3LT Letter Mail

3LT Letter Mail — MCP 服务

为你的 AI 助手装上双手。3L-Group Technology 是一条打印与邮寄通道： AI Agent 调用我们的 MCP 工具，一封真实的纸质信件便会通过美国邮政寄出， 或一份真实的传真会送达一台真实的传真机。在聊天中起草并批准，即可寄出或发送—— 无需打印、准备信封、跑邮局，也无需自备传真机。

🌐 https://3lgrouptechnology.com 📇 官方 MCP 注册表：com.3lgrouptechnology/3lt-letter-mail（参见 server.json）

使用托管服务（无需设置）

公共 MCP 端点已上线：

https://3lgrouptechnology.com/mcp

传输方式：流式 HTTP。身份验证：每次调用工具时，都将 API 密钥作为 api_key 参数传入。在 3lgrouptechnology.com 获取 API 密钥。

从 Claude 连接

Claude（claude.ai）支持自定义 MCP 连接器：添加一个新连接器，并使用上面的 服务 URL。助手调用工具时，会将你的 lms_... API 密钥作为 api_key 参数传入。 （服务不会看到你的 Claude 账户——密钥是唯一的凭据。）

从 Cursor 连接

设置 → MCP → 添加自定义 MCP 服务：

{
  "mcpServers": {
    "3lt-letter-mail": {
      "url": "https://3lgrouptechnology.com/mcp"
    }
  }
}

从任意 MCP 客户端连接

任何支持流式 HTTP 的客户端都可以使用：将其指向 https://3lgrouptechnology.com/mcp，并在每次调用工具时提供 API 密钥。

获取 API 密钥

密钥（lms_...）由服务签发——密钥只会显示一次， 因此显示时请妥善保存。有两种方式：

• 自助服务（Connect） — 打开 https://3lgrouptechnology.com/connect（或 让你的助手调用 POST /v1/connect）。在 Stripe 托管的表单（/billing 页面 使用的机制）中保存付款方式，确认每月上限，然后完成授权：服务会签发一个 绑定该上限的 on_command 密钥。这项授权是长期有效的批准——在上限内发送 无需逐次提示批准。
• 管理员签发 — 操作员使用 POST /v1/keys （X-Admin-Token）创建密钥。这类密钥初始处于 approval 层级：每次发送 都需要人工点击“允许”，直到操作员更改层级。

无论哪种方式，密钥的风险等级都从 L0（每月上限 $50）开始；良好的使用记录 会自动提高限额，而达到每月上限时会立即停止，绝不会悄然超额收费。

工具

工具	功能
draft_letter	创建信件草稿：验证收件人地址、筛查内容并返回价格报价。**绝不会寄出任何内容。**接受 html（信件正文）或 pdf_path（服务端本地 PDF）。选项：color、quantity（批量数量）、certified（可选 USPS Certified Mail + Electronic Return Receipt——默认使用标准 First-Class 邮寄）。
request_send	请求寄出信件草稿。approval 层级的密钥会收到一个 PENDING 请求，以及一个可一键点击的允许/拒绝链接——在人工点击“允许”之前不会寄出任何内容。可信的 on_command 密钥可在防护规则内自动发送（支出上限、内容筛查、异常检测）。
send_status	查询发送请求：状态（PENDING / SENT / REJECTED / FAILED）、批准状态、信任层级判定和账单状态。
create_fax_draft	使用服务端本地 PDF 创建传真草稿：验证收件人传真号码、统计页数、筛查内容并返回价格报价。绝不会传送任何内容。
approve_fax	批准传真草稿，使其可以传送。批准时会重新筛查内容。此操作本身不会传送任何内容。
send_fax	通过 Phaxio 传送一份已批准的传真。会拒绝未批准的草稿和已发送的传真——一份传真只会传送一次。
get_fax_status	查询传真：生命周期状态（DRAFT / APPROVED / SENT / FAILED）、页数、报价、账单状态，以及发送后 Phaxio 的实时送达状态。

没有任何工具可以直接寄出信件或发送传真。每次发送都必须经过批准记录： 人工点击，或 Connect 的长期授权。传真要求更严格：始终必须调用 approve_fax—— 即使使用 on_command 密钥，也不存在无需提示的传真发送方式。

定价

每封信收取固定 $1.00 服务费，另加邮费（通过我们的打印和邮寄服务提供商使用 USPS First-Class）。价格统一，不分档，也不玩批量定价。挂号信（附电子回执）可选，费用更高——绝不会作为默认选项。

传真： 计费方式同样固定——Phaxio 按页收费（约 $0.07/页）乘以页数，另加每份传真 $0.50 服务费（每份传真只收一次，不按页收取）。一页传真在处理费上浮前的报价为 $0.57；发送时，客户的银行卡会被收取上浮后的总额，与信件完全相同。

示例：“把我的 2026 年 1099 寄给这 40 个人” → 你的助手会针对每位收件人依次调用 draft_letter → request_send → send_status。批量发送会在每月限额内自动发送；任何被标记的项目都会改为使用一键“允许/拒绝”链接。每次发送都会生成一份明细收据。

---

自托管

想使用自己的通道？完整技术栈就在这个仓库中。

快速入门

./quickstart.sh

创建 .venv、安装依赖、运行测试套件，并在 http://127.0.0.1:8000 启动 REST API（仪表板位于 /）。

如果没有设置 POSTGRID_API_KEY，草稿会在地址验证阶段安全失败——不会寄出任何东西。设置一个测试密钥，即可通过模拟发送体验完整流程：

POSTGRID_API_KEY=test_... LMS_ADMIN_TOKEN=pick-a-secret ./quickstart.sh

MCP 服务（在单独的终端中）：

POSTGRID_API_KEY=test_... .venv/bin/python mcp_server.py
# MCP endpoint: http://127.0.0.1:8001/mcp

仓库内容

• MCP 服务（mcp_server.py）——通过可流式传输的 HTTP 提供以上 7 个工具。
• REST API（api.py，FastAPI）——面向 Agent 的端点（X-API-Key），用于草稿、发送请求和传真生命周期（POST /v1/faxes → /{id}/approve → /{id}/send，GET /v1/faxes/{id}）；管理端点（X-Admin-Token）用于签发密钥、批准／拒绝发送、管理信任等级和 支出上限；客户仪表板（/customer）、审批仪表板（/）、审计历史记录、Stripe Webhook。静态发现文档通过以下地址提供：/.well-known/oauth-authorization-server、/.well-known/oauth-protected-resource （准确的 API 密钥元数据——未部署 OAuth），以及 /.well-known/mcp/server-card.json（Smithery 静态服务卡片）。
• 传真通道（phaxio_client.py，Phaxio API v2.1）——传真草稿会像信件一样经过验证、页数统计、筛查和报价；发送时使用与信件相同的计费引擎（tlt_billing.settle_fax）：根据信件和传真合并计算的支出检查风险上限，先对银行卡进行预授权 → 发送传真 → 扣款（若传输失败则撤销预授权），并开具明细收据。
• 信任等级（按 API 密钥设置）——approval（管理员签发密钥的默认等级：每次发送都需人工确认）或 on_command（受信任：在防护规则内自动发送——每次发送都进行内容筛查，设置单次和每日支出上限、硬性月度上限、超过 7 天基准值 3 倍的异常规则，以及 needs_review 回退机制）。所有决策都会记录在审计日志中。
• 一次性通道授权（“Connect”）——POST /v1/connect 会创建 Stripe 客户，并返回一个 /connect/<token> 页面（通过 Payment Element 支持银行卡／Apple Pay／Google Pay，并确认月度上限）。完成后会签发一个关闭单次发送审批的 on_command API 密钥——单次 Connect 授权即为持续授权，因此在上限范围内发送时不会出现任何提示。达到月度上限时会硬性返回 402 “提高你的上限”——绝不会悄悄超额扣款。
• 计费（Stripe）——使用 SetupIntents 保存付款方式；每次审批时，离线执行 预授权 → 履行 → 扣款（若发送失败则撤销预授权），并为每次发送设置幂等密钥。 信件和传真共用一个引擎（共享 tlt_billing 模块中的 settle / settle_fax）。⚠️ 此构建的计费模块拒绝非测试 Stripe 密钥——真实客户扣款需要先解除测试模式限制（参见 DEPLOY.md 中的待解决问题）。
• 风险引擎——支出限额根据风险计算，而非固定不变。新密钥从 L0（每月 $50）起步；良好的历史记录会自动提高限额；标记、付款失败和拒付会收紧或冻结密钥。每项决策都会记录在审计日志中，并附上易读的原因。参见 risk.py。
• 滥用筛查——内容拦截名单会在起草时以及审批／履行时再次检查。
• 存储——SQLite（db.py）：api_keys、drafts、send_requests、faxes、billing_receipts、approval_tokens、connect_sessions、audit_log。

环境变量

变量	必填	默认值	用途
POSTGRID_API_KEY	是，发送邮件时必填	—	PostGrid Print & Mail API 密钥。test_... = 模拟发送，不会寄出邮件。正式密钥 = 真实邮件（除非 ALLOW_LIVE_MAIL=1，否则会被拒绝）。切勿提交此密钥。
LMS_ADMIN_TOKEN	建议填写	随机生成，启动时仅打印一次	用于审批和签发密钥的管理员令牌（X-Admin-Token）。
LMS_DB_PATH	否	./lms.db	SQLite 文件位置。
POSTGRID_BASE_COST_USD	否	0.97	报价中使用的 PostGrid 单封邮件预估基础费用。
POSTGRID_AV_API_KEY	否	—	PostGrid 地址验证密钥；未设置时使用 POSTGRID_API_KEY。
MAIL_PROVIDER	否	postgrid	postgrid 或 lob（旧版回退选项）。
PHAXIO_API_KEY / PHAXIO_API_SECRET	传真时必填	—	Phaxio API 凭据。test_... = 模拟发送。除非 ALLOW_LIVE_FAX=1，否则会拒绝正式凭据。留空则仅运行邮件寄送功能。切勿提交这些凭据。
ALLOW_LIVE_FAX	否	未设置	设为 1 以允许使用正式 Phaxio 凭据（发送真实传真，并产生实际的逐页费用）。
PHAXIO_PER_PAGE_USD	否	0.07	传真报价中使用的 Phaxio 逐页预估费用。
LMS_MCP_HOST / LMS_MCP_PORT	否	127.0.0.1 / 8001	MCP 服务绑定地址。
STRIPE_SECRET_KEY	账单功能必填	—	测试密钥（sk_test_...）。不接受非测试密钥。
STRIPE_PUBLISHABLE_KEY	/billing 必填	—	Payment Element 页面使用的可发布密钥。
STRIPE_WEBHOOK_SECRET	Webhook 必填	—	用于 POST /v1/webhooks/stripe 的签名密钥。
APPROVAL_TOKEN_SECRET	建议填写	临时密钥（重启后失效）	用于单击“允许/拒绝”链接的 HMAC 密钥。
PUBLIC_BASE_URL	审批链接必填	请求 URL	嵌入审批链接中的公共基础 URL。
TLT_MAILER_BACKEND	否	log	log 会将收据写入 TLT_RECEIPTS_DIR（不会发送电子邮件）。
TLT_RECEIPTS_DIR	否	./receipts	明细收据文件的写入位置。
LMS_UPLOADS_DIR	否	./uploads	上传 PDF 的存储位置（按草稿分别存放在目录中）。
LMS_MAX_PDF_BYTES	否	10485760	PDF 上传大小上限，单位为字节。

将 .env.example 复制为 .env，并填写真实值。切勿提交 .env。

运行测试

.venv/bin/python test_pricing.py
.venv/bin/python test_api_flow.py       # PostGrid calls stubbed, no network
.venv/bin/python test_billing_tiers.py  # Stripe mocked, no network
.venv/bin/python test_pdf.py            # PDF upload + flow, no network
.venv/bin/python test_risk.py
.venv/bin/python test_customer_dashboard.py
.venv/bin/python test_certified.py      # certified-mail pricing + flow
.venv/bin/python test_grossup.py        # billing gross-up math
.venv/bin/python test_rail.py           # Connect rail authorization flow
.venv/bin/python test_fax.py            # Phaxio stubbed, no network
.venv/bin/python test_fax_billing.py    # fax settle/caps/pooling, Stripe mocked
.venv/bin/python test_server_card.py    # /.well-known/mcp/server-card.json

部署说明

请参阅 DEPLOY.md — 部署当晚的逐步操作手册（通过 ./deploy.sh 使用 Docker Compose、环境变量检查清单、共享库发布步骤，以及部署后的验证探测）。

安全说明

• 除 core.approve_send 外，没有任何代码路径会调用 mail_provider.create_letter。该函数要求请求处于 PENDING 状态，并由人工管理员执行操作。MCP 工具无法发送邮件。
• 唯一的传真发送路径是 core.send_fax。传真必须处于 APPROVED 状态（必须先明确调用 approve_fax），并且会在发送前进行扣款——如果银行卡扣款被拒，传真就不会发送。
• postgrid_client 设置了 trust_env=False，因此 API 密钥绝不会通过环境中的代理变量传输。
• API 密钥以 SHA-256 哈希形式存储；签发时原始密钥仅显示一次。