easypaydirect-mcp

easypaydirect-mcp

📖 文档： https://praveendias1180.github.io/easypaydirect-mcp/

适用于 Easy Pay Direct（EPD）/ NMI 系列支付网关的非官方、只读 Model Context Protocol 服务。

为 AI 助手（Claude Desktop、Claude Code 或任何 MCP 客户端）提供安全的只读访问权限，以查看网关中的交易、订阅、定期付款计划和 Customer Vault 记录——这样，你就可以用日常语言提问，例如 “找出这位客户上周失败的交易” 或 “这个订阅仍然有效吗？”。

Easy Pay Direct 基于 NMI / Network Merchants 网关平台构建，因此此服务适用于任何 NMI 白标网关——只需将其指向你的网关主机即可。EPD 只是主要示例，并非唯一适用对象。

⚠️ 与 Easy Pay Direct 或 NMI 没有关联，未获其认可或赞助。“Easy Pay Direct”、“EPD” 和 “NMI” 是其各自所有者的商标。这是一个独立的开源客户端，用于访问其公开的 Query API。

---

为什么是只读？

此服务只与网关的 Query API（/api/query.php）通信——这是用于报告的端点。它没有任何代码路径可以访问交易端点（transact.php），因此无法扣款、退款、撤销交易或修改 vault。连接到此服务的大模型可以查看信息，但无法动用资金。请参阅 docs/security.md。

未来的主要版本可能会加入写入操作——始终需要主动选择启用，默认关闭，并设置醒目的限制。

---

安装和运行

需要 Node.js 18+。

# no install needed — run straight from npm
npx easypaydirect-mcp

此服务通过 stdio 使用 MCP，并需要两个环境变量：

变量	必填	说明
NMI_SECURITY_KEY	✅	你的网关 API 安全密钥（建议使用只读密钥）。商户门户 → Settings → Security Keys。
NMI_API_URL	—	网关 API 基础 URL。默认为 https://secure.nmi.com。对于 EPD/白标网关，请将其设置为你的网关主机。

如何查找密钥和主机，请参阅 docs/configuration.md。

使用 Docker 运行

无需在本地安装 Node.js。从仓库根目录构建镜像，然后使用 -i 运行——MCP 通过 stdio 通信，因此容器需要保持 stdin 打开：

docker build -t easypaydirect-mcp .

docker run --rm -i \
  -e NMI_SECURITY_KEY=your_read_only_security_key \
  -e NMI_API_URL=https://secure.nmi.com \
  easypaydirect-mcp

也可以将变量保存在环境文件中（--env-file .env）。.env 已被 git 忽略——切勿提交真实密钥。

将其连接到 Claude

Claude Desktop——添加到 claude_desktop_config.json（请参阅 examples/claude-desktop-config.json）：

{
  "mcpServers": {
    "easypaydirect": {
      "command": "npx",
      "args": ["-y", "easypaydirect-mcp"],
      "env": {
        "NMI_SECURITY_KEY": "your_read_only_security_key",
        "NMI_API_URL": "https://secure.nmi.com"
      }
    }
  }
}

Claude Code：

claude mcp add easypaydirect \
  -e NMI_SECURITY_KEY=your_read_only_security_key \
  -e NMI_API_URL=https://secure.nmi.com \
  -- npx -y easypaydirect-mcp

如要改用 Docker 镜像，请替换命令——单独使用 -e NAME 会将该变量转发到容器中：

claude mcp add easypaydirect \
  -e NMI_SECURITY_KEY=your_read_only_security_key \
  -e NMI_API_URL=https://secure.nmi.com \
  -- docker run --rm -i -e NMI_SECURITY_KEY -e NMI_API_URL easypaydirect-mcp

完整操作指南：docs/getting-started.md。

Claude Code 插件（服务端 + 技能）

该插件会同时安装 MCP 服务和 Agent 技能， 教 Claude 如何正确读取网关数据——例如，成功的 ACH 销售交易只是已提交，并不代表已付款；EPD 时间戳采用 UTC。

在 shell 中设置密钥（插件会从环境中读取），然后安装：

export NMI_SECURITY_KEY=your_read_only_security_key
export NMI_API_URL=https://secure.nmi.com   # optional; your EPD / white-label host

/plugin marketplace add praveendias1180/easypaydirect-mcp
/plugin install easypaydirect@easypaydirect-mcp

使用其他客户端？该技能是纯文本 SKILL.md 文件，可将其添加到任何支持 Agent Skills 的工具中。

工具

所有工具均为只读。完整参考请见 docs/tools.md。

工具	功能
get_transaction	按网关交易 ID 获取一笔交易。
search_transactions	按日期范围和筛选条件（状态、操作类型、付款类型、来源、电子邮件、订单 ID）搜索交易。
get_subscription	按 ID 获取一个定期订阅。
list_subscriptions	列出定期订阅，可按创建或更新日期范围筛选。
list_recurring_plans	列出定期计费计划（或按 plan_id 获取一个计划）。
get_customer_vault_record	按 ID 获取一条已存储的 Customer Vault 记录。
list_customer_vault	列出已存储的 Customer Vault 记录，可按日期范围筛选。

开发

git clone https://github.com/praveendias1180/easypaydirect-mcp.git
cd easypaydirect-mcp
npm install
npm run build      # compile TypeScript to dist/
npm run typecheck  # type-check only

使用 MCP Inspector 在本地运行：

npx @modelcontextprotocol/inspector node dist/index.js

架构以及工具与 Query API 的对应关系：docs/nmi-api-mapping.md。

路线图

计划中 / 正在考虑的事项——欢迎贡献（请参阅未解决的问题）：

• 测试 — 使用录制的 Query API 固定数据集构建单元测试套件（#1）
• 更友好的日期格式 — 在日期筛选器中接受 ISO-8601 格式（#2）
• 更多筛选条件 — 在 search_transactions 中支持商户自定义字段（#3）
• 更好的错误信息 — 将 NMI 响应代码转换为可执行的提示信息（#4）
• 分发 — 自动执行发布时的发布流程（#8）
• 文档 — 响应字段参考（#9）

默认仍保持只读；任何写入支持都将作为单独的、需主动选择并设有门控的主版本推出。

已发布的变更请参阅更新日志。

贡献

欢迎贡献——本项目旨在打造一个小巧、可靠的只读 MCP 服务。请参阅 CONTRIBUTING.md，了解基本规范和开发环境设置。

初次参与？ 从一个适合新手的问题开始——每个问题都附有背景说明、任务清单、相关文件位置和验收标准。有疑问？请发起一场 Discussion。

许可证

MIT © easypaydirect-mcp 贡献者。