mcp-facade

汎用 MCP ファサード: 1 つの stdio プロセスが上流の MCP サーバーの前に立ち、設定されたツールの一部だけを、スキーマを圧縮して公開します。さらに、カタログの残りをオンデマンドで利用可能にする 3 つのメタツール(discover, describe, call)を備えています。

なぜ

MCP サーバーが公開するすべてのツールは、すべてのリクエストで JSON スキーマとしてモデルのコンテキストに注入されます。40 個のツールを持つ大きなサーバーは、実際の作業を行う前に、セッションごとに数万トークンを消費します。その大半は、呼び出さないツールです。

このファサードは経済性を逆転させます。実際に使うツール(used に列挙)にだけ、完全なスキーマのトークンを支払い、しかもそれを要点まで圧縮します。その他はすべてメタツール経由で発見可能なままであり、メタツールは合計 3 つの小さなスキーマしか使いません。

Related MCP server: @zhangzwd/mcp-gateway

動作

• stdio MCP サーバーとして実行します: bun run facade.ts --server <name>。上流サーバーごとに 1 プロセスです。

• facade.servers.json(facade.ts の隣)を読み込み、<name> エントリを選択します。

• 最初の tools/list で上流カタログを取得してディスクにキャッシュします(~/.omp/agent/mcp-facade/catalogs/<name>.json、TTL 7 日)。上流接続は遅延で、最初の使用まで何も接続しません。

• 各 used ツールを、圧縮されたスキーマで配信します:

  • すべての description 文字列(ツールレベルと JSON スキーマ内)は最初の一文だけにし、最大 140 文字に短縮します。

  • $comment、examples、default キーは再帰的に削除します。

  • 構造(types、properties、required、enums)はそのまま保持します。

  • ツール名は小文字化されます。ルックアップは大文字小文字を区別しません。

• 常に 3 つのメタツールを追加します(下記参照)。

• tools/list の時点でカタログを取得できない場合、メタツールのみを提供することにフォールバックし、理由を stderr に記録します。

• 呼び出しを上流に転送します。credentialId を持つ HTTP 上流で、401/不正/トークン有効期限切れエラーが発生した場合、トークンの強制リフレッシュを 1 回行い、再試行を 1 回だけ実行します。

メタツール

典型的なエージェントの流れ: discover "worklog" → describe addworklog → call { tool: "addworklog", args: { ... } }

要件

• Bun(ファサードが TypeScript を直接実行します)。

• OAuth で保護された HTTP 上流の場合: ~/.bun/bin/omp に OMP omp CLI がインストールされ、その資格情報が認証済みであるか必要です。ファサードは omp token <credentialId>(再試行時は omp token --force-refresh <credentialId>)でトークンを取得します。秘密情報は設定に一切保存されません。

• 環境変数(API キー、トークン)を必要とする stdio 上流の場合: ~/.claude.json に Claude ホスト設定が存在し、そのサーバーの env ブロックを含んでいる必要があります(後述の envFrom を参照)。

インストール

bun install
cp facade.servers.example.json facade.servers.json   # then edit

facade.servers.json は gitignore されています。ローカルパスを含む可能性があるためです。

設定

facade.servers.json はサーバー名を、上流サーバーと使用ツールのリストにマッピングします:

{
  "<name>": {
    "upstream": {
      // HTTP upstream (Streamable HTTP transport):
      "url": "https://mcp.example.com/v1/mcp",
      "credentialId": "mcp_oauth:profile:default:https://mcp.example.com/v1/mcp" // optional

      // …or stdio upstream:
      // "command": "/usr/local/bin/npx",
      // "args": ["-y", "@example/mcp-server"],
      // "envFrom": "claude:<server-name>",  // optional: pull env from ~/.claude.json mcpServers.<server-name>.env
      // "env": { "EXTRA": "value" }          // optional: merged on top
    },
    "used": ["tool_one", "tool_two"]  // exposed directly; everything else via meta-tools
  }
}

注意:

• used エントリは大文字小文字を区別せずマッチし、小文字で配信されます。

• envFrom は現在 claude:<name> プレフィックスのみサポートしています。

• used が空リストでも有効です。その場合、ファサードはメタツールのみを公開します。

ホストへの登録

ホストの MCP 設定をファサードに向けます。上流サーバーごとに 1 エントリを置きます:

{
  "mcpServers": {
    "acme": {
      "command": "/path/to/bun",
      "args": ["run", "/path/to/mcp-facade/facade.ts", "--server", "acme-http"]
    }
  }
}

⚠️ stdout はプロトコル

stdio トランスポートは stdout を専有します。絶対にログ、診断、デバッグ出力を stdout に書き出さないでください。stdout 上の出力は JSON-RPC ストリームを破壊し、ホストを on 固まらせます。ファサードは stderr にのみログを出力します(console.error)。フォークした場合もそのようにしてください。

制限

• ハードコードされたパス: カタログキャッシュは ~/.cache/agent/mcp-facade/catalogs/、OMP バイナリは ~/.bun/bin/omp、envFrom は ~/.claude.json のみを読みます。

• カタログは 1 回の listTools 呼び出しで取得されます。ページネーションも tools/list_changed の処理もありません。最新の上流ツール変更を取り込むには、ファサードを再起動する(または 7 日間の TTL の期限が切れるのを待つ)必要があります。

• discover は単純な文字列部分一致で、最大 10 件の結果です。

• 認証失敗時の再試行は 1 回のみです。それ以外の上流のエラーはそのまま伝播します。

• 上流の prompts、resources、sampling には対応していません。ツールのみです。