@payretailers/mcp

面向 PayRetailers 支付 API 的官方 Model Context Protocol (MCP) 服务器。

将任何兼容 MCP 的 AI 助手变成 PayRetailers 集成专家。此服务器将官方指南、战术技能、端点参考和集成工具（搜索、国家特定验证、Webhook 操作手册）作为一流的 MCP 资源、工具和提示词公开。

适用于 Cursor、Claude Desktop、Claude Code、Windsurf、Antigravity、Zed、VS Code + Copilot、JetBrains IDEs、Continue.dev、Cline 以及任何其他通过 stdio 支持 MCP 的客户端。

为什么使用它

安装此服务器后，你的 AI 助手将不再猜测 PayRetailers 的相关信息，而是在每一步都查阅权威来源。

• 首次尝试即获得正确代码。 助手会读取每个端点的真实 OpenAPI 结构（get_endpoint_spec），因此生成的代码使用实际的字段名、类型和必填组合——而不是从其他 PSP 借用的内容。

• 从一开始就具备国家感知。 询问 PIX 付款，助手会知道 PIX 仅限巴西，期望使用 BRL，需要有效的 11 位 CPF，并且二维码过期很快。询问 SPEI，它会知道墨西哥需要 CURP 或 RFC、MXN，并且 CLABE 是异步配置的。所有这些都由 get_country_rules 提供支持。

• 在进入沙箱之前验证负载。 validate_payload 对 CPF、CNPJ、RUT、DNI、RUC、CC、NIT、CURP、RFC、CLABE 执行真实的校验和验证——以及跨领域规则（整数最小货币单位、HTTPS 通知 URL、货币/国家匹配、方法/国家兼容性、幂等键、客户必填字段矩阵、订阅 AmountModel 形状、PIX Automático 重试契约）。你在编辑器中捕获错误，而不是在 400 INVALID_MODEL_SCHEMA 响应中。

• 正确设计的 Webhook 接收器。 get_webhook_playbook 返回规范的事件词汇表、重试策略和签名/重放契约。validate_webhook_handler 在编写任何接收器代码之前捕获六种最具破坏性的反模式（处理后确认、缺少 eventId 去重、业务错误作为 500、生产环境中禁用签名、依赖时钟顺序的假设、缺少 HTTPS）。

• 针对复杂流程的斜杠命令提示词。 输入 /integrate-pix-payin、/integrate-subscriptions、/implement-webhook-handler、/integrate-payout-fx、/build-checkout、/debug-401-auth 或 /reconcile-with-graphql，即可获得所选技术栈中的生产级实现。

• 零配置、零网络、离线友好。 所有内容都打包在发布 zip 中。无需账户、无需 API 密钥、无需出站调用即可回答文档相关问题。仅当使用（计划中的）simulate_transaction 工具时才需要凭据。

在底层，你有 7 个工具、7 个提示词、158 个文档资源（指南 + 技能 + 参考 + 配方 + 概念文档），全部从 payretailers-ai-docs 仓库逐字镜像。

Related MCP server: Payman AI Documentation MCP Server

它暴露了什么

资源

对 PayRetailers 文档的结构化、LLM 友好的访问。

完整列表在连接时动态公布——客户端可以通过其资源选择器浏览。

工具

LLM 可以调用而不是猜测的操作。

提示词

开发者可以在 Cursor / Claude Desktop 等中使用 / 选择的现成模板。

安装

两种受支持的路径。选择一种：

• 选项 A — 从 GitHub Releases 下载预构建 zip（目前推荐）：无需 npm 账号，无需编译，下载后即可完全离线使用。在 @payretailers/mcp 尚未发布到 npm 之前，这是官方支持的发行方式。

• 选项 B — 从源码构建：适用于贡献者以及希望在运行前审计代码的安全敏感型部署。

选项 C — 通过 npm 安装为 @payretailers/mcp — 已规划但尚未可用。当该包发布后，按客户端配置 一节中的 npx -y @payretailers/mcp 片段将开箱即用。

选项 A — 从 GitHub Releases 安装

前置条件：Node.js 20 或更高版本（node --version）。其他无需任何安装 — 发布 zip 是自包含的。

1. 打开 Releases 页面，从顶部 release 的 "Assets" 部分下载最新的 payretailers-mcp-vX.Y.Z.zip。

2. 将其解压到任意位置。常见位置：

   • Windows：C:\Tools\payretailers-mcp

   • macOS / Linux：~/tools/payretailers-mcp

3. 将服务器添加到你的 MCP 客户端（参见下方的 按客户端配置，或该处链接的分步指南）。将其指向解压文件夹内 dist/index.js 的绝对路径。

4. 重新加载 / 重启你的 MCP 客户端。服务器将与其他工具一起显示。

带截图和验证提示的分步设置指南：

• Cursor

• Claude Code CLI

• Claude Desktop

• VS Code + GitHub Copilot

可选的在接入前后进行的冒烟检查 — 用于证明该 bundle 端到端健康：

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

预期结果：末尾显示 PASS ✅，并宣告 7 个工具、158 个资源、7 个提示词、5 个资源模板。

选项 B — 从源码构建

适用于贡献者，或如果你的安全策略要求在运行前审计代码。前置条件：Node.js 20 或更高版本、git。

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/（Guides、Skills、Reference、Recipes、概念文档、精选 JSON）已纳入版本控制 — 除非你需要在同一台机器上镜像更新的 payretailers-ai-docs 检出，否则无需运行 npm run sync:docs。

然后按照选项 A 的相同方式将 dist/index.js 接入你的 MCP 客户端。

按客户端配置

更倾向于带验证提示和故障排查的完整演练？请参阅 docs/setup/ 中针对 Cursor、Claude Code、Claude Desktop 和 VS Code + Copilot 的分步指南。如果你已经熟悉你的客户端，下面的片段是所需的最简 JSON。

每个客户端都接收相同三条信息：command（node）、指向 dist/index.js 绝对路径的 args 数组，以及为将来的 simulate_transaction 工具准备的可选 env 块。

将下面的 C:/Tools/payretailers-mcp/dist/index.js 替换为你解压 release 的绝对路径。在 Windows 上，JSON 中请使用正斜杠 — 反斜杠需要转义，且会导致令人困惑的错误。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）：

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

env 块是可选的 — Resources、search_docs 和所有验证器无需任何凭据即可工作。

Claude Desktop

添加到你的 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

添加到 .vscode/mcp.json（工作区），或通过命令面板 → MCP: Open User Configuration 打开用户级文件：

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

注意：VS Code 是个例外 — 根键是 "servers"（而非 "mcpServers"）。MCP 工具仅在 Copilot Chat 的 Agent 模式下运行。

Zed

添加到 ~/.config/zed/settings.json：

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

添加到 ~/.continue/config.json：

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

打开 Settings → AI Assistant → MCP Servers → Add 并输入：

• Name：payretailers

• Command：node

• Arguments：C:/Tools/payretailers-mcp/dist/index.js（绝对路径）

其他客户端

任何支持通过 stdio 使用 MCP 的客户端都可以使用此服务器。将其指向 node <absolute-path-to>/dist/index.js 即可。

当 npm 可用时

当 @payretailers/mcp 发布到 npm 后，相同的配置可以使用更简短的形式：

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

无需更改 env，也无需保留解压文件夹。

验证是否正常工作

重新加载 MCP 客户端后，你应该在服务器的状态条目上看到类似：

7 个工具 · 158 个资源 · 7 个提示词 · 5 个资源模板

• Cursor：Ctrl+Shift+P → Customize → MCPs 选项卡。查找带绿色圆点的 payretailers 并展开它。

• Claude Desktop：在新聊天中检查工具抽屉；PayRetailers 工具应与其他 MCP 一起出现。

• VS Code / Zed / Continue.dev / Windsurf：查阅各客户端文档中的 MCP 状态面板。

如果你的助手似乎没有调用工具，请通过在提示词前加上 "Use the PayRetailers MCP to..." 来强制调用一次。一旦它在对话中调用过一次工具，它往往会继续这样做。

故障排查

服务器无法启动。 从终端手动运行该 bundle：

node /path/to/payretailers-mcp/dist/index.js

如果它保持静默等待输入，则 bundle 没有问题 — 问题出在客户端（配置中的路径拼写错误、Windows 上正斜杠与反斜杠的问题、重启了错误的进程）。如果它打印错误，最常见的原因是 Node < 20（升级 Node）或下载不完整（重新下载 zip）。

客户端显示旧计数（例如 5 个工具、89 个资源）。 某些客户端会缓存 MCP 工具/资源的枚举结果。在客户端的 MCP 面板中将服务器切换为 OFF → ON，或在配置中添加一个未使用的 env 条目（例如 "MCP_VERSION": "0.4.1"）以强制重新生成进程。

模型似乎没有调用任何 MCP 工具。 确保聊天处于 Agent 模式（而非 Ask / 只读模式）。一些轻量级模型不太愿意调用工具 — 在首次调用时切换到顶级模型，助手将在对话的其余部分记住这些工具可用。

日志在哪里？ 每个 MCP 客户端都有一个 MCP 日志面板，用于捕获 JSON-RPC 握手、解析错误和服务器 stderr。在 Cursor 中：Ctrl+Shift+U → 下拉菜单 → MCP Logs。

环境变量

可选 — 仅将来的 simulate_transaction 工具（阶段 4）需要。其他所有内容（Resources、search_docs、Prompts）无需任何凭据即可工作。

安全性： 服务器从不记录凭据，也从不持久化凭据。它们仅在会话期间驻留于内存中，并且仅在你调用 simulate_transaction 时发送到 api-sandbox.payretailers.com 或 api.payretailers.com。

使用示例

配置完成后，用自然语言向你的 AI 助手提问：

"Create my first PIX payin in the sandbox for R$50 in Brazil. Use Node.js."

在底层，助手将：

1. 调用 search_docs({ query: "pix payin brazil" }) → 找到 brazil-pix-payin skill。

2. 读取 payretailers://skill/brazil-pix-payin 获取确切步骤。

3. 使用正确的端点、请求头、最小货币单位和 CPF 格式生成可运行代码。

或者直接使用 /integrate-pix-payin 提示词获取完整搭建的答案。

提交前验证 payload

一旦助手起草了 payload，它可以在调用 API 之前进行验证：

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

响应会列出每个问题，包含 code、severity、path、message，通常还有 hint 和 suggestion — LLM 可以在浪费一次网络往返之前修复 payload。

开发

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/（Guides、Skills、Reference、Recipes、概念文档、精选 JSON）已纳入版本控制。仅当你检出了 ../payretailers-ai-docs 并希望刷新镜像时，才运行 npm run sync:docs。

可以使用官方 MCP Inspector 检查服务器：

npx @modelcontextprotocol/inspector node dist/index.js

发布（维护者）

发布通过 GitHub Actions 在标签推送（v*.*.*）时自动进行。工作流程：

1. 运行 lint、类型检查、单元测试、构建和冒烟测试。

2. 运行 npm run pack:release 生成 release/payretailers-mcp-vX.Y.Z.zip（打包的 dist/index.js + data/ 镜像 + README + LICENSE + CHANGELOG + 冒烟测试）。

3. 创建 GitHub Release 并附加 zip。

4. 仅当配置了 NPM_TOKEN 仓库密钥时才发布到 npm 作为 @payretailers/mcp — 否则该 release 仅限 GitHub。

要在本地发布，然后推送标签：

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

严格强制语义化版本：补丁版本修复 bug，次要版本在不破坏现有功能的前提下添加工具/提示词/资源，主版本仅用于重命名/移除。

路线图

• 0.1 ✅ Resources（Guides、Skills）、search_docs、integrate-pix-payin 提示词。

• 0.2 ✅ Resources（Reference、Recipes）、get_country_rules、get_test_data、get_endpoint_spec、提示词 integrate-payout-fx、build-checkout、debug-401-auth、reconcile-with-graphql。

• 0.3 ✅ validate_payload，支持 CPF、CNPJ、RUT、DNI、RUC、CC、NIT、CURP、RFC、CLABE 的真实校验和验证 + 跨领域规则（最小货币单位、货币/国家、HTTPS webhook、方式/国家、幂等性）。

• 0.4 ✅ 概念文档资源类别、get_webhook_playbook、validate_webhook_handler、为订阅操作扩展的 validate_payload、提示词 implement-webhook-handler、integrate-subscriptions。

• 0.4.1 ✅ 订阅模式对齐（AmountModel、frequency 枚举、authorizationType）— CHANGELOG.md。

• 0.5 — simulate_transaction（针对沙箱的干跑）、get_error_code、扩展国家覆盖范围。

• 1.0 — 稳定公开版本 + 列入 官方 MCP Registry + npm 发布。

详见 CHANGELOG.md。

相关

• 针对 Cursor、Claude Code、Claude Desktop 和 VS Code + Copilot 的分步设置指南：docs/setup/。

• 配套文档仓库：payretailers-dev/payretailers-ai-docs — Guides、Skills 和文档镜像的来源。

• 官方文档：www.payretailers.dev。

• 使用 LLM 开发指南：www.payretailers.dev/docs/develop-with-llms。

• Model Context Protocol：modelcontextprotocol.io。

许可证

源代码：MIT。参见 LICENSE。

data/ 中捆绑的文档内容（Guides、Skills、Reference、Recipes）根据 CC BY-ND 4.0 许可，继承自 payretailers-ai-docs 仓库。精选数据文件（data/country-rules.json、data/test-data.json）也以 CC BY-ND 4.0 发布。

贡献

欢迎通过 GitHub Issues 提交 bug 报告和功能请求。社区提交的 Pull Request 会被审查，但由 PayRetailers 团队酌情合并 — 可用时参见 CONTRIBUTING.md。