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 编写。欢迎贡献代码！