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），並在提交問題或拉取請求時提供重現細節。