Alternative Payments

Alternative Payments MCP 服务

一个 Model Context Protocol (MCP) 服务，为 AI 助手提供对 Alternative Payments 的读取和安全写入权限，包括客户、发票、付款请求、交易、付款和 Webhook。

由 Wyre Technology 维护。

功能

此服务刻意不转移资金。它提供读取和安全写入功能 （创建客户、发票和托管付款链接）。它不实现 直接创建付款（POST /payments），因为该操作会向银行卡或银行账户扣款。

三个具有破坏性的工具——ap_archive_customer、ap_archive_invoice、 ap_delete_webhook——运行前都需要交互式确认。

领域	工具
客户	ap_list_customers、ap_get_customer、ap_list_customer_users、ap_create_customer、ap_add_customer_user、ap_archive_customer ⚠
发票	ap_list_invoices、ap_get_invoice、ap_get_invoice_payment_link、ap_get_invoice_pdf_link、ap_create_invoice、ap_create_payment_request、ap_get_payment_request、ap_archive_invoice ⚠
付款	ap_list_transactions、ap_get_transaction、ap_list_payouts、ap_get_payout、ap_list_payout_transactions
Webhook	ap_list_webhooks、ap_list_webhook_events、ap_create_webhook、ap_retry_webhooks、ap_delete_webhook ⚠

此外还有发现工具 ap_navigate 和 ap_status。

身份验证

Alternative Payments 使用 OAuth 2.0 客户端凭据。在 Partner Dashboard 中生成 API 密钥 （client_id / client_secret）。

复制 .env.example。stdio 传输会读取这些变量，且不会使用 CONDUIT_S2S_SECRET：

• ALTERNATIVE_PAYMENTS_CLIENT_ID
• ALTERNATIVE_PAYMENTS_CLIENT_SECRET
• ALTERNATIVE_PAYMENTS_ENVIRONMENT（production 或 demo，默认为 production）

服务会自动用这些凭据换取 bearer token，并在令牌过期前刷新。

HTTP 服务到服务身份验证

当 MCP_TRANSPORT=http 时，必须设置 CONDUIT_S2S_SECRET。如果该值为空，或为已知占位符（changeme、your-s2s-secret、secret、placeholder 及其他示例值），进程会记录错误并以非零状态退出。它绝不会打印该密钥。未设置此变量时，Compose 不会启动。

仅在本地开发时设置 MCP_ALLOW_INSECURE_DEV=1，即可在不配置密钥的情况下启动。进程会记录醒目的警告，不会检查 X-Gateway-S2S，且只绑定到 127.0.0.1。在此模式下，非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录此覆盖操作。占位符密钥仍会被拒绝。

设置了真实的 CONDUIT_S2S_SECRET 时，系统会采用 MCP_HTTP_HOST。如果未设置 MCP_HTTP_HOST，服务会保留原有默认值并绑定到 0.0.0.0。容器镜像和 Compose 会设置 0.0.0.0 和 AUTH_MODE=gateway。除非前面有代理，否则请将端口发布到环回地址。

使用真实密钥时，每个 /mcp 请求都必须包含：

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对 ASCII 字符串 t=<unix seconds> 计算的十六进制 HMAC-SHA256 值，密钥为 CONDUIT_S2S_SECRET。时间戳必须与服务器时钟相差不超过 300 秒。缺少或无效的请求头会在读取厂商凭据前返回 401。

网关模式（AUTH_MODE=gateway）

每个 /mcp 请求还必须包含：

• X-Alternative-Payments-Client-ID
• X-Alternative-Payments-Client-Secret
• X-Alternative-Payments-Environment（可选：production 或 demo）

如果请求缺少客户端 ID 或密钥，将返回 401，且不会回退使用进程环境中的 ALTERNATIVE_PAYMENTS_CLIENT_ID / ALTERNATIVE_PAYMENTS_CLIENT_SECRET。仓库中提供的 Compose 服务不会设置静态厂商凭据。

单租户 HTTP（AUTH_MODE=env）

/mcp 仍需要有效的 X-Gateway-S2S 标头。如果请求未携带 client-id 和 client-secret 标头，则供应商凭据来自 ALTERNATIVE_PAYMENTS_* 环境变量。

/health 始终返回 200。它不需要身份验证，也不会读取供应商凭据。

快速开始

Claude Code（CLI）：

claude mcp add alternative-payments \
  -e ALTERNATIVE_PAYMENTS_CLIENT_ID=your-client-id \
  -e ALTERNATIVE_PAYMENTS_CLIENT_SECRET=your-client-secret \
  -- npx -y github:WYRE-AI/alternative-payments-mcp

Docker（HTTP 传输，网关模式）：

镜像会在容器内监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，Alternative Payments 凭据会作为标头随每个请求传入；不会从环境中读取这些凭据。

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  ghcr.io/wyre-ai/alternative-payments-mcp:latest

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，并且不会注入静态供应商凭据：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

网关会为每次 /mcp 调用签名：

t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS -X POST http://127.0.0.1:8080/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${sig}" \
  -H "X-Alternative-Payments-Client-ID: $ALTERNATIVE_PAYMENTS_CLIENT_ID" \
  -H "X-Alternative-Payments-Client-Secret: $ALTERNATIVE_PAYMENTS_CLIENT_SECRET" \
  -H "X-Alternative-Payments-Environment: production" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，随后使用 ALTERNATIVE_PAYMENTS_CLIENT_ID 和 ALTERNATIVE_PAYMENTS_CLIENT_SECRET。这与网关 Compose 服务相互独立：

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ALTERNATIVE_PAYMENTS_CLIENT_ID="$ALTERNATIVE_PAYMENTS_CLIENT_ID" \
  -e ALTERNATIVE_PAYMENTS_CLIENT_SECRET="$ALTERNATIVE_PAYMENTS_CLIENT_SECRET" \
  ghcr.io/wyre-ai/alternative-payments-mcp:latest

不使用密钥的本地 HTTP 仅用于开发。它会绑定到 127.0.0.1 并记录警告：

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

传输方式

• stdio（默认）：node dist/index.js。不使用 CONDUIT_S2S_SECRET。
• HTTP（MCP_TRANSPORT=http）：在 MCP_HTTP_PORT（默认值为 8080）上提供可流式 HTTP， 并提供 /mcp 和 /health 端点。每个请求都会创建一个全新的无状态服务， 这是 WYRE MCP Gateway 所必需的。除非设置 MCP_ALLOW_INSECURE_DEV=1， 否则启动时必须先确认 CONDUIT_S2S_SECRET 是真实密钥，才会开始监听。

开发

npm install
npm run build
npm test
npm run lint

许可证

Apache-2.0