PayRam

PayRam MCP サーバー — AI エージェント向けセルフホスト型暗号資産決済

セルフホスト型の暗号資産・ステーブルコイン決済：アカウントのロックも、資金の凍結もなく、顧客データが共有されることもありません。AI エージェントが MCP 経由で計画、インストール、運用できます。 ホスト型エンドポイント：https://mcp.payram.com/mcp · ウェブサイト · ドキュメント · Agentic · OpenClaw

あらゆる MCP 対応 AI エージェント — OpenClaw、Hermes、Claude、Cursor、GitHub Copilot など — がセルフホスト型の PayRam 暗号資産決済スタックをデプロイ、統合、運用できる MCP（Model Context Protocol）サーバー です。

まずはこちら： カタログの中核となる4つのツール：

ツール	内容
payram_setup_plan	人が引き継ぐ必要がある箇所をすべて明示した、パーソナライズされたインストール計画
payram_doctor	URL を指定して PayRam サーバーを確認する、公開かつ認証情報不要のチェック
payram_troubleshoot	問題を説明するかエラーを貼り付けると、既知の原因、確認方法、修正方法、次に使うツールが表示されます
payram_runbook	管理タスク：サイト URL、ドメイン、SSL、ファイアウォール、アップグレード、バックアップ、チェーン、Smart Bridge、Shopify/WooCommerce
payram_ops_playbook	エージェントが独自の認証情報を使って実行する、Day-2 API のレシピ

これらに加えて、コードベースの評価、スターターアプリのひな形、複数言語のスニペット、インラインドキュメントも利用できます。

ホスト型サーバー（mcp.payram.com）は、加盟店の認証情報を保持しません。 Day-2 の運用は payram_ops_playbook を通じて行います。エージェントが PayRam API を直接呼び出すため、認証情報がエージェントのマシンから外に出ることはありません。ライブデータツール（決済の検索、決済リンク、ノード同期、ワーカーの再起動）と assess_payram_project は、MCP をローカルモードで自分で実行する場合にのみ利用できます。

エージェントとクローラー向け： サーバーカード · スキルインデックス · llms.txt · サイトマップ。サーバーは / で Accept: text/markdown にも応答し、エージェントが読み取れる概要を返します。

---

PayRam とは？ · PayRam とは何ですか？

PayRam は、完全に自分で所有できるセルフホスト可能なマルチチェーン暗号資産決済ゲートウェイです。運用に登録や KYC/KYB は必要ありません。 AI エージェント（または開発者）は、PayRam、銀行、その他の決済処理業者にアカウントを登録することなく、ストアを立ち上げて決済を受け付けられます。自分の VPS にデプロイし、API キーをローカルで生成すれば、すぐに運用を開始できます。

他との違い：

• 誰にも締め出されません — ロックされるアカウントも、凍結される資金もありません。顧客データが共有されることはなく、報告や監視も行われません。理由はシンプルです。PayRam は自分のサーバー上で動作し、資金は自分のウォレットに入金されます。
• 許可不要のセットアップ — 登録不要、KYC 不要、KYB 不要です。誰かの承認を得る必要も、停止される心配もありません。自律的にストアを立ち上げるエージェントや、西側の決済処理業者への登録が選択肢にならない中国のような市場に最適です。
• カードから暗号資産への決済 — 暗号資産を持っていない購入者も、クレジットカード／デビットカードで支払えます。受け取った暗号資産は、自分で管理するウォレットに直接決済されます。これは組み込みの決済チャネルで、Payments ページから有効にできます。カードプロバイダーは購入者に対して独自の確認を行います。
• マルチチェーン — Bitcoin、Ethereum、Base、Polygon、Tron において、BTC、ETH、USDT、USDC、TRX をネイティブに受け付けます。入金の自動検出、オンチェーンでの確認、コールドストレージへの集約、署名付き Webhook に対応しています。Smart Bridge の決済経路では、Solana、Bitcoin、Tron（USDT）、BNB Chain での支払いも受け付け、Base 上の USDC で決済できます。
• サーバーに入金用の秘密鍵はありません — スマートコントラクトが入金をコールドウォレットに集約するため、サーバーが侵害されても資金の送金先を変更できません。サーバーのホットウォレットはガス代の支払いと出金の署名を行うため、残高は少額に保ってください。

---

AI エージェントによる PayRam の利用方法

PayRam はエージェントファーストのインフラストラクチャです。MCP 経由で統合されるため、OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain など、MCP 対応のあらゆるランタイムで動作します。一般的なエージェントのワークフローは次のとおりです。

1. 接続 — https://mcp.payram.com/mcp をエージェントの MCP 設定に追加します（接続だけなら API キーは必要ありません）。
2. 計画 — payram_setup_plan を呼び出します。実行順序、各手順の担当者、エージェントが人間の操作を待つ必要がある箇所（コールドウォレット、メインネットのガス代、root のみが変更できる設定）が返されます。
3. インストール — VPS の対話型ターミナルで一度だけ、bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet（または --mainnet）を実行します。インストーラーのデフォルトはメインネットなので、必ずフラグを指定してください。bash にパイプで渡してはいけません。
4. 引き継ぎ — 人間がすぐに root アカウントを取得し、公開ドメインから Settings → Site URL を保存します。それまでは、決済リンクの URL は http://localhost を指します。
5. 確認 — 公開 URL を指定して payram_doctor を実行します（認証情報は不要です）。
6. 決済の受付 — スニペットツールから、フレームワーク固有の統合コードを組み込みます。Webhook には署名が付与されます（プロジェクトの API キーを使用して、raw body に HMAC-SHA256 を適用した X-Payram-Signature）。
7. 運用 — payram_ops_playbook（daily_check、payment_options、node_sync、unswept_funds、create_payment_link、…）には、エージェント自身の認証情報で実行する正確な API 呼び出しが示されています。管理者による変更については payram_runbook を参照してください。

{
  "mcpServers": {
    "payram": { "url": "https://mcp.payram.com/mcp" }
  }
}

OpenClaw 固有の手順（登録、Base Sepolia のテストネット、WhatsApp／Telegram／Discord 向けのチャットコマースのパターン）については、payram-openclaw-integration スキルと payram.com/openclaw をご覧ください。

PayRam はエージェントファーストのインフラストラクチャです。MCP 経由で統合されるため、MCP 対応のあらゆるランタイムで動作します。一般的なエージェントのワークフローは、MCP エンドポイントに接続 → payram_setup_plan を呼び出してインストールを計画 → 対話型ターミナルで bash <(curl …) --testnet を実行してゲートウェイをデプロイ → 人間がすぐに root アカウントを作成し、公開ドメインの Site URL を保存 → payram_doctor で確認 → 統合コードを使って決済を受け付け（Webhook には X-Payram-Signature 署名が付与されます）→ payram_ops_playbook を通じてエージェント自身の認証情報で運用、という流れです。ホスト型 MCP サーバーが加盟店の認証情報を保存することはありません。

お使いのネットワークから GitHub にアクセスしにくい場合は、このリポジトリを別の Git ホスティングサービスにミラーリングできます（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

目次

• PayRam とは？
• AI エージェントによる PayRam の利用方法
• エージェントスキル
• プロジェクトの目標
• クイックスタート
• MCP クライアントから接続する
• ローカルモード
• 認証情報
• ツール一覧
• ガイド付きワークフロー
• 開発
• トラブルシューティング

---

エージェントスキル

エージェント向けの入り口： https://mcp.payram.com/SKILL.md — PayRam の概要と、エージェントを最初に使う 4 つのツールへ案内するルートスキルです。こちらも提供しています：/llms.txt。

このリポジトリには、AI コーディングアシスタント向けの 19 個のエージェントスキルが含まれています。skills.sh からインストールできます。

個別にインストール

npx skills add payram/payram-mcp/payram-setup
npx skills add payram/payram-mcp/payram-agent-onboarding
npx skills add payram/payram-mcp/payram-auth
npx skills add payram/payram-mcp/payram-analytics
npx skills add payram/payram-mcp/payram-crypto-payments
npx skills add payram/payram-mcp/payram-payment-integration
npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
npx skills add payram/payram-mcp/payram-checkout-integration
npx skills add payram/payram-mcp/payram-widget-integration
npx skills add payram/payram-mcp/payram-webhook-integration
npx skills add payram/payram-mcp/payram-stablecoin-payments
npx skills add payram/payram-mcp/payram-bitcoin-payments
npx skills add payram/payram-mcp/payram-payouts
npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
npx skills add payram/payram-mcp/payram-openclaw-integration
npx skills add payram/payram-mcp/compare-crypto-payments
npx skills add payram/payram-mcp/payram-agent-journey
npx skills add payram/payram-mcp/payram-topup-wallet-integration
npx skills add payram/payram-mcp/payram-testnet-testing

スキル	目的
payram-setup	インストール計画とサーバーのセットアップ：要件、インストーラー、Site URL、ウォレット、最初の支払いリンク
payram-agent-onboarding	エージェントによるヘッドレスインストール：エージェントの CLI コマンド、環境変数、人間への引き継ぎ
payram-auth	JWT 認証フロー — サインイン、トークンの更新、ログアウト、外部プラットフォームの詳細
payram-analytics	JWT を使用した直接 REST API による支払いの検索、取引量、残高、スイープ履歴
payram-crypto-payments	アーキテクチャの概要、PayRam を選ぶ理由、MCP ツール
payram-payment-integration	支払い統合のクイックスタートガイド
payram-self-hosted-payment-gateway	支払いインフラストラクチャのデプロイと所有
payram-checkout-integration	6 つのフレームワークに対応した SDK ＋ HTTP によるチェックアウトフロー
payram-widget-integration	安全な「クレジットを追加」ボタン（バックエンドエンドポイントを使用し、公開 API キーは使用しません）＋署名付きウェブフックのハンドラー
payram-webhook-integration	Express、Next.js、FastAPI、Gin、Laravel、Spring Boot に対応した署名付きウェブフック（HMAC）ハンドラー
payram-stablecoin-payments	EVM チェーンと Tron 全体での USDT／USDC の受け入れ
payram-bitcoin-payments	HD ウォレット導出とモバイル署名に対応した BTC
payram-payouts	暗号資産の支払い送金と紹介プログラムの管理
payram-no-kyc-crypto-payments	KYC 不要、サインアップ不要、パーミッションレスな支払いの受け入れ
payram-openclaw-integration	PayRam を OpenClaw／エージェントのランタイムに統合 — MCP の登録、テストネット、チャットコマース
compare-crypto-payments	決済ゲートウェイを比較：Stripe、BitPay、Coinbase、NOWPayments、BTCPay、PayRam、x402
payram-agent-journey	スタートガイド：インストール（加盟店または運用者）→ ウォレット → ガス／スイープ → 統合 → テスト
payram-topup-wallet-integration	既存アプリ向け：暗号資産をユーザー残高に入金し、残高から請求書を決済 — 台帳＋フロー
payram-testnet-testing	メインネットの前に、テストネットで自分の支払いリンクを最初から最後までテスト

---

プロジェクトの目標

• オンボーディングを加速します。パーソナライズされたセットアップ計画、運用手順書、環境テンプレート、フレームワークごとのプレイブックを提供します。
• 認証情報を保持せずに運用します。ホストサーバーは PayRam の URL を使ってサーバーをチェックし（payram_doctor）、エージェントが自身の認証情報で実行できる正確な API の手順（payram_ops_playbook）を提供します。
• 既存のリポジトリを後付けで対応します。プロジェクト評価ツール（ローカルモード）がパッケージマニフェストと .env ファイルをスキャンし、適切な統合スニペットを推奨します。
• コピーして貼り付けられるスニペットを提供します。Payments、Payouts、Referrals、Webhooks に加え、複数の言語に対応したバックエンド（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot など）を網羅します。
• ドキュメントをローカルに保持します。Copilot がエディターを離れることなく、PayRam の概念、フロー、紹介ダッシュボードについて説明できるようにします。
• 接続を検証します。支払いを作成しない読み取り専用のプローブ（payram_doctor、test_payram_connection）を使います。

---

クイックスタート

ほとんどのエージェントでは、ホスト型エンドポイント https://mcp.payram.com/mcp を使うだけで十分です（MCP クライアントから接続するを参照）。サーバーを自分で実行するには、次の手順に従ってください。

1. 依存関係をインストールする

   yarn install
   

   このリポジトリでは Yarn 1 を使用します。Node 25 以降には Corepack が同梱されなくなったため、Node 26 では npm install -g yarn で先に Yarn をインストールしてください。
2. 環境を設定する（ローカルモードのデータツールを使う場合のみ必要です）
   • .env.example を .env にコピーします。
   • PAYRAM_BASE_URL に PayRam の URL を設定します。ダッシュボードと同じオリジンを指定してください（例：https://pay.example.com）。
   • PAYRAM_API_KEY と、データツール用の JWT 変数を設定します。ローカルモードを参照してください。
3. サーバーを実行する

   yarn dev
   # Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport)
   

4. MCP サーバーをクライアントに追加する：MCP クライアントから接続するを参照してください。ローカルモードの URL は http://localhost:3333/mcp です。
5. ヘルスチェック

   curl http://localhost:3333/healthz
   

ヒント： Copilot に「test payram」と伝えると、準備状況チェックリストを自動的に実行し、.env が存在することを確認してから、実際の認証情報を使って test_payram_connection を呼び出します。この動作はCopilot 自動化プロンプトで定義されているため、手動でプロンプトを入力する必要はありません。

---

MCP クライアントから接続する

エンドポイント： https://mcp.payram.com/mcp（ストリーミング可能な HTTP、POST 経由の JSON-RPC）。SSE エンドポイントはなく、/mcp/sse は 410 を返します。認証ヘッダーは不要です。ホスト型サーバーは加盟店の認証情報を保持しないため、認証情報はお使いのマシン上にとどまり、チャットに送信されることもありません。

クライアント	場所	設定
VS Code（Copilot Chat）	設定 → Copilot：Model Context Protocol → HTTP サーバーを追加	名前 payram、上記 URL、ヘッダーは空欄
Cursor	設定 → MCP Servers → 追加 → HTTP	名前 payram、上記 URL
Claude Desktop / Code	設定 → MCP Servers → HTTP サーバーを追加	名前 payram、上記 URL
任意の MCP クライアント	HTTP エンドポイントを登録	上記 URL、ヘッダーなし

確認： ツール一覧の先頭には payram_setup_plan、payram_doctor、payram_troubleshoot、payram_runbook、payram_ops_playbook が表示され、その後に scaffold_payram_app と generate_* スニペットツールが続きます。次に、「pay.example.com への PayRam のインストールを計画して」「https://pay.example.com を確認して」「FastAPI の create-payment ルートを生成して」「Next.js の webhook ハンドラーを作って」と試してください。

プロンプト： setup-payram、setup-payram-agent、integrate-payment、troubleshoot-payment、daily-ops。 リソース： payram://docs/setup-guide、payram://docs/api-reference、およびテンプレート payram://ops/playbook/{task} と payram://runbooks/{task}。

Copilot 自動化プロンプト

新しいワークスペースに一度貼り付けると、「test payram」で準備状況のフロー全体が自動実行されるようになります。

You have access to the `payram` MCP server in this workspace.

Whenever I ask you to "test my Payram connection" (or I type "test payram"), follow this order:

1. Call `prepare_payram_test` (no inputs) and share the checklist verbatim.
2. Look for a `.env` in the workspace root; create one if missing.
3. Ensure `.env` defines `PAYRAM_BASE_URL` and `PAYRAM_API_KEY`. If either is
   missing, call `generate_env_template` and append it (with TODOs) to `.env`.
   Do NOT call `test_payram_connection` until real values are provided.
4. Once real values exist, call `test_payram_connection` with baseUrl/apiKey
   from `.env`, show the structured result, and explain whether the
   connection is healthy. If anything fails, run `payram_doctor` and follow
   its ranked fixes.

---

ローカルモード

MCP を自分の PayRam と同じ環境で実行すると、ライブデータのツールを利用できます。

• list_platforms、search_payments、lookup_payment、get_payment_summary、get_daily_volume、get_unswept_balances、list_currencies、list_recipients
• create_payment_link、check_payment_readiness、check_node_sync、restart_payram_worker
• assess_payram_project

PAYRAM_MCP_MODE=local yarn dev        # or: yarn build && PAYRAM_MCP_MODE=local yarn start

• モード： PAYRAM_MCP_MODE=local を設定すると、ローカルモードが選択されます。サーバーが Vercel 上で実行されていない場合も、ローカルモードがデフォルトです。PAYRAM_MCP_MODE=hosted では、認証情報は読み込まれません。
• バインド： ローカルモードでは、デフォルトで 127.0.0.1 にバインドされます（ポートは PORT、デフォルトは 3333）。
• ループバック以外へのバインド： HOST（例：HOST=0.0.0.0）を設定してから、次のようにします。
  • MCP_ALLOWED_HOSTS を設定します（Host ヘッダーで許可するホスト名をカンマ区切りで指定します）。
  • MCP_SERVER_TOKEN を設定します。クライアントは Authorization: Bearer <token> を送信する必要があります。
  • PAYRAM_* 認証情報が設定されている場合、MCP_SERVER_TOKEN がない状態でループバック以外の HOST にバインドしようとすると、サーバーは起動を拒否します。ループバックと SSH トンネルの使用を推奨します。
• 認証情報： データツールは環境変数（または .env）から PAYRAM_* を読み取ります。
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY（決済リンク）
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN（JWT、データツール）
  • PAYRAM_EXTERNAL_PLATFORM_ID（デフォルトプロジェクトとして任意で指定）

ローカルサーバーのクライアント設定例（ローカルモードのみ）：

{
  "mcpServers": {
    "payram-local": { "url": "http://localhost:3333/mcp" }
  }
}

---

認証情報：キーの用途

PayRam には2 種類の認証情報があります。混同するとエージェントの処理が止まります。

認証情報	形式	用途	エージェントによる取得方法（ダッシュボード不要）
Merchant API key (PAYRAM_API_KEY, header API-Key)	プロジェクトごとのキー	POST /api/v1/payment（決済リンク）、加盟店への支払い、すべての加盟店のサーバー間呼び出し、および Webhook の署名（X-Payram-Signature）	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — POST /api/v1/external-platform/{id}/api-key を使用してプロジェクトキーを再利用または発行し、~/.payraminfo/merchant-api-key.env に保存します
JWT (Authorization: Bearer)	サインインで取得するアクセス＋リフレッシュトークン	管理者／セットアップ API（プロジェクト、ウォレット、分析）— payram_ops_playbook のレシピとローカルモードのデータツール	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin（環境変数 PAYRAM_EMAIL／PAYRAM_PASSWORD）。~/.payraminfo/headless-tokens.env に保存されます

1 ステップのセットアップフロー（bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet）では、両方が自動的に作成され、保存先が表示されます。API はダッシュボードと同じオリジンの ポート 80/443 を使用します（https://<your-domain>/api/v1/...、またはサーバー上の http://localhost。:8080 は使用しません）。API キーを使うと支払いを作成できるため、サーバー側で管理し、ブラウザーのコードやチャットには決して含めないでください。API を直接呼び出すための設定には、payram_ops_playbook のタスク connect を使用してください。

---

ツールカタログ

カテゴリー	ツール	目的
まずはこちら – インストール	payram_setup_plan	エージェント向けの手順と人間向けの手順、停止条件を含む、個別の優先順位付きインストール計画（準備 → インストール → ルートとサイト URL の設定 → ウォレットと Smart Bridge → API キーと最初のリンク → セキュリティ強化 → 統合）を提供します。
まずはこちら – 診断	payram_doctor, payram_troubleshoot	payram_doctor：URL を指定して行う、認証情報不要の段階的な公開チェック（到達可能性 → ヘルス → TLS → バージョン → ワーカー）です。可能性の高い原因を優先度順に示し、具体的な修正方法を提示します。任意で、何も作成せずに API キーの有効性を確認できます。問題が発生した場合は、最初に実行してください。payram_troubleshoot：症状または貼り付けたエラーに該当する既知の原因と修正方法を提示します。
まずはこちら – 管理	payram_runbook	人間による確認ステップを含む管理タスクの手順：set_site_url、change_domain、ssl_setup、ssl_renewal_fix、firewall_ports、upgrade、backup、restore、add_chain、smart_bridge、mainnet_cutover、operator_setup、rotate_api_key、reset_test_install、shopify_connector、woocommerce_plugin、secure_analytics_mcp。
まずはこちら – 運用	payram_ops_playbook	エージェントが直接 API を実行するレシピ：connect、health、version_check、workers、restart_worker、node_sync、site_url、payment_options、unswept_funds、payments_today、payment_lookup、stuck_payment、create_payment_link、payouts、webhooks、logs、daily_check。
接続	test_payram_connection	読み取り専用の到達可能性／ヘルスチェックと、任意の API キー検証を行います。支払いを作成することはありません。
セットアップ	generate_env_template、generate_setup_checklist、suggest_file_structure、get_agent_setup_flow、onboard_agent_setup	環境変数のひな形、加盟店向けチェックリスト、推奨プロジェクト構成、ヘッドレスエージェントのオンボーディングガイドを提供します。
コンテキスト／ドキュメント	explain_payram_basics、explain_payram_concepts、explain_payment_flow、explain_payram_security、get_payram_links、prepare_payram_test、get_payram_doc_by_id、list_payram_docs、その他	docs/ を情報源とするインラインの Markdown ナレッジを提供し、Copilot が概念に関する質問に回答できるようにします。一部のツールは「test payram と入力してください」というリマインダーを自動で追加します。
統合 – 支払い	generate_payment_sdk_snippet、generate_payment_http_snippet、generate_payment_status_snippet、generate_payment_route_snippet	作成とステータス確認のフローに対応する SDK、HTTP 生コード、または Express／Next.js のルートコードを出力します。
統合 – 払い出し	generate_payout_sdk_snippet、generate_payout_recipient_flow_snippet、generate_payout_status_snippet	直接払い出し（OTP なし）、保存済み受取人を使用する 3 ステップのフロー（受取人の作成 → OTP の検証 → 払い出し）、およびステータスのポーリングに対応します。
統合 – 紹介	generate_referral_sdk_snippet、generate_referral_validation_snippet、generate_referral_status_snippet、generate_referral_route_snippet	紹介の認証、リンク、検証、ステータス、Express／Next.js のルートに対応します。
統合 – Webhook	generate_webhook_handler、generate_webhook_event_router、generate_mock_webhook_event	Express／Next／FastAPI／Gin／Laravel／Spring Boot 用のハンドラー、ファンアウトルーター、cURL／Python／Go／PHP／Java 用の Webhook テスターを生成します。
統合 – 多言語対応の支払い	snippet_* ファミリー（snippet_express_payment_route、snippet_nextjs_payment_route、snippet_fastapi_payment_route、snippet_laravel_payment_route、snippet_go_payment_handler、snippet_spring_payment_controller）	Express、Next.js App Router、FastAPI、Gin、Laravel、Spring Boot 用の事前構築済みルートハンドラーを提供します。
統合 – ウォレットへのチャージ	generate_topup_integration_snippet	既存アプリ向けに、台帳スキーマ、累積クレジット用 Webhook、アトミックな請求書決済を提供します。これにより、過払い、不足、遅延、重複した暗号資産の支払いを、支払い例外ではなく残高状態として処理できます。payram-topup-wallet-integration スキルと併用します。
統合 – プロジェクト評価（ローカルモード）	assess_payram_project	package.json、requirements.txt、composer.json、go.mod、pom.xml、.env などをスキャンします。検出したフレームワーク、環境変数の状態、PayRam の依存関係、ツールの提案を含む、優先順位付きの次の手順を報告します。
スキャフォールディング	scaffold_payram_app	支払い、払い出し、Webhook、ブラウザーコンソールを備えたスターターアプリ一式（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot）を生成します。デプロイ前に、払い出しエンドポイントを独自の管理者認証で保護してください。
ライブデータ（読み取り専用、ローカルモード）	list_platforms、search_payments、lookup_payment、get_payment_summary、get_daily_volume、get_unswept_balances、list_currencies、list_recipients	PayRam のライブデータを照会します。list_currencies は公開情報を扱うためキーは不要です。それ以外のツールは .env 内の JWT トークンを使用します。list_recipients は払い出しの受取人フローと併用します。
ライブ運用（ローカルモード）	create_payment_link（書き込み）、check_payment_readiness、check_node_sync、restart_payram_worker（書き込み）	create_payment_link は API-Key を使用して実際のチェックアウトリンクを作成します。check_payment_readiness は、支払い受付に必要なチェーンごとの不足項目（ウォレット／通貨／リスナー）を報告します。check_node_sync はリスナーワーカーと RPC ノードのヘルス、およびブロックの古さを報告します。ホスト型サーバーでは、対応する payram_ops_playbook のタスクを使用してください。

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

---

ガイド付きワークフロー

0. PayRam をインストールする

1. 「pay.example.com に PayRam をセットアップして」と依頼します（または setup-payram / setup-payram-agent プロンプトを使用します）。
2. アシスタントが payram_setup_plan を呼び出し、各フェーズを案内します。ルートアカウント、Site URL、コールドウォレット、メインネットのガス代など、人による作業が必要な段階では毎回停止します。
3. 最後に payram_doctor、バックアップ（payram_runbook の backup）、および日次チェック（payram_ops_playbook の daily_check）を実行します。

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

1. Copilot に「このプロジェクトに PayRam を統合できますか？」と尋ねます。
2. アシスタントが assess_payram_project をローカルモードで実行し、依存関係のマニフェストと .env を確認します。
3. 推奨手順に従います（payram のインストール、Express/FastAPI/Spring のルートスニペットの作成依頼、ウェブフックの追加など）。
4. 認証情報が有効になったら test_payram_connection を使用し、バックエンドからセルフホスト可能なサーバーに接続できることを確認します。

2. 新しいサンプルをスキャフォールドする

1. 「PayRam の Express デモを作成して」と依頼すると、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 を使用します。

---

開発

コマンド	説明
yarn dev	tsx を使用し、ホットリロードで MCP サーバーを実行します。
yarn build	TypeScript を dist/ にコンパイルします。
yarn lint / yarn format	リポジトリ全体で ESLint と Prettier を実行します。
yarn test	Vitest スイート（tests/）を実行します。
make precommit-test	format → lint → test → build の順に実行します。

このプロジェクトは TypeScript を優先しており（ESM）、Prettier の設定は .prettierrc.json にあります。ESLint は eslint.config.mjs で設定されています。スムーズにコントリビュートするには、Makefile のコミットヘルパー（make commit）を使用してください。

---

トラブルシューティング

まずは payram_doctor を実行してください — 到達性 → ヘルス → TLS → バージョン → ワーカーの順に確認する読み取り専用の呼び出しです。原因を優先度順に提示し、具体的な修正方法も返します。より詳細な確認には、payram_ops_playbook（stuck_payment、node_sync、webhooks、logs）に従ってください。

• Copilot が適切なツールを呼び出しません： Copilot 自動化プロンプトがインストールされていること、および MCP クライアントがサーバーを読み込んでいることを確認してください。想定される自動化を実行するには、「test payram」または「assess my project」を再実行してください。
• test_payram_connection が 401 で失敗します： 有効なプロジェクト API キーであることを確認してください。キーは Authorization ではなく、API-Key ヘッダーで送信します。
• データツールが認証情報を利用できないと表示します： ホスト型サーバーが加盟店の認証情報を保持することはありません。対応する payram_ops_playbook のタスクを使用するか、MCP をローカルモードで実行してください。
• 支払いリンクに http://localhost と表示されます： 人が、公開ドメインを使って Settings → Site URL を保存する必要があります（payram_runbook のタスク set_site_url）。
• ドキュメントツールがファイルが見つからないと表示します： ローカルの docs/payram-docs-live/ ツリーに、要求した Markdown ファイルがあることを確認してください（get_payram_doc_by_id は .. を含むパスを拒否します）。
• サーバーが起動しません： Node 22.12+ がインストールされていることを確認し、yarn install を実行してください。ローカルモードでループバック以外の HOST と PAYRAM_* 認証情報が設定されている場合、MCP_SERVER_TOKEN を設定するまでサーバーは起動しません（ローカルモードを参照）。

それ以外の問題については、src/utils/logger.ts が出力する構造化ログを確認し（LOG_LEVEL=debug を設定）、再現手順を添えて issue または PR を作成してください。