Tool Filter MCP

🚀 tool-filter-mcp

這是一個 MCP 代理服務器，它通過基於正則表達式的拒絕列表，從上游 MCP 服務器過濾工具。

維護狀態：✅ 是（2025 年秋季）

🚀 快速開始

MCP 代理服務器可通過基於正則表達式的拒絕列表，過濾來自上游 MCP 服務器的工具。

✨ 主要特性

• 工具過濾：使用正則表達式模式阻止特定工具。
• 頭部透傳：添加自定義 HTTP 頭部用於身份驗證。
• 零延遲：緩存工具列表，開銷極小。
• 快速失敗：在連接問題或無效模式下立即報錯。
• 透明代理：將允許的工具調用未經修改地轉發到上游。

📦 安裝指南

使用以下命令進行安裝：

npx @respawn-app/tool-filter-mcp --upstream <url> --deny <patterns>

💻 使用示例

基礎用法

過濾匹配 .*_file$ 模式的工具：

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --deny ".*_file$"

多個模式

使用逗號分隔的模式：

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --deny "get_file_text,create_new_file,replace_text"

帶有身份驗證頭部

添加自定義頭部進行身份驗證：

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --header "Authorization: Bearer your-token-here" \
  --header "X-API-Key: your-api-key"

頭部支持環境變量擴展（如果您的應用尚未擴展）：

npx @respawn-app/tool-filter-mcp \
  --upstream http://localhost:3000/sse \
  --header "Authorization: Bearer $AUTH_TOKEN"

與 Claude Code 配合使用

添加到您的 .mcp.json 文件中：

{
  "mcpServers": {
    "filtered-server": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream",
        "http://localhost:3000/sse",
        "--deny",
        "dangerous_tool_1,dangerous_tool_2"
      ],
      "type": "stdio"
    }
  }
}

帶有身份驗證頭部（支持環境變量擴展）：

{
  "mcpServers": {
    "filtered-server": {
      "command": "npx",
      "args": [
        "@respawn-app/tool-filter-mcp",
        "--upstream",
        "http://localhost:3000/sse",
        "--header",
        "Authorization: Bearer ${API_TOKEN}",
        "--header",
        "X-Custom-Header: $CUSTOM_VALUE"
      ],
      "type": "stdio"
    }
  }
}

📚 詳細文檔

CLI 選項

• --upstream <url>（必需）：上游 MCP 服務器 URL（SSE 傳輸）
• --deny <patterns>：用於過濾工具的逗號分隔的正則表達式模式
• --header <name:value>：傳遞給上游服務器的自定義 HTTP 頭部（可重複以添加多個頭部）
  • 格式：--header "Header-Name: value"
  • 支持環境變量擴展：$VAR 或 ${VAR}
  • 示例：--header "Authorization: Bearer $TOKEN"

要求

• Node.js >= 20.0.0
• 支持 SSE 傳輸的上游 MCP 服務器

📄 許可證

本項目採用 MIT 許可證。

為什麼要使用這個工具？

為了進行有效的上下文工程，我們希望儘量減少無用的標記。目前大多數主流代理（例如 Claude Code）不會 從上下文中移除工具描述。即使某個工具被完全拒絕且未使用，模型仍然會獲取其完整描述，並且仍然會嘗試調用該工具（並收到錯誤消息）。對於像 GitHub、Supabase、JetBrains IDE、Atlassian 這樣的大型 MCP，這對上下文來說是災難性的，會導致 40 - 60k 個無用標記的上下文汙染。您希望您的代理能夠查看 Jira 工單描述？但同時還得處理 44 個用於編輯 Confluence 頁面上的受讓人的無用工具。

這個 MCP 完全解決了這個問題，且不會引入任何額外開銷。本項目完全由 Claude 編寫。歡迎貢獻代碼！