Payram Helper MCP Server

🚀 Payram Helper MCP Server

MCP（モデルコンテキストプロトコル）サーバーです。このサーバーは、GitHub Copilot（およびMCP対応のクライアント）が自前でホストしているPayramスタックとどのように統合するかを教えます。既存のコードベースを評価するワンクリックツール、新しいスターターアプリを構築するツール、多言語のスニペットを生成するツール、インラインドキュメントを読むツール、およびPayramデプロイメントに対する接続性を検証するツールを提供します。

目次

• プロジェクトの目標
• クイックスタート
• ツールカタログ
• ガイド付きワークフロー
• ドキュメントと仕様書
• 開発
• トラブルシューティング

プロジェクトの目標

• 環境テンプレート、準備チェックリスト、およびフレームワークごとのプレイブックを提供することで、オンボーディングを加速します。
• プロジェクト評価ツールを通じて、パッケージマニフェストと.envファイルをスキャンし、適切な統合スニペットを推奨することで、既存のリポジトリを改造します。
• 支払い、支払い出金、リファラル、ウェブフック、および多言語のバックエンド（Express、Next.js、FastAPI、Laravel、Gin、Spring Bootなど）にまたがるコピー&ペースト可能なスニペットを提供します。
• Copilotがエディターを離れることなくPayramの概念、フロー、およびリファラルダッシュボードを説明できるように、ドキュメントをローカルに保持します。
• Payramが期待するAPI-Keyヘッダーを強制する組み込みの/api/v1/paymentプローブを通じて、接続性を検証します。

クイックスタート

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に記載されており、手動での指示は必要ありません。

ツールカタログ

ツールの登録はsrc/tools/index.tsにあり、個々の実装はsrc/tools/**にあり、言語固有のテンプレートはtemplates/フォルダーの下にあります。

ガイド付きワークフロー

1. 既存のプロジェクトを評価して改造する

1. Copilotに「Can you integrate Payram into this project?」と尋ねます。
2. アシスタントがassess_payram_projectを実行し、依存関係マニフェストと.envをレビューします。
3. 推奨される手順に従います（payramをインストールする、Express/FastAPI/Springルートスニペットを要求する、ウェブフックを追加するなど）。
4. 資格情報が実際のものになったら、test_payram_connectionを使用して、バックエンドが自前でホストしているサーバーに到達できることを確認します。

2. 新しいサンプルを構築する

1. 「Create a Payram Express demo」と言うと、scaffold_payram_appが支払い、支払い出金、ウェブフック、およびUIコンソールを備えたExpressプロジェクトを構築します。
2. 生成されたファイルを空のリポジトリに配置するか、既存のディレクトリと比較して参照用の配線を行います。

3. 「Test Payram」の準備フローを実行する

1. 「test payram」と言います。アシスタントは自動的に以下のことを行います。
   • prepare_payram_testを呼び出して準備チェックリストを共有します。
   • generate_env_templateを使用して.envが存在することを確認し（存在しない場合は作成します）。
   • 実際の資格情報が入力されるのを待ってからtest_payram_connectionを呼び出します。
2. 構造化されたJSON結果を確認して、Payram APIに到達できることを確認します。

4. 支払い、支払い出金、リファラル、およびウェブフックを接続する

• 支払い：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。
• ウェブフック：generate_webhook_handlerとファンアウト用のgenerate_webhook_event_router、各ステータスをテストするためのgenerate_mock_webhook_event。

ドキュメントと仕様書

• ローカルの参照はdocs/の下にあります。
  • docs/js-sdk.md – TypeScript SDKの拡張ガイド。
  • docs/payram-external.yaml, docs/payram-webhook.yaml – OpenAPI仕様書。
  • docs/referrals.md – リファラルのFAQとワークフロー。
• MCPドキュメントツール（get_payram_doc_by_id, list_payram_docs）は、src/utils/markdownLoader.tsを介してdocs/payram-docs/**からファイルを読み取ります。
• 将来の更新のために、docs/payram-docsに上流のドキュメントツリーをミラーリングして、サーバーの応答が同期したままになるようにします。

開発

このプロジェクトは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以上であることを確認し、MCP SDKを取得するためにyarn installを実行します。

その他の問題については、src/utils/logger.tsから出力される構造化ログを調査し（LOG_LEVEL=debugに設定）、再現手順を含めて問題/PRを開いてください。