# PostBridge Agent Plugin

Postal execution layer for AI agents: **quote, send, track, and prove physical
letters** from any agent that supports the [Agent Plugins](https://agent-plugins.org)
open standard.

PostBridge turns a PDF (or generated document) into a physically mailed letter
through print-and-mail providers, with carrier tracking and delivery proof.
This plugin gives your AI agent that capability via PostBridge's hosted MCP
server plus a set of Agent Skills playbooks.

> Built on the [Agent Plugins specification](https://agent-plugins.org/specification)
> v1.0.0 — a portable package format for Agent Skills and MCP servers.

## What's inside

| Component | Location | Purpose |
|---|---|---|
| `plugin.json` | root | Plugin manifest (name `postbridge`, v0.1.0) |
| `mcp.json` | root | Remote MCP server → `https://api.postbridge.ai/mcp` (Streamable HTTP) |
| `skills/send-letter` | skills/ | Quote → confirm → send workflow, with 5-country address rules |
| `skills/track-and-proof` | skills/ | Track mailed letters, retrieve delivery proof |
| `skills/wallet` | skills/ | Workspace wallet balance and top-up |

### MCP tools exposed

`list_services`, `get_quote`, `send_letter`, `track_letter`, `get_proof`,
`get_balance`, `top_up_wallet`, `list_letters`.

## Setup

This repository doubles as a Copilot CLI plugin **marketplace** — users can
register it and install the plugin in one step:

```shell
copilot plugin marketplace add PostbridgeAI/postbridge-agent-plugin
copilot plugin install postbridge@postbridge-plugins
```

Or install directly from the repository / a local path with any Agent
Plugins-compatible client.

PostBridge's MCP endpoint is **subscription-backed and API-key authenticated**.
The plugin ships no credentials — your client injects the key.

1. Create a workspace at [postbridge.ai](https://postbridge.ai).
2. Generate an **API & MCP key** in *Settings → API & MCP* (subscription-backed;
   usage consumes the workspace wallet).
3. Install this plugin in your Agent Plugins-compatible client and configure the
   `Authorization: Bearer <your-key>` header / credential for the `postbridge`
   MCP server.

Per-client notes:

- **Cursor** — install the plugin, then add your key as a plugin variable /
  MCP header under *Plugins → Configure*.
- **GitHub Copilot CLI** — `copilot plugin install` from this repo or a
  marketplace entry, then set the MCP credential.
- **Codex / ChatGPT** — connect the MCP server and supply the Bearer key in the
  auth step.

## Safety model

- **Spend is explicit.** `send_letter` and `top_up_wallet` move real money; the
  skills require explicit user confirmation of address, content, service, and
  price before any spend.
- **Server-side auth is fail-closed.** The hosted MCP accepts only a
  subscription-backed SaaS API & MCP key (no UCAN/browser/x402/legacy keys).
- **No secrets in the package.** The API key is never stored in `plugin.json`,
  `mcp.json`, `env`, or headers.
- **No fabricated proof.** Tracking states and delivery proof are reported only
  as returned by the carrier.

## Address support

The `send-letter` skill bundles a 5-country address reference (US, CA, FR, GB,
DE) distilled from PostBridge's deterministic address parser. For other
countries, the agent asks the user to confirm layout rather than guess.

## Links

- PostBridge — https://postbridge.ai
- Agent Plugins standard — https://agent-plugins.org
- Model Context Protocol — https://modelcontextprotocol.io
- Agent Skills specification — https://agentskills.io/specification

## License

MIT — see [LICENSE](LICENSE).