内容
# 代理邮件 - 从 AI 代理发送实体邮件
一个用于实体邮件的开放 MCP 服务器。使用 PostalForm 创建可审查的邮件草稿、托管的结账会话、仅验证报价和明确批准的代理可付邮件，通过 MPP（机器支付协议）或 x402 实体邮件。
本仓库是参考实现和示例包，用于诸如“从 AI 代理发送实体邮件”、“用于实体邮件的 MCP 服务器”、“代理可付邮件”、“x402 实体邮件”、“使用 x402 支付邮件”和“MPP 邮件”等术语。
## 快速开始
运行本地的标准输入输出 MCP 服务器：
```bash
npm install
npm run server
```
或配置 MCP 客户端以在发布后从 npm 运行：
```json
{
"mcpServers": {
"agent-mail": {
"command": "npx",
"args": ["-y", "@postalform/agent-mail-mcp"]
}
}
}
```
本地服务器暴露了安全的代理邮件工具：
| 工具 | 目的 | 副作用 |
| --- | --- | --- |
| `agent_mail_discovery` | 返回 PostalForm MCP、OpenAPI、x402、A2A 和文档网址 | 只读 |
| `list_postalform_tools` | 列出在线的 PostalForm 远程 MCP 工具 | 只读 |
| `validate_letter_mail` | 验证和报价一个字母机器订单载荷 | 无支付、打印或邮寄 |
| `create_letter_checkout_draft` | 创建一个未付的托管结账草稿 | 在结账被审查和支付之前不会发送邮件 |
## 远程 PostalForm MCP
如果您的客户端支持远程流式 HTTP MCP 服务器，您可以直接连接：
```text
https://postalform.com/mcp
```
对于大多数代理，默认模式应该是：
```text
草稿 -> 预览 -> 批准/支付 -> 发送 -> 跟踪
```
托管结账是聊天式助手的安全默认选项，因为所有者在 PostalForm 打印或邮寄实体邮件之前会审查 PDF、发件人、收件人、邮寄选项和价格。本地 `confirm_create_unpaid_draft` 标志是创建未付草稿的软客户端保护措施，而不是人类支付批准的证明。
## 支付前验证
在发送邮件之前验证机器订单载荷：
```bash
POSTALFORM_VALIDATE_EXAMPLE=1 npm run rest:validate-letter
```
直接 MPP（机器支付协议）或 x402 机器支付仅在运行时已经具有明确的所有者批准、支出限制和重试安全的请求 ID 时使用。
## 示例
| 路径 | 示范内容 |
| --- | --- |
| [examples/01-claude-mcp](examples/01-claude-mcp) | Claude Desktop 和 Claude Code 设置本地代理邮件 MCP 服务器 |
| [examples/02-send-a-letter](examples/02-send-a-letter) | 为一封信创建未付的 PostalForm 结账草稿 |
| [examples/03-x402-paywalled-send](examples/03-x402-paywalled-send) | 先验证后支付的 x402 和 MPP 机器订单载荷 |
| [examples/04-langchain-tool](examples/04-langchain-tool) | 将 PostalForm 验证包装为 LangChain 样式的工具 |
| [examples/05-openai-responses-mcp](examples/05-openai-responses-mcp) | OpenAI Responses API 远程 MCP 配置 |
## 发现
标准 PostalForm 网址：
| 字段 | 网址 |
| --- | --- |
| MCP 端点 | `https://postalform.com/mcp` |
| 开发者文档 | `https://postalform.com/developers` |
| 代理指南 | `https://postalform.com/agents` |
| OpenAPI | `https://postalform.com/openapi.json` |
| MCP 注册表清单 | `https://postalform.com/.well-known/mcp/server.json` |
| MCP 服务器卡 | `https://postalform.com/.well-known/mcp/server-card.json` |
| A2A 代理卡 | `https://postalform.com/.well-known/agent-card.json` |
| x402 发现 | `https://postalform.com/.well-known/x402` |
| LLM 概述 | `https://postalform.com/llms.txt` |
运行实时发现检查：
```bash
npm run check:discovery
```
## 仓库地图
| 路径 | 目的 |
| --- | --- |
| [src/server.mjs](src/server.mjs) | 用于代理邮件发现、验证和未付结账草稿的本地标准输入输出 MCP 服务器 |
| [.well-known/mcp.json](.well-known/mcp.json) | 仓库级别的 MCP 发现描述符 |
| [manifest/mcp-server.json](manifest/mcp-server.json) | 目录就绪的本地 MCP 服务器描述符 |
| [manifest/x402-payment.json](manifest/x402-payment.json) | x402 实体邮件支付描述符 |
| [docs/quickstart.md](docs/quickstart.md) | 首次运行指南 |
| [docs/tools-reference.md](docs/tools-reference.md) | 工具行为和副作用参考 |
| [docs/machine-payments.md](docs/machine-payments.md) | MPP 和 x402 指南 |
| [docs/compliance.md](docs/compliance.md) | 滥用、隐私和批准指南 |
| [docs/directory-listing.md](docs/directory-listing.md) | 复制粘贴目录列表字段 |
## 目录就绪摘要
PostalForm 是一个远程 MCP 服务器和用于 AI 代理的实体邮件 API。代理可以从 PDF、文本、HTML、Markdown、RTF 或表单载荷创建可审查的邮件草稿、返回托管结账以供人类批准，或使用所有者批准的 MPP/x402 机器支付流程来支付和跟踪实体邮件。
## 安全默认值
- 优先使用托管结账进行聊天式代理。
- 在共享私人文档、地址或支付凭证之前需要批准。
- 为直接机器支付重试使用稳定的 `request_id` 值。
- 在支付前显示可用的 PDF 预览。
- 在模型提示之外强制执行支出限制。
- 不要将 PostalForm 用于垃圾邮件、骚扰、非法内容、支票、密钥、包裹、公证、服务过程或法律建议。
## 维护者
由 PostalForm 和 Gabriel Garrett（[`ggaabe`](https://github.com/ggaabe)）维护，Gabriel Garrett 还维护 [`rrule-temporal`](https://www.npmjs.com/package/rrule-temporal)。
## 许可证
MIT
