MCP Funnel

🚀 MCP Funnel

Model Context Protocol (MCP) のプロキシサーバーです。複数のMCPサーバーを1つのインターフェースに集約し、Claude DesktopまたはClaude Code CLIを通じて複数のソースからのツールを同時に使用できるようにします。

🚀 クイックスタート

MCP Funnelを使用するには、まず必要な前提条件を満たす必要があります。

• Node.js 18+ と npm/yarn
• TypeScriptを直接実行するための tsx
• プロキシしたいMCPサーバー（個別にインストール）

✨ 主な機能

• 多サーバー集約：任意の数のMCPサーバーに接続できます。
• ツール名前空間化：自動的な接頭辞付与により、名前の衝突を防ぎます（github__create_issue, memory__store_memory）。
• 柔軟なフィルタリング：ワイルドカードパターンを使用して、ツールの表示/非表示を切り替えます。
• 細かい制御：サーバーで無効にできない個々のツールをフィルタリングできます。
• コンテキスト最適化：選択的なフィルタリングにより、MCPツールのコンテキスト使用量を40 - 60％削減します。
• カスタムトランスポート：stdioベースのMCPサーバー（Docker、NPX、ローカルバイナリ）をサポートします。
• サーバーログ接頭辞：どのサーバーが何をログに記録しているかを明確に識別できます。
• 動的ツール検出：初期コンテキスト使用量を削減するための実験的な機能です（制限事項あり）。
• コアツールモード：選択したMCP Funnelツールのみを動的にブリッジして公開する超最小コンテキストモードで、95％以上のコンテキスト削減が可能です。

📦 インストール

READMEに具体的なインストール手順が記載されていないため、このセクションは省略します。

💻 使用例

基本的な使用法

# デフォルトでは、カレントワーキングディレクトリの .mcp-funnel.json を使用します
npx mcp-funnel

# カスタム設定ファイルのパスを指定する場合
npx mcp-funnel /path/to/config.json

高度な使用法

{
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "--env-file",
        ".env",
        "-i",
        "--rm",
        "ghcr.io/github/github-mcp-server"
      ]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  },
  "hideTools": [
    "github__list_workflow_runs",
    "github__get_workflow_run_logs",
    "memory__debug_*",
    "memory__dashboard_*",
    "github__get_team_members"
  ]
}

📚 ドキュメント

設定方法

MCP Funnelは、設定を指定する方法が2通りあります。

1. 暗黙的（デフォルト）：カレントワーキングディレクトリの .mcp-funnel.json を探します。

   npx mcp-funnel  # ./.mcp-funnel.json を使用します
   

2. 明示的：カスタム設定ファイルのパスを指定します。

   npx mcp-funnel /path/to/config.json
   

3. ユーザーベース設定（自動的にマージ） ~/.mcp-funnel/.mcp-funnel.json が存在する場合、プロジェクト設定とマージされます。プロジェクトの値はユーザーベースの値を上書きします。配列は置き換えられます（連結されません）。

設定オプション

• servers：接続するMCPサーバーのレコード（サーバー名をキーとして使用）
  • キー：サーバー名（ツールの接頭辞として使用）
  • command：実行するコマンド
  • args：コマンドの引数（オプション）
  • env：環境変数（オプション）
• alwaysVisibleTools：常に公開され、検出モードをバイパスするツールのパターン（オプション）
• exposeTools：公開する外部ツールのパターンを含める（オプション）
• hideTools：非表示にする外部ツールのパターンを除外する（オプション）
• exposeCoreTools：内部のMCP Funnelツールのパターンを含める（オプション、デフォルトではすべて有効）

alwaysVisibleTools と exposeTools の違い

• ツールを起動時に表示したい場合は、exposeTools のみを使用します。サーバーベースのツールについては、alwaysVisibleTools での重複は必要ありません。
• サーバーツールがすべてのゲート（公開/非表示、将来のパターン変更）をバイパスするようにしたい場合は、alwaysVisibleTools を使用します。これは hideTools よりも優先されます。exposeTools で繰り返す必要はありません。
• コマンドは特殊：コマンドをリストするには、exposeTools を commands__… を使用して指定する必要があります。alwaysVisibleTools は開発コマンドのリストには適用されません。

フィルタリングパターン

パターンは、接頭辞付きのツール名 (serverName__toolName) に対して一致し、ワイルドカード (*) をサポートします。

• 個別のツール：
  • github__get_team_members - GitHubサーバーから特定のツールを非表示にします。
  • memory__check_database_health - Memoryサーバーから特定のツールを非表示にします。
• ワイルドカードパターン：
  • memory__dashboard_* - Memoryサーバーのすべてのダッシュボードツール
  • github__debug_* - GitHubサーバーのすべてのデバッグツール
  • *__workflow_* - 任意のサーバーのすべてのワークフロー関連ツール
  • memory__ingest_* - Memoryサーバーのすべてのインジェストツール
  • *__list_* - 任意のサーバーのすべてのリストツール

コアツールのフィルタリング

MCP Funnelには、検出とブリッジのための内部ツールが含まれています。exposeCoreTools を使用して、どのコアツールを公開するかを制御できます。

"exposeCoreTools": ["discover_*", "load_toolset"]  // 検出ツールとツールセットの読み込みのみを公開する

利用可能なコアツール：

• discover_tools_by_words - キーワードでツールを検索します。
• get_tool_schema - ツールの入力スキーマを取得します。
• bridge_tool_request - ツールを動的に実行します。
• load_toolset - 事前定義されたツールパターンを読み込みます。

exposeCoreTools が指定されていない場合、すべてのコアツールがデフォルトで有効になります。

ツールの可視性制御

MCP Funnelは、どのツールを公開するかを管理するための3段階の可視性システムを提供します。

1. 常に表示されるツール (alwaysVisibleTools)：これらのパターンに一致するツールは、動的検出パターン（空の許可リスト）を使用している場合でも、起動時から常に公開されます。常に利用可能にしたい重要なツールに最適です。

{
  "alwaysVisibleTools": [
    "github__create_pull_request", // この特定のツールを常に表示する
    "memory__store_*" // すべての保存操作を常に表示する
  ]
}

2. 検出可能なツール (exposeTools)：空の許可リスト (exposeTools: []) を使用すると、これらのツールは最初は非表示になりますが、load_toolset を介して動的に検出して有効にすることができます。exposeTools で許可リストに追加されている場合は、起動時から表示されます。
3. 非表示のツール (hideTools)：これらのパターンに一致するツールは、他の設定に関係なく、決して公開されません。

動的検出

最小限の表面積で始めて、必要に応じてツールを有効にするには：

{
  "exposeTools": [],
  "alwaysVisibleTools": [],
  "exposeCoreTools": [
    "discover_*",
    "get_tool_schema",
    "load_toolset",
    "bridge_tool_request"
  ]
}

ランタイムフロー：

• 検索：キーワード（例："context7"）で discover_tools_by_words を使用します。
• 有効化：明示的なツール名またはパターン（例：["context7__resolve_library_id", "context7__get-library-docs"]）で load_toolset を使用します。
• 呼び出し：有効にしたツールを通常通り使用します。

コアツールモード（超低コンテキスト）

コアツールモードでは、動的検出のためにMCP Funnelの内部ツールのみを公開できます。exposeCoreTools を最小限のセットに設定すると、MCP Funnelは100以上ではなく、最小で 3つのツール を公開できます。

1. discover_tools_by_words：キーワードでツールを検索します。
2. get_tool_schema：任意のツールの入力スキーマを取得します。
3. bridge_tool_request：任意のツールを動的に実行します。

使い方の例

• シンプルなワークフロー：

ユーザー: "https://github.com/chris-schra/mcp-funnel のPRを読み込んでください"
Claude: *自動的にGitHubツールを検出し、スキーマを取得し、ブリッジを介して実行します*

• ステップバイステップのワークフロー：

1. "ファイルを操作するためのツールを探してください"
   → Claudeは discover_tools_by_words を使用します
   → 返される：filesystem__read_file, filesystem__write_file など
2. "filesystem__read_file のスキーマを取得してください"
   → Claudeは get_tool_schema を使用します
   → 返される：入力パラメーターと型
3. "README.md ファイルを読み込んでください"
   → Claudeは bridge_tool_request を使用します
   → 実行される：{"tool": "filesystem__read_file", "arguments": {"path": "README.md"}}

利点

• 完全な機能性：すべてのツールにアクセス可能です。
• スマートな検出：Claudeは自然にツールを見つけて使用できます。
• 即座に利用可能：Claude Codeの更新を待つ必要はありません。

トレードオフ

• 検出しにくい（ツールが最初から表示されない）
• 検出/スキーマステップに若干のオーバーヘッドがある
• 利用可能なツールの10％未満を使用するシナリオに最適

動的ツール検出（実験的）

MCP Funnelには、キーワードでツールを検索できる discover_tools_by_words ツールが含まれています。ただし、この機能は現在、限られた有用性しか持っていません。

⚠️ 重要提示

Claude Code CLIは動的ツールの更新をサポートしていません。セッションが開始されると、ツールリストは固定されます。これは、以下のことを意味します。

• discover_tools_by_words ツールは一致するツールを見つけることができます。
• MCP Funnelの内部状態でそれらを「有効に」することができます。
• ただし、セッションを再起動するまで、Claudeは新しく有効にされたツールを認識しません。

これらの問題が解決されるのを楽しみにしています。

• claude-code#7519 - 動的ツール検出のサポート
• claude-code#4118 - ランタイムでのツール更新

これらの機能が実装されると、動的検出により、必要なツールのみをオンデマンドで読み込むことで、初期コンテキストの使用量を大幅に削減できます。

🔧 技術詳細

目的

ほとんどのMCPサーバーは、すべてのツールをフィルタリングオプションなしで公開しており、貴重なコンテキスト空間を消費します。MCP Funnelを使用すると、以下のことが可能になります。

• 複数のMCPサーバーに同時に接続する（GitHub、Memory、Filesystemなど）
• 細かいツールフィルタリング：必要のない特定のツールを非表示にする
• パターンベースのフィルタリング：ワイルドカードを使用して、ツールのカテゴリ全体を非表示にする
• コンテキスト使用量の削減：必要なツールのみを公開することで、トークンの消費量を大幅に削減する

アーキテクチャ

┌────────────────────────┐
│ CLI (e.g. Claude Code) │
└──────┬─────────────────┘
       │ MCP Protocol via stdio
┌──────▼──────┐
│  MCP Funnel │ ← フィルタリングと動的検出が行われる場所
└──────┬──────┘
       │
   ┌───┴──────┬─────────┬─────────┐
   │          │         │         │
┌──▼────┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│GitHub │ │Memory │ │FS     │ │ ...   │ ← 各サーバーはすべてのツールを公開する
└───────┘ └───────┘ └───────┘ └───────┘

MCP Funnelは、以下のように動作します。

1. クライアントとして複数のMCPサーバーに接続する
2. 各サーバーからすべてのツールを受信する
3. フィルタリングルールを適用する
4. フィルタリングされたツールのみをクライアントに公開する
5. ツール呼び出しを適切なバックエンドサーバーにルーティングする

📄 ライセンス

MIT - リポジトリのルートにある LICENSE ファイルを参照してください。

🔒 セキュリティに関する考慮事項

• APIキーを決してコミットしない：環境変数または .env ファイル（gitで無視される）を使用します。
• ファイルシステムアクセス：ファイルシステムサーバーのパスに注意してください。
• Dockerパーミッション：コンテナ化されたサーバーを使用する場合は、適切なDockerソケットアクセスを確保してください。
• ネットワーク分離：機密操作の場合は、分離された環境で実行することを検討してください。

🗺️ ロードマップ

• [x] 強力なサーバー管理のための接続リトライロジック
• [ ] ヘルスモニタリングとステータスレポート
• [x] サーバーが失敗した場合の適切な劣化
• [ ] 構造化ロギングと設定可能なレベル
• [ ] メトリクスとパフォーマンスモニタリング
• [ ] WebSocketトランスポートのサポート
• [ ] 完全な動的ツール検出（Claude Code CLIのサポートに依存）

🧪 テスト

テストスイートを実行するには、以下のコマンドを使用します。

yarn test           # すべてのテストを実行する
yarn test:e2e       # エンドツーエンドテストを実行する
yarn validate       # リント、型チェック、およびフォーマットチェックを実行する

このプロジェクトには、モックMCPサーバーを使用したClaude SDK会話をシミュレートする包括的なエンドツーエンドテストが含まれています。

🤝 コントリビュート

コントリビューションを歓迎します！取り組む必要がある主要な領域は以下の通りです。

1. エラーハンドリング：MCP Funnelをサーバーの障害に対して強化する
2. テスト：Claude Code以外のクライアントに対する包括的なテストカバレッジを追加する
3. ロギング：構造化ロギングを実装する

🙏 謝辞

このプロジェクトは、Anthropicによる Model Context Protocol SDK をベースに構築されています。