@payretailers/mcp

PayRetailers Payments API 向け公式 Model Context Protocol (MCP) サーバー。

MCP 互換の AI アシスタントを、PayRetailers 統合のエキスパートに変えます。このサーバーは、公式ガイド、実践的なスキル、エンドポイントリファレンス、統合ツール（検索、国別バリデーション、Webhook プレイブック）を、第一級の MCP リソース、ツール、プロンプトとして公開します。

Cursor、Claude Desktop、Claude Code、Windsurf、Antigravity、Zed、VS Code + Copilot、JetBrains IDEs、Continue.dev、Cline、および stdio 経由で MCP を話すその他のクライアントで動作します。

なぜ使うのか

このサーバーをインストールすると、AI アシスタントは PayRetailers について推測するのをやめ、あらゆるステップで公式情報源を参照するようになります。

• 初回から正しいコード。 アシスタントは各エンドポイントの実際の OpenAPI 形状を読み取るため（get_endpoint_spec）、生成されるコードは実際のフィールド名、型、必須の組み合わせを使用します。他の PSP から借用したものではありません。

• 最初から国を意識。 PIX の payin を依頼すると、アシスタントは PIX がブラジル限定で、BRL を想定し、有効な 11 桁の CPF が必要で、QR コードの有効期限が短いことを認識します。SPEI を依頼すると、メキシコでは CURP または RFC、MXN が必要で、CLABE は非同期でプロビジョニングされることを認識します。これらはすべて get_country_rules によって実現されます。

• サンドボックスに到達する前にペイロードを検証。 validate_payload は、CPF、CNPJ、RUT、DNI、RUC、CC、NIT、CURP、RFC、CLABE の実際のチェックサム検証に加え、横断的なルール（整数の最小単位、HTTPS 通知 URL、通貨/国の一致、方法/国の互換性、冪等性キー、顧客必須フィールドマトリックス、サブスクリプションの AmountModel 形状、PIX Automático のリトライ契約）を実行します。エディタでバグを発見でき、400 INVALID_MODEL_SCHEMA レスポンスで発見する必要はありません。

• Webhook レシーバーを正しく設計。 get_webhook_playbook は、標準のイベント語彙、リトライポリシー、署名/リプレイ契約を返します。validate_webhook_handler は、最も有害な 6 つのアンチパターン（処理後の ACK、eventId による重複排除の欠如、ビジネスエラーの 500 化、本番環境での署名無効化、時計順序の仮定、HTTPS の欠如）を、レシーバーコードを 1 行も書く前に検出します。

• 複雑なフロー用のスラッシュコマンドプロンプト。 /integrate-pix-payin、/integrate-subscriptions、/implement-webhook-handler、/integrate-payout-fx、/build-checkout、/debug-401-auth、/reconcile-with-graphql と入力すると、選択したスタックで本番向けの実装が得られます。

• ゼロ設定、ゼロネットワーク、オフライン対応。 すべてがリリース zip に同梱されています。アカウント、API キー、ドキュメントに関する質問に答えるためのアウトバウンド呼び出しは不要です。資格情報は（計画中の）simulate_transaction ツールにのみ必要です。

内部には、7 つのツール、7 つのプロンプト、158 のドキュメントリソース（ガイド + スキル + リファレンス + レシピ + コンセプトドキュメント）があり、すべて payretailers-ai-docs リポジトリから逐語的にミラーリングされています。

Related MCP server: Payman AI Documentation MCP Server

公開内容

リソース

PayRetailers ドキュメントへの構造化された LLM フレンドリーなアクセス。

完全なリストは接続時に動的に通知されます。クライアントはリソースピッカーで参照できます。

ツール

LLM が推測する代わりに呼び出せるアクション。

プロンプト

開発者が Cursor / Claude Desktop などで / を使用して選択できる、すぐに使えるテンプレート。

インストール

2 つのサポートパスがあります。いずれかを選択してください:

• オプションA — GitHub Releases からのプレビルド zip（現在推奨）: npm アカウント不要、コンパイル不要、ダウンロード後は完全にオフラインで動作します。@payretailers/mcp がまだ npm に公開されていない間、これが公式サポートの配布方法です。

• オプションB — ソースからのビルド: コントリビューターや、実行前にコードを監査したいセキュリティ重視のデプロイ向けです。

オプションC — npm から @payretailers/mcp としてインストール — は計画中ですが、まだ利用できません。パッケージが公開されると、クライアント別設定セクションの npx -y @payretailers/mcp スニペットがそのまま動作します。

オプションA — GitHub Releases からインストール

前提条件: Node.js 20以降（node --version）。それ以外は不要です — リリース zip は自己完結型です。

1. Releases ページを開き、先頭のリリースの「Assets」セクションから最新の payretailers-mcp-vX.Y.Z.zip をダウンロードします。

2. 任意の場所に解凍します。一般的な場所:

   • Windows: C:\Tools\payretailers-mcp

   • macOS / Linux: ~/tools/payretailers-mcp

3. MCP クライアントにサーバーを追加します（下記のクライアント別設定、またはそこにリンクされているステップバイステップガイドを参照）。解凍したフォルダ内の dist/index.js の絶対パスを指定します。

4. MCP クライアントをリロード / 再起動します。サーバーが他のツールと一緒に表示されます。

スクリーンショットと検証プロンプト付きのステップバイステップ設定ガイド:

• Cursor

• Claude Code CLI

• Claude Desktop

• VS Code + GitHub Copilot

配線の前後に任意でスモークチェックを実行できます — バンドルがエンドツーエンドで正常であることを証明します:

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

期待される結果: 最後に PASS ✅ が表示され、7 tools、158 resources、7 prompts、5 resource templates がアナウンスされます。

オプションB — ソースからのビルド

コントリビューター向け、またはセキュリティポリシーで実行前のコード監査が必要な場合。前提条件: Node.js 20以降、git。

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/（Guides、Skills、Reference、Recipes、コンセプトドキュメント、厳選された JSON）はチェックインされています — 同じマシンで更新された payretailers-ai-docs チェックアウトをミラーリングする場合を除き、npm run sync:docs は不要です。

その後、オプションAと同じ方法で dist/index.js を MCP クライアントに配線します。

クライアント別設定

検証プロンプトとトラブルシューティング付きの完全なウォークスルーをお好みですか？ Cursor、Claude Code、Claude Desktop、VS Code + Copilot 向けのステップバイステップガイドは docs/setup/ を参照してください。以下のスニペットは、クライアントの操作にすでに慣れている場合に必要な最小限の JSON です。

すべてのクライアントは同じ3つの情報を必要とします: command（node）、dist/index.js の絶対パスを指す args 配列、そして将来の simulate_transaction ツール用のオプションの env ブロックです。

以下の C:/Tools/payretailers-mcp/dist/index.js を、リリースを解凍した絶対パスに置き換えてください。Windows では JSON でフォワードスラッシュを使用してください — バックスラッシュはエスケープが必要で、紛らわしいエラーを引き起こします。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト単位）に追加:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

env ブロックはオプションです — Resources、search_docs、およびすべてのバリデータは認証情報なしで動作します。

Claude Desktop

claude_desktop_config.json に追加:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

.vscode/mcp.json（ワークスペース）に追加するか、コマンドパレット → MCP: Open User Configuration でユーザースコープのファイルを開きます:

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

注: VS Code は特殊です — ルートキーは "servers"（"mcpServers" ではありません）。MCP ツールは Copilot Chat の Agent モードでのみ実行されます。

Zed

~/.config/zed/settings.json に追加:

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

~/.continue/config.json に追加:

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

Settings → AI Assistant → MCP Servers → Add を開き、以下を入力:

• Name: payretailers

• Command: node

• Arguments: C:/Tools/payretailers-mcp/dist/index.js（絶対パス）

その他のクライアント

stdio で MCP を話すクライアントはすべてこのサーバーを利用できます。node <絶対パス>/dist/index.js を指定すれば完了です。

npm が利用可能になったら

@payretailers/mcp が npm に公開されると、同じ設定がより短い形式で動作します:

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

env の変更は不要、解凍したフォルダを保持しておく必要もありません。

動作確認

MCP クライアントをリロードした後、サーバーのステータスエントリに次のような表示が確認できるはずです:

7 tools · 158 resources · 7 prompts · 5 resource templates

• Cursor: Ctrl+Shift+P → Customize → MCPs タブ。緑のドットが付いた payretailers を探して展開します。

• Claude Desktop: 新しいチャットでツールドロワーを確認します。PayRetailers ツールが他の MCP と一緒に表示されるはずです。

• VS Code / Zed / Continue.dev / Windsurf: 各クライアントのドキュメントで MCP ステータスパネルを確認してください。

アシスタントがツールを呼び出していないように見える場合は、プロンプトの先頭に "Use the PayRetailers MCP to..." を付けて一度強制的に呼び出してみてください。会話内で一度ツールを呼び出すと、その後は呼び出し続ける傾向があります。

トラブルシューティング

サーバーが起動しない。 ターミナルからバンドルを手動で実行します:

node /path/to/payretailers-mcp/dist/index.js

入力待ちのまま沈黙している場合、バンドルは正常です — 問題はクライアント側です（設定のパスのタイプミス、Windows でのフォワードスラッシュとバックスラッシュ、再起動するプロセスの誤り）。エラーが表示される場合、最も一般的な原因は Node < 20（Node のアップグレード）またはダウンロードの破損（zip の再ダウンロード）です。

クライアントが古いカウントを表示する（例: 5 tools、89 resources）。 一部のクライアントは MCP のツール/リソース列挙をキャッシュします。クライアントの MCP パネルでサーバーを OFF → ON に切り替えるか、設定に未使用の env エントリ（例: "MCP_VERSION": "0.4.1"）を追加して再スパウンを強制します。

モデルが MCP ツールを呼び出していないように見える。 チャットが Agent モード（Ask / 読み取り専用モードではない）であることを確認してください。一部の軽量モデルはツール呼び出しに消極的です — 最初の呼び出しではトップティアのモデルに切り替えると、アシスタントは会話の残りの間ツールが利用可能であることを覚えています。

ログはどこにありますか？ すべての MCP クライアントには、JSON-RPC ハンドシェイク、パースエラー、サーバーの stderr をキャプチャする MCP ログパネルがあります。Cursor の場合: Ctrl+Shift+U → ドロップダウン → MCP Logs。

環境変数

オプション — 将来の simulate_transaction ツール（フェーズ4）にのみ必要です。その他すべて（Resources、search_docs、Prompts）は認証情報なしで動作します。

セキュリティ: サーバーは認証情報をログに記録せず、永続化もしません。認証情報はセッション中メモリ内にのみ存在し、simulate_transaction を呼び出したときに api-sandbox.payretailers.com または api.payretailers.com にのみ送信されます。

使用例

設定が完了したら、AI アシスタントに平易な言葉で依頼します:

"Create my first PIX payin in the sandbox for R$50 in Brazil. Use Node.js."

内部では、アシスタントは次のことを行います:

1. search_docs({ query: "pix payin brazil" }) を呼び出し → brazil-pix-payin スキルを見つけます。

2. payretailers://skill/brazil-pix-payin を読み、正確な手順を確認します。

3. 正しいエンドポイント、ヘッダー、最小通貨単位、CPF 形式で実行可能なコードを生成します。

または、/integrate-pix-payin プロンプトを直接使用して、完全にスキャフォールドされた回答を得ることもできます。

API に送信する前のペイロード検証

アシスタントがペイロードをドラフトしたら、API にヒットする前に検証できます:

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

レスポンスには、code、severity、path、message、そして多くの場合 hint と suggestion を持つすべての問題がリストされます — LLM はネットワークラウンドトリップを無駄にする前にペイロードを修正できます。

開発

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/（Guides、Skills、Reference、Recipes、コンセプトドキュメント、厳選された JSON）はリポジトリにチェックインされています。../payretailers-ai-docs をチェックアウトしていてミラーを更新したい場合にのみ npm run sync:docs を実行してください。

サーバーは公式の MCP Inspector で検査できます:

npx @modelcontextprotocol/inspector node dist/index.js

リリース（メンテナー向け）

リリースはタグプッシュ（v*.*.*）時に GitHub Actions で自動化されています。ワークフロー:

1. lint、型チェック、ユニットテスト、ビルド、スモークテストを実行します。

2. npm run pack:release を実行し、release/payretailers-mcp-vX.Y.Z.zip（バンドルされた dist/index.js + data/ ミラー + README + LICENSE + CHANGELOG + スモークテスト）を生成します。

3. GitHub Release を作成し、zip を添付します。

4. NPM_TOKEN リポジトリシークレットが設定されている場合のみ npm に @payretailers/mcp として公開します — それ以外の場合、リリースは GitHub のみです。

ローカルでリリースを切り、タグをプッシュするには:

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

セマンティックバージョニングは厳格に適用されます: パッチリリースはバグ修正、マイナーリリースは既存のものを壊さずにツール/プロンプト/リソースを追加、メジャーリリースはリネーム/削除のみ。

ロードマップ

• 0.1 ✅ Resources（Guides、Skills）、search_docs、integrate-pix-payin プロンプト。

• 0.2 ✅ Resources（Reference、Recipes）、get_country_rules、get_test_data、get_endpoint_spec、プロンプト integrate-payout-fx、build-checkout、debug-401-auth、reconcile-with-graphql。

• 0.3 ✅ CPF、CNPJ、RUT、DNI、RUC、CC、NIT、CURP、RFC、CLABE の実際のチェックサム検証 + 横断的ルール（最小通貨単位、通貨/国、HTTPS ウェブフック、方法/国、冪等性）を備えた validate_payload。

• 0.4 ✅ コンセプトドキュメントリソースカテゴリ、get_webhook_playbook、validate_webhook_handler、サブスクリプション操作向けに拡張された validate_payload、プロンプト implement-webhook-handler、integrate-subscriptions。

• 0.4.1 ✅ サブスクリプションスキーマの整合（AmountModel、frequency 列挙型、authorizationType）— CHANGELOG.md。

• 0.5 — simulate_transaction（サンドボックスに対するドライラン）、get_error_code、国のカバレッジ拡大。

• 1.0 — 安定版パブリックリリース + 公式 MCP Registry への掲載 + npm 公開。

詳細は CHANGELOG.md を参照してください。

関連情報

• Cursor、Claude Code、Claude Desktop、VS Code + Copilot 向けのステップバイステップ設定ガイド: docs/setup/。

• コンパニオンドキュメントリポジトリ: payretailers-dev/payretailers-ai-docs — Guides、Skills、ドキュメントミラーのソース。

• 公式ドキュメント: www.payretailers.dev。

• LLM 向け開発ガイド: www.payretailers.dev/docs/develop-with-llms。

• Model Context Protocol: modelcontextprotocol.io。

ライセンス

ソースコード: MIT。LICENSE を参照してください。

data/ にバンドルされているドキュメントコンテンツ（Guides、Skills、Reference、Recipes）は、payretailers-ai-docs リポジトリから継承した CC BY-ND 4.0 の下でライセンスされています。厳選されたデータファイル（data/country-rules.json、data/test-data.json）も CC BY-ND 4.0 の下で公開されています。

コントリビューション

バグ報告と機能リクエストは GitHub Issues で歓迎します。コミュニティからのプルリクエストはレビューされますが、マージは PayRetailers チームの裁量で行われます — 利用可能になり次第 CONTRIBUTING.md を参照してください。