Tool Gating MCP

Tool Gating MCP

Model Context Protocol（MCP）用のインテリジェントなプロキシ／ルーターです。Claude Desktop などの MCP クライアントが、単一の接続先を維持しながら、複数の MCP サーバーのツールを動的に検出して使用できるようにします。タスクごとに最も関連性の高いツールだけをインテリジェントに選択し、コンテキストの肥大化を防ぎます。

🎯 課題

Claude Desktop などの MCP クライアントは、起動時にすべてのサーバーを読み込む必要があり、会話中にサーバーを動的に追加できません。複数の MCP サーバーを使用する場合：

• Exa サーバー：7 個の検索ツール（ウェブ、研究論文、Twitter、企業など）
• Puppeteer：ブラウザー自動化ツール
• Context7：ドキュメント検索ツール
• Desktop Commander：18 個以上のデスクトップ自動化ツール

すべてのサーバーを直接読み込むと、次の問題が発生します：

• 🚨 コンテキストの肥大化：100 個以上のツールがコンテキストウィンドウの大部分を消費します
• 🔒 静的な設定：Claude を再起動せずにサーバーを追加できません
• 💸 コストの増加：リクエストごとに消費するトークンが増えます
• 🎯 ツール選択の精度低下：選択肢が多すぎると、AI が適切なツールを選ぶのに苦労します

💡 解決策

Tool Gating MCP は、次の機能を備えたインテリジェントなプロキシとして動作します：

1. 単一の接続：Claude Desktop は Tool Gating にのみ接続します
2. バックエンド管理：複数の MCP サーバーへの接続を維持します
3. スマートな検出：セマンティック検索を使用して、すべてのサーバーから関連するツールを見つけます
4. 動的な提供：トークン予算内で必要なツールのみを読み込みます
5. 透過的なルーティング：適切なバックエンドサーバーでツールを実行します

例：100 個以上のツールを持つ 10 個の MCP サーバーを設定する代わりに、Tool Gating だけを設定します。その後、必要な 2～3 個のツールだけを動的に検出して使用できます。

🚀 機能

• プロキシアーキテクチャ：複数のバックエンドサーバーにルーティングする単一の MCP サーバー
• 動的なツール検出：手動で設定せずに、すべてのサーバーからツールを検索
• セマンティック検索：自然言語で適切なツールを検索
• スマートな提供：トークン予算内で関連するツールのみを読み込み
• 透過的な実行：ツール呼び出しを適切なバックエンドサーバーにルーティング
• ネイティブ MCP サーバー：mcp-proxy を介して Claude Desktop と直接連携
• サーバー横断のインテリジェンス：Puppeteer、Exa、Context7 などのツールを統合して表示
• トークンの最適化：すべてのサーバーを読み込む場合と比べ、コンテキストの使用量を 90% 以上削減
• 設定不要：Claude Desktop で必要なのは Tool Gating の設定だけです

📋 前提条件

• Python 3.12+
• uv パッケージマネージャー

🔧 インストール

1. リポジトリをクローンします：

git clone https://github.com/yourusername/tool-gating-mcp.git
cd tool-gating-mcp

2. 仮想環境を作成して有効化します：

uv venv
source .venv/bin/activate  # On Unix/macOS
# .venv\Scripts\activate  # On Windows

3. 依存関係をインストールします：

uv sync

4. 開発モードでパッケージをインストールします：

uv pip install -e .

🏃 サーバーの起動

HTTP API サーバーとして

# Start the server
tool-gating-mcp

# Or with uvicorn for development
uvicorn tool_gating_mcp.main:app --reload

サーバーは http://localhost:8000 で起動します

API ドキュメント：

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc
• MCP エンドポイント：http://localhost:8000/mcp（SSE トランスポート）

MCP サーバーとして（推奨）

Tool Gating MCP は、Claude Desktop と直接連携するネイティブ MCP サーバーになりました：

1. サーバーを起動します：

   tool-gating-mcp
   

2. mcp-proxy をインストールします（まだインストールされていない場合）：

   uv tool install mcp-proxy
   

3. Claude Desktop に追加します：

   ~/Library/Application Support/Claude/claude_desktop_config.json を編集します：

   {
     "mcpServers": {
       "tool-gating": {
         "command": "/Users/YOUR_USERNAME/.local/bin/mcp-proxy",
         "args": ["http://localhost:8000/mcp"]
       }
     }
   }
   

   注：YOUR_USERNAME を実際のユーザー名に置き換えてください。

4. Claude Desktop を再起動します

Claude で Tool Gating のツールを使用できるようになります。次のようなツールがあります：

• discover_tools - クエリに基づいて関連するツールを検索します
• provision_tools - トークン予算内でツールを選択します
• register_tool - 新しいツールをレジストリに追加します
• list_mcp_servers - 登録済みの MCP サーバーを表示します
• その他多数！

詳しい手順は、MCP Native Usage Guide を参照してください。

🔍 API エンドポイント

ツールの検出

POST /api/tools/discover

セマンティック検索に基づいて関連するツールを検出します。

リクエスト：

{
  "query": "I need to perform calculations",
  "tags": ["math", "calculation"],
  "limit": 5
}

レスポンス：

{
  "tools": [
    {
      "tool_id": "calculator",
      "name": "Calculator",
      "description": "Perform mathematical calculations",
      "score": 0.95,
      "matched_tags": ["math", "calculation"],
      "estimated_tokens": 50
    }
  ],
  "query_id": "uuid",
  "timestamp": "2024-01-01T00:00:00"
}

ツールのプロビジョニング

POST /api/tools/provision

トークン予算を適用しながら、LLM で使用するツールを選択してフォーマットします。

リクエスト：

{
  "tool_ids": ["calculator", "web-search"],
  "max_tools": 3
}

レスポンス：

{
  "tools": [
    {
      "name": "Calculator",
      "description": "Perform mathematical calculations",
      "parameters": { "type": "object", "properties": {...} },
      "token_count": 50
    }
  ],
  "metadata": {
    "total_tokens": 150,
    "gating_applied": true
  }
}

🔄 仕組み

1. Claude Desktop の設定：Tool Gating MCP のみを設定します

   {
     "mcpServers": {
       "tool-gating": {
         "command": "mcp-proxy",
         "args": ["http://localhost:8000/mcp"]
       }
     }
   }
   

2. バックエンドサーバーへの接続：Tool Gating が複数の MCP サーバーに接続します

   Tool Gating → puppeteer (browser tools)
              → exa (search tools)
              → context7 (documentation)
              → filesystem (file operations)
   

3. 自然言語による検出：「研究論文を検索したいです」

   Claude → discover_tools → Semantic Search → Returns relevant tools
   

4. リアルタイムのツール実行：ツールは必要に応じて読み込まれます

   execute_tool("exa_research_paper_search", {...}) → Validates → Loads → Executes
   

   プロビジョニングは不要です！ツールは、使用時に動的に読み込まれます。

🎯 使用例

デモの実行

# Make sure the server is running first
tool-gating-mcp

# In another terminal, run the interactive demo
python demo.py

手動テスト

# Test the server endpoints
python test_server.py

例：数学ツールの検索

import httpx
import asyncio

async def find_math_tools():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/api/tools/discover",
            json={
                "query": "I need to solve equations",
                "tags": ["math"],
                "limit": 3
            }
        )
        tools = response.json()["tools"]
        print(f"Found {len(tools)} relevant tools")
        for tool in tools:
            print(f"- {tool['name']}: {tool['score']:.3f}")

asyncio.run(find_math_tools())

🧪 テスト

# Run all tests
pytest

# Run with coverage
pytest --cov=tool_gating_mcp

# Run specific test files
pytest tests/test_discovery_service.py -v

# Run integration tests
pytest tests/test_integration.py -v

📊 アーキテクチャの詳細

1. ツールの登録：ツールはメタデータ、タグ、トークン数の推定値とともに登録されます
2. セマンティック検索：ユーザーのクエリは、センテンストランスフォーマーを使用して埋め込みベクトルに変換されます
3. 関連性のスコアリング：ツールは以下に基づいてスコア付けされます：
   • クエリとツールの埋め込みベクトル間のコサイン類似度
   • タグの一致（一致するタグごとに 0.2 の加点）
4. リアルタイム読み込み：実行中にツールが検証され、必要に応じて読み込まれます
5. MCP フォーマット：選択したツールは MCP プロトコルに従ってフォーマットされます

🔧 設定

システムには適切なデフォルト値が設定されていますが、変更も可能です：

• 最大トークン数：リクエストあたりのデフォルトは 2000 トークンです
• 最大ツール数：リクエストあたりのデフォルトは 10 個です
• 埋め込みモデル：all-MiniLM-L6-v2（384 次元の埋め込みベクトル）

📖 ドキュメント

• ツール検出システム - セマンティック検索とタグがどのように連携するか
• 新しい MCP サーバーの追加 - 新しいサーバーを統合するための手順ガイド
• AI 統合ガイド - AI アシスタントが MCP サーバーを自動的に追加する方法
• アーキテクチャの概要 - システム設計とコンポーネント間の連携

📁 プロジェクト構成

tool-gating-mcp/
├── src/
│   └── tool_gating_mcp/
│       ├── __init__.py
│       ├── main.py              # FastAPI application
│       ├── api/
│       │   ├── models.py        # Pydantic models
│       │   ├── tools.py         # Tool management endpoints
│       │   └── mcp.py           # MCP server endpoints
│       ├── models/
│       │   └── tool.py          # Domain models
│       └── services/
│           ├── discovery.py     # Semantic search
│           ├── gating.py        # Tool selection logic
│           └── repository.py    # Tool storage
├── tests/
│   ├── test_*.py               # Test files
│   └── test_integration.py     # Integration tests
├── demo.py                     # Interactive demo
├── test_server.py              # Manual testing script
└── pyproject.toml              # Project configuration

🔌 MCP サーバーとの統合

MCP サーバーのツール登録

# 1. Clear existing demo tools
DELETE /api/tools/clear

# 2. Register tools from your MCP servers
POST /api/tools/register
{
  "id": "exa_research_paper_search",
  "name": "research_paper_search",
  "description": "Search across 100M+ research papers with full text access",
  "tags": ["search", "research", "academic"],
  "estimated_tokens": 250,
  "server": "exa",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "numResults": {"type": "number", "default": 5}
    },
    "required": ["query"]
  }
}

LLM オーケストレーションでの使用

1. LLM がユーザーのクエリを受け取る：「量子コンピューティングに関する最近の論文を探してください」
2. オーケストレーターがツールゲーティングに問い合わせる：

   POST /api/tools/discover
   {"query": "find research papers", "limit": 3}
   

3. システムが関連するツールを返す：ファイル編集ツールではなく、研究用ツールのみを返します
4. オーケストレーターがツールをプロビジョニングする：

   POST /api/tools/provision
   {"tool_ids": ["exa_research_paper_search"], "max_tokens": 500}
   

5. LLM が MCP サーバーを直接使用して実行する：プロビジョニングされたツール定義を使用します

AI によるサーバー登録

AI アシスタントは、新しい MCP サーバーを自動的に追加できます：

# User: "Add this Slack MCP server to tool gating"
# AI: Connects to server, discovers tools, and registers everything

POST /api/mcp/ai/register-server
{
  "server_name": "slack",
  "config": {
    "command": "npx",
    "args": ["@slack/mcp-server"],
    "env": {"SLACK_TOKEN": "xoxb-..."}
  },
  "tools": [
    // AI provides all discovered tools with metadata
  ]
}

# Result: Slack server + all tools registered and ready for use

🧑‍💻 開発

コード品質

# Format code
black .

# Run linter
ruff check . --fix

# Type checking
mypy .

# Run all checks
black . && ruff check . --fix && mypy . && pytest

新しいツールの追加

ツールは services/repository.py のリポジトリに追加できます：

Tool(
    id="my-tool",
    name="My Tool",
    description="Description for semantic search",
    tags=["category", "function"],
    estimated_tokens=100,
    parameters={
        "type": "object",
        "properties": {...},
        "required": [...]
    }
)

🤝 コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加え、テストを追加します
4. 品質チェックを実行します（black、ruff、mypy、pytest）
5. 変更をコミットします（git commit -m 'Add amazing feature'）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

🙏 謝辞

• FastAPI を使用して構築
• セマンティック検索には Sentence Transformers を使用
• fastapi-mcp による MCP プロトコル統合
• Rich を使用したデモ UI