# 夏天pay全球通 MCP Server · xiatian-pay-mcp

让 AI 助手（Trae / Cursor / Claude Desktop / Dify / Coze 等任何 MCP 客户端）一句话完成**微信支付 V3**与**支付宝**的签名、下单、回调验签。零依赖、纯本地运行、不触碰任何资金。

> 合规定位：本工具是**开发者技术工具**，只生成签名/请求与校验回调；资金始终在商户自己的微信/支付宝商户号内结算，本工具不参与资金清算（无「二清」）。

## 能力（11 个工具）

| 工具 | 作用 | 是否联网 |
|---|---|---|
| `wechat_build_authorization` | 离线生成微信 V3 Authorization 签名头 | 否 |
| `wechat_create_native_order` | Native 扫码下单，返回 `code_url` | execute=true 时联网 |
| `wechat_create_jsapi_order` | JSAPI/小程序下单，返回 wx.invoke 调起参数 | execute=true 时联网 |
| `wechat_verify_callback` | 微信异步通知 RSA-SHA256 验签 | 否 |
| `wechat_decrypt_callback` | 回调 resource AES-256-GCM 解密 | 否 |
| `alipay_sign_params` | 支付宝 RSA2 参数签名 | 否 |
| `alipay_precreate` | 当面付预下单，返回 `qr_code` | execute=true 时联网 |
| `alipay_build_pay_url` | 电脑网站/手机网站支付跳转链接 | 否 |
| `alipay_verify_notify` | 支付宝异步通知验签 | 否 |
| `platform_create_order` | 托管平台免凭证建单（可选 SaaS） | 是 |
| `platform_query_order` | 托管平台查单 | 是 |

## 安装与接入

要求 Node.js ≥ 18。

```bash
npm install -g xiatian-pay-mcp   # 发布后；当前可直接用源码目录
```

MCP 客户端配置（Trae / Claude Desktop 等的 mcp.json）：

```json
{
  "mcpServers": {
    "xiatian-pay": {
      "command": "npx",
      "args": ["-y", "xiatian-pay-mcp"],
      "env": {
        "XIATIAN_WX_MCHID": "1900000001",
        "XIATIAN_WX_APPID": "wxxxxxxxx",
        "XIATIAN_WX_CERT_SERIAL": "证书序列号",
        "XIATIAN_WX_PRIVATE_KEY_PATH": "C:/certs/apiclient_key.pem",
        "XIATIAN_WX_PLATFORM_CERT_PATH": "C:/certs/wx_platform_cert.pem",
        "XIATIAN_WX_APIV3_KEY": "32位APIv3密钥",
        "XIATIAN_ALIPAY_APPID": "2021000000000001",
        "XIATIAN_ALIPAY_PRIVATE_KEY_PATH": "C:/certs/alipay_app_private.pem",
        "XIATIAN_ALIPAY_PUBLIC_KEY_PATH": "C:/certs/alipay_public.pem",
        "XIATIAN_PLATFORM_URL": "https://pay.your-domain.com",
        "XIATIAN_API_KEY": "托管平台API密钥(可选)"
      }
    }
  }
}
```

- 所有环境变量均可省略，改为调用工具时在 `cred` 参数内传入（PEM 全文或 .pem 文件路径均可）。
- 建议生产环境用环境变量/文件路径，避免密钥出现在对话上下文中。

## 使用示例（对 AI 说的话）

- 「帮我生成微信 Native 扫码下单请求，订单号 T1001，金额 199.00 元，商品‘降噪耳机’，回调 https://example.com/cb」
- 「这是微信回调的 headers 和原始 body，帮我验签并解密 resource」
- 「用支付宝当面付给订单 A20260916001（9.9 元）生成二维码链接，沙箱环境」
- 「生成支付宝电脑网站支付跳转链接，return_url 是 https://example.com/ok」
- 「校验这段支付宝异步通知的签名是不是真的」

## 测试

```bash
node test/run-tests.js
```

内置 32 项协议级测试：MCP 握手/工具清单/真实 RSA 签名验签/篡改检测/AES-GCM 加解密闭环/离线下单构造/错误处理，全部离线可跑。

## 凭证准备指引

- 微信支付：pay.weixin.qq.com → 账户中心 → API 安全 → 设置 APIv3 密钥、申请 API 证书（apiclient_key.pem + 证书序列号）；平台证书通过 `/v3/certificates` 获取；另需已开通 Native/JSAPI 产品与 AppID。
- 支付宝：open.alipay.com → 创建网页/移动应用 → 用密钥工具生成 RSA2 密钥对，上传应用公钥，保存支付宝公钥；签约当面付/电脑网站/手机网站支付；沙箱网关自动支持。

## 安全与边界

- 本项目不存储、不上传任何商户密钥；除显式下单工具外全部离线计算。
- 不提供资金代收、代付、清算能力；不持有支付牌照，不做「二清」。
- 商户需自行承担微信/支付宝平台资质、ICP、税务合规义务。

## License

MIT