用途
easypaydirect-mcp 是一个非官方、只读的 Model Context Protocol（MCP）服务器，用于访问 Easy Pay Direct（EPD）/ NMI 系列支付网关的 Query API。它让 AI 助手（Claude Desktop、Claude Code 或任何 MCP 客户端）能够安全、只读地查询网关中的交易（transactions）、订阅（subscriptions）、周期计划（recurring plans）和 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。连接到该服务器的 LLM 只能查看，不能触及资金。安全细节见 docs/security.md。
- 覆盖对象：交易、订阅、周期计划、Customer Vault 记录。
- 广泛兼容：适用于任何 NMI 白标网关，需要指向对应网关主机。
使用方式
运行环境与配置：
- 需要 Node.js 18+。
- 服务器通过 stdio 使用 MCP 协议，需要两个环境变量。
- 关于如何找到密钥和主机的说明见 docs/configuration.md。
使用 Docker 运行：
无需本地 Node.js。从仓库根目录构建镜像，然后用 -i 运行——MCP 通过 stdio 通信，因此容器需要保持 stdin 打开。也可以将变量放在 env 文件中（--env-file .env）。.env 已被 git 忽略——切勿提交真实密钥。
连接到 Claude：
Claude Desktop——添加到 claude_desktop_config.json（参见 examples/claude-desktop-config.json）。若要改用 Docker 镜像，需替换命令——裸 -e NAME 会把变量转发进容器。完整教程见 docs/getting-started.md。
Claude Code 插件（服务器 + 技能）：
该插件会安装 MCP 服务器和一个 Agent Skill，用于教 Claude 如何正确读取网关数据——例如成功的 ACH 销售只是 submitted（已提交）而非 paid（已付款），以及 EPD 时间戳为 UTC 时间。在 shell 中设置密钥（插件从环境变量读取），然后安装。使用其他客户端？该技能就是一个普通的 SKILL.md，可以添加到任何支持 Agent Skills 的工具中。
工具说明：
所有工具均为只读。完整参考见 docs/tools.md。可在本地针对 MCP Inspector 运行。架构以及工具如何映射到 Query API 见 docs/nmi-api-mapping.md。
适用场景
- 用自然语言查询某客户上周失败的交易。
- 确认某订阅是否仍然有效。
- 查阅交易、订阅、周期计划和 Customer Vault 记录等报表数据。
限制与边界
- 严格只读：无法扣款、退款、作废交易或修改 Vault。写入操作可能在未来某个主版本中提供——始终为可选加入、默认关闭且明确设限。
- 需要 Node.js 18+，通过 stdio 通信。
- 仅面向 NMI 系列网关的 Query API。
- 与 Easy Pay Direct 或 NMI 无官方关联。
规划中 / 正在考虑（欢迎贡献，见 open issues）：
- 测试——使用录制的 Query API fixtures 的单元测试套件（#1）
- 更友好的日期——日期过滤器中接受 ISO-8601（#2）
- 更多过滤条件——search_transactions 上的商户自定义字段（#3）
- 更好的错误——将 NMI 响应码映射为可操作的错误消息（#4）
- 分发——发布时自动发布（#8）
- 文档——响应字段参考（#9）
只读仍是默认姿态——任何写入支持都将是独立的、可选加入、设限的主版本。已发布变更见 changelog。许可证：MIT © the easypaydirect-mcp contributors。文档地址：https://praveendias1180.github.io/easypaydirect-mcp/
