Tool Gating MCP

工具门控MCP

用于模型上下文协议（MCP）的智能代理/路由器，使Claude Desktop和其他MCP客户端能够动态发现和使用来自多个MCP服务器的工具，同时保持单个连接点。该系统通过智能地为每个任务选择最相关的工具来防止上下文膨胀。

🎯 问题

像Claude Desktop这样的MCP客户端必须在启动时加载所有服务器，并且不能在对话期间动态添加服务器。使用多个MCP服务器时：

• Exa服务器：7个搜索工具（网络、研究论文、推特、公司等）
• 操纵者：浏览器自动化工具
• 背景7：文档搜索工具
• 桌面指挥官：18+桌面自动化工具

直接加载所有服务器会导致：

• 🚨 上下文膨胀：100多种工具占用了大部分上下文窗口
• 🔒 静态配置：如果不重新启动Claude，则无法添加服务器
• 💸 成本增加：每次请求消耗的令牌更多
• 🎯 工具选择不当：人工智能难以从太多的选项中做出选择

💡 解决方案

工具门控MCP充当智能代理：

1. 单个连接：Claude Desktop仅连接到工具门控
2. 后端管理：保持与多个MCP服务器的连接
3. 智能发现：使用语义搜索在所有服务器上查找相关工具
4. 动态预配置：仅在令牌预算内加载所需的工具
5. 透明路由：在适当的后端服务器上执行工具

示例：与其用100多个工具配置10个MCP服务器，不如只配置工具门控。然后动态发现并仅使用您需要的2-3个工具。

🚀 特性

• 代理架构：路由到多个后端服务器的单个MCP服务器
• 动态工具发现：无需手动配置即可在所有服务器上查找工具
• 语义搜索：通过自然语言查询找到合适的工具
• 智能资源调配：仅在代币预算内加载相关工具
• 透明执行：将工具调用路由到适当的后端服务器
• 本地MCP服务器：通过mcp代理直接与Claude Desktop集成
• 跨服务器智能：Puppeteer、Exa、Context7等工具的统一视图。
• 令牌优化：与加载所有服务器相比，上下文使用率降低了90%以上
• 零配置：Claude Desktop只需要工具门控配置

📋 先决条件

• Python 3.12+
• 紫外线 包管理器

🔧 安装

1. 克隆存储库：

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

1. 创建并激活虚拟环境：

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

1. 安装依赖项：

uv sync

1. 在开发模式下安装软件包：

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用户界面： http://localhost:8000/docs
• 重新记录： http://localhost:8000/redoc
• MCP端点： http://localhost:8000/mcp （SSE运输）

作为MCP服务器（推荐）

Tool Gating MCP现在是一个直接与Claude Desktop配合使用的原生MCP服务器：

1. 启动服务器:

   tool-gating-mcp

1. 安装mcp代理 （如果尚未安装）：

   uv tool install mcp-proxy

1. 添加到克劳德桌面:

编辑 ~/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 使用您的实际用户名。

1. 重新启动克劳德桌面

您将在Claude中看到Tool Gating的工具，包括：

• discover_tools -根据查询查找相关工具
• provision_tools -在代币预算内选择工具
• register_tool -向注册表添加新工具
• list_mcp_servers -查看已注册的MCP服务器
• 还有更多！

看 MCP本机使用指南 详细说明。

🔍 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桌面配置：仅配置工具门控MCP

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

1. 后端服务器连接：工具门控连接到多个MCP服务器

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

1. 自然语言发现：“我需要搜索研究论文”

   Claude → discover_tools → Semantic Search → Returns relevant tools

1. 实时工具执行：工具按需加载

   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个增益）

1. 实时加载：工具在执行过程中按需验证和加载
2. MCP格式化：所选工具根据MCP协议进行格式化

🔧 配置

系统使用合理的默认值，但可以配置：

• 最大令牌数：每个请求默认2000个令牌
• Max工具：默认每个请求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}

1. 系统返回相关工具：只有研究工具，没有文件编辑器
2. 编排器配置工具:

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

1. LLM直接与MCP服务器执行：使用配置的工具定义

人工智能辅助服务器注册

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许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

• 内置于 快速API
• 语义搜索由 句子转换
• MCP协议集成 fastapi mcp
• 演示UI使用 富有的