PubFi MCP

PubFi MCP Stdio Bridge スモークフィクスチャ

この公開サンプルは、依存関係のないローカルの MCP 互換 stdio ブリッジ兼スモークフィクスチャで、PubFi のホスト型 MCP エンドポイントに対応しています。Node.js 24.19.0 以降の Node.js 24 リリースで実行してください。

このブリッジは、別のハンドシェイクを生成したり、廃止された TypeScript のルートツール実装を実行したり、プロバイダーごとに公開ツールを作成したりするのではなく、最新の server/discover、list、tools/call リクエストを Rust MCP エンドポイントに転送します。すべてのリクエストには完全な MCP 2026-07-28 メタデータが含まれ、ブリッジは標準の HTTP ルーティングヘッダーをミラーリングします。PubFi はプロトコルセッションを作成しません。ブリッジ自体は最新形式の入力のみを受け付けます。MCP 2025-11-25 の initialize 時代との互換性が必要なクライアントは、同じホスト型エンドポイントに直接接続してください。

ホスト型サービスを認証して利用するには、MCP クライアントで PubFi の Streamable HTTP エンドポイント https://mcp.pubfi.ai を設定してください。認証済みのホスト型サービスでは、固定の Registry v2 ツールを 4 つ使用します。カタログの一覧表示と詳細の読み取りは公開されています。このルートで正確な実行を行うには、PubFi API キーまたは OAuth アクセストークンが必要です。アカウント不要の x402 実行が許可される場合は、Bearer 認証情報なしで https://mcp.pubfi.ai/x402 を使用します。アップストリームのプロバイダー認証情報はサーバー側に保持されます。

ツール

• pubfi.capabilities.list
• pubfi.capabilities.get
• pubfi.route.execute
• pubfi.substrate.runtime_upgrade.verify

pubfi.capabilities.list は、不透明な世代バインドカーソルを使用して、簡潔な概要を列挙します。pubfi.capabilities.get は、指定された 1 つの capability id の完全な型付きコントラクトを返します。capability を選択するのはクライアントエージェントです。PubFi が候補を順位付けしたり、意図を推測したりすることはありません。実行可能なパス、メソッド、マッチャー、スキーマ、メソッド固有の PubFi 料金、準備状況は、インストール済みの署名付き Registry 世代からのみ取得されます。

Staging で実行する

リポジトリのルートから実行します。

export STG_PUBFI_API_KEY='<Staging PubFi API key>'
export PUBFI_MCP_ENDPOINT='https://mcp-stg.pubfi.ai'
node examples/agents/pubfi-route-tools-mcp/server.ts

MCP クライアントの設定例：

{
  "mcpServers": {
    "pubfi-route-tools": {
      "command": "node",
      "args": ["examples/agents/pubfi-route-tools-mcp/server.ts"]
    }
  }
}

これらの変数を設定した環境からクライアントを起動するか、シークレットストア連携を使用してください。追跡対象の設定ファイルにキーを記載しないでください。

Production に移行する

Production 用のキーを別途作成し、正確な Production エンドポイントを使用します。

export PROD_PUBFI_API_KEY='<Production PubFi API key>'
export PUBFI_MCP_ENDPOINT='https://mcp.pubfi.ai'
node examples/agents/pubfi-route-tools-mcp/server.ts

上記のクライアント設定では、同じローカルコマンドを使用します。Staging のキーを Production エンドポイントに送信しないでください。

スモークテスト

node examples/agents/pubfi-route-tools-mcp/smoke_pubfi_route_tools_mcp.ts
node --test examples/agents/pubfi-route-tools-mcp/bridge-response.test.ts \
  examples/agents/pubfi-route-tools-mcp/endpoint-policy.test.ts

認証済みのステージング環境でスモークテストを実行する場合：

export STG_PUBFI_API_KEY='<Staging PubFi API key>'
export PUBFI_MCP_ENDPOINT='https://mcp-stg.pubfi.ai'
node examples/agents/pubfi-route-tools-mcp/smoke_pubfi_route_tools_mcp.ts

エンドポイントに応じて選択した呼び出し元キーがない場合、スモークテストでは、最新のディスカバリー、固定されたツール一覧、カタログの全ページ取得、正確な機能の詳細、および実行時の認証情報ゲートを検証します。ステージングの MCP エンドポイントには STG_PUBFI_API_KEY を、本番環境の MCP エンドポイントには PROD_PUBFI_API_KEY を指定しても、同じカタログの読み取りは引き続き公開されています。意図的に実際のリクエストを送信するには、現在のカタログから PUBFI_MCP_EXECUTE_LIVE=1、PUBFI_MCP_SMOKE_RAW_PATH、PUBFI_MCP_SMOKE_METHOD を設定します。任意の PUBFI_MCP_SMOKE_QUERY と PUBFI_MCP_SMOKE_BODY で、ルートに渡す入力を正確に指定できます。PUBFI_MCP_SMOKE_BODY は、ネストされた MCP JSON 値ではなく、コンパクトな ASCII 形式のリクエストボディそのものです（例：{"limit":10}）。スモークテストでプロバイダーのルートや機能 ID を推測することはありません。

ログイン、キーの作成、HTTP チェック、Base Sepolia のテスト範囲、本番環境への移行については、ステージングガイドをご覧ください。

アカウントなしで支払いを行う場合は、公式の x402 MCP クライアントを使用してください。https://mcp-stg.pubfi.ai/x402 または https://mcp.pubfi.ai/x402 への、署名のない対象の pubfi.route.execute 呼び出しは、MCP ツールの結果として PaymentRequired を返します。再試行時には、x402 V2 の支払いオブジェクトを params._meta["x402/payment"] に含めます。決済後の結果には result._meta["x402/payment-response"] が含まれます。このフローでは、PubFi API キー、秘密鍵、または PAYMENT-SIGNATURE HTTP ヘッダーを渡さないでください。

stdio ブリッジで受け付けるのは、本番環境およびステージング環境の正確なルート（https://mcp.pubfi.ai と https://mcp-stg.pubfi.ai）のみです。スコープが限定された呼び出し元キーを転送する前に、ユーザー情報、ポート、別のパス、クエリ文字列、フラグメント、類似ホスト、リダイレクトを拒否します。PUBFI_MCP_ORIGIN はサポートされている別名ではありません。

ホスト環境のデプロイと同等のスモークテストは、次に含まれています：

npm run smoke:mcp-e2e --workspace apps/web -- --json
npm run smoke:mcp-e2e --workspace apps/web -- --execute-live --json

実行境界

pubfi.route.execute は、カタログの一覧と詳細を読み取った後に選択した、正確な raw_path と method を受け付けます。Rust Data Plane は、インストール済みの Registry v2 マッチャーを使用してこの組み合わせを解決し、HTTP ゲートウェイと同じ型付きエグゼキューター、認証情報の権限、Credit 会計、生成処理、およびフェイルクローズ方式の準備状態を使用します。現在のカタログにないルート、またはブロックされているルートは引き続き実行できません。このブリッジによって、プロバイダーの分岐、機能のランキング、互換性のためのルート ID、サプライヤーの調達、自動支払い、または第 2 のカタログ権限が追加されることはありません。