Payram Helper MCP Server

🚀 Payram Helper MCP 服务器

Payram Helper MCP 服务器是一个 MCP（模型上下文协议）服务器，它可以指导 GitHub Copilot（以及任何支持 MCP 的客户端）如何与自托管的 Payram 堆栈集成。该服务器提供了一系列一键式工具，可用于评估现有代码库、搭建新的启动应用程序、生成多语言代码片段、读取内联文档，以及验证与 Payram 部署的连接性。

🚀 快速开始

1. 安装依赖项

   yarn install
   

2. 配置环境
   • 将 .env.example 复制为 .env，并填写 PAYRAM_BASE_URL 和 PAYRAM_API_KEY，或者从 Copilot 运行 MCP 工具 generate_env_template 以自动追加模板。
3. 运行服务器

   yarn dev
   # 在 http://localhost:3333/mcp 和 /mcp/sse 上暴露 HTTP + SSE 传输
   

4. 将 MCP 服务器添加到 Copilot/你的 MCP 客户端
   • 将客户端指向 http://localhost:3333/mcp（如果支持流式传输，则指向 /mcp/sse）。
5. 健康检查

   curl http://localhost:3333/healthz
   

💡 使用建议

当你告诉 Copilot “test payram” 时，它将自动运行就绪性检查清单，确保 .env 文件存在，然后使用你的真实凭证调用 test_payram_connection。该行为在 COPILOT-USE.md 中有文档说明，无需手动提示。

✨ 主要特性

• 加速入职流程：通过提供环境模板、就绪性检查清单和按框架划分的操作指南，帮助新用户快速上手。
• 改造现有仓库：通过项目评估工具扫描包清单和 .env 文件，然后推荐合适的集成代码片段。
• 提供可复制粘贴的代码片段：涵盖支付、支出、推荐、Webhook 以及多语言后端（如 Express、Next.js、FastAPI、Laravel、Gin、Spring Boot 等）。
• 本地化文档：使 Copilot 能够在编辑器内解释 Payram 的概念、流程和推荐仪表板。
• 验证连接性：通过内置的 /api/v1/payment 探测工具，强制使用 Payram 所需的 API-Key 头部信息。

📦 安装指南

安装依赖

yarn install

配置环境

复制 .env.example 到 .env，并填充 PAYRAM_BASE_URL 和 PAYRAM_API_KEY。或者使用 Copilot 运行 MCP 工具 generate_env_template 自动添加模板。

启动服务器

yarn dev

添加到客户端

将客户端指向 http://localhost:3333/mcp 或 /mcp/sse（支持流式传输时）。

健康检查

curl http://localhost:3333/healthz

💻 使用示例

基础用法

评估并改造现有项目

1. 向 Copilot 询问：“Can you integrate Payram into this project?”
2. 助手将运行 assess_payram_project，检查依赖清单和 .env 文件。
3. 按照推荐步骤操作（安装 payram、请求 Express/FastAPI/Spring 路由代码片段、添加 Webhook 等）。
4. 当凭证有效时，使用 test_payram_connection 确保后端能够连接到自托管服务器。

搭建新的示例项目

1. 输入 “Create a Payram Express demo”，scaffold_payram_app 将构建一个包含支付、支出、Webhook 和 UI 控制台的 Express 项目。
2. 将生成的文件放入空仓库，或与现有目录进行比较以参考布线。

运行 “Test Payram” 就绪性流程

1. 输入 “test payram”，助手将自动执行以下操作：
   • 调用 prepare_payram_test 以显示就绪性检查清单。
   • 使用 generate_env_template 确保 .env 文件存在（如果不存在则创建）。
   • 在调用 test_payram_connection 之前等待有效凭证。
2. 查看结构化的 JSON 结果，确认 Payram API 可访问。

集成支付、支出、推荐和 Webhook

• 支付：使用 generate_payment_sdk_snippet（JS SDK）或 generate_payment_http_snippet（Python/Go/PHP/Java）。
• 多语言路由：使用 snippet_nextjs_payment_route、snippet_fastapi_payment_route 等。
• 支出：使用 generate_payout_sdk_snippet 创建支出，使用 generate_payout_status_snippet 轮询状态。
• 推荐：使用 generate_referral_route_snippet、generate_referral_validation_snippet。
• Webhook：使用 generate_webhook_handler 和 generate_webhook_event_router 进行扇出，使用 generate_mock_webhook_event 测试每个状态。

📚 详细文档

本地参考文档

• docs/js-sdk.md：TypeScript SDK 的详细指南。
• docs/payram-external.yaml、docs/payram-webhook.yaml：OpenAPI 规范。
• docs/referrals.md：推荐常见问题解答和工作流程。

MCP 文档工具

MCP 文档工具（get_payram_doc_by_id、list_payram_docs）通过 src/utils/markdownLoader.ts 从 docs/payram-docs/** 读取文件。为了确保服务器响应与上游文档同步，未来更新时请在 docs/payram-docs 中镜像上游文档树。

🔧 技术细节

工具注册

工具注册信息位于 src/tools/index.ts，具体实现位于 src/tools/**，特定语言模板位于 templates/ 文件夹下。

开发命令

项目以 TypeScript（ESM）为主，Prettier 配置位于 .prettierrc.json，ESLint 配置位于 eslint.config.mjs。遵循 Makefile 中的提交助手（make commit）可实现平滑贡献。

📄 许可证

暂未提供相关许可证信息。

🛠️ 故障排除

• Copilot 未调用正确的工具：检查 COPILOT-USE.md，确保 MCP 客户端已加载服务器。重新运行 “test payram” 或 “assess my project” 以触发预期的自动化操作。
• test_payram_connection 返回 401 错误：确认 .env 文件使用的是 API-Key 头部，而不是 Authorization。当检测到占位符时，该工具会提示缺少的字段。
• 文档工具提示文件缺失：验证本地 docs/payram-docs/ 目录中是否包含请求的 Markdown 文件（get_payram_doc_by_id 拒绝包含 .. 的路径）。
• 服务器无法启动：检查 .env 文件中的 PAYRAM_BASE_URL 和 PAYRAM_API_KEY，确保使用的是 Node 18 及以上版本，并运行 yarn install 以获取 MCP SDK。

对于其他问题，请检查 src/utils/logger.ts 输出的结构化日志（设置 LOG_LEVEL=debug），并在提交问题或拉取请求时提供重现细节。