AI导哈

语义搜索代理工具

MCPFind是一个高效的MCP工具代理，通过语义搜索减少代理上下文中的工具模式数量，支持多种后端服务器集成，适用于开发效率提升场景。

  • by jcgs2503
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jcgs2503/mcpfind

使用说明

MCPFind

具有语义搜索的上下文高效MCP工具代理。MCPFind位于任何MCP客户端和后端MCP服务器之间，仅用3个元工具（约500个令牌）替换代理上下文中的数百个工具模式。

Agent (Claude Desktop, Cursor, Claude Code, etc.)
  │  Sees only: search_tools, get_tool_schema, call_tool
  ▼
MCPFind Proxy
  ├── Vector search over all tool descriptions
  ├── Per-agent MFU cache for personalized ranking
  └── Routes calls to the correct backend server
  │
  ├──▶ Gmail MCP Server
  ├──▶ GitHub MCP Server
  ├──▶ Slack MCP Server
  └──▶ ... N servers

为什么

随着MCP工具空间的增长，每个工具模式都被转储到代理的上下文中：

工具 上下文标记 效果
10 ~2K 很好
50 ~10K 可管理
200 ~40K 代理选择了错误的工具
1000 ~200K 不可用

MCPFind将上下文保持在约500个令牌，无论其背后存在多少工具。代理通过语义搜索发现工具，按需提取模式，并通过代理调用工具。

安装

# With uv (recommended)
uv tool install mcpfind

# With pip
pip install mcpfind

不需要API密钥-MCPFind默认使用本地嵌入。

快速开始

1.运行安装向导

最简单的开始方法：

mcpfind setup

这将引导您选择嵌入提供商并添加流行的MCP服务器（GitHub、Slack、文件系统、PostgreSQL、Brave Search、Playwright等）。它产生了一个 mcpfind.toml 配置文件。

或者手动创建配置文件

创建 mcpfind.toml:

[proxy]
# Uses local embeddings by default — no API key needed
embedding_provider = "local"          # or "openai"
embedding_model = "all-MiniLM-L6-v2"  # or "text-embedding-3-small" for openai
mfu_boost_weight = 0.15
mfu_persist = true
default_max_results = 5

[[servers]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

[[servers]]
name = "filesystem"
command = "uvx"
args = ["mcp-server-filesystem", "/path/to/allowed/dir"]

2.验证您的设置

# List all tools discovered from your backend servers
mcpfind list-tools --config mcpfind.toml

# Test semantic search
mcpfind search "create a pull request" --config mcpfind.toml

3.运行代理

mcpfind serve --config mcpfind.toml

这将启动MCPFind作为stdio MCP服务器。将MCP客户端指向它，而不是单个服务器。

添加MCP服务器

每个后端服务器都是一个 [[servers]] 配置文件中的条目：

[[servers]]
name = "gmail"              # Unique name (used in search results and call_tool)
command = "uvx"              # Command to launch the server
args = ["mcp-gmail"]         # Arguments passed to the command
env = { GMAIL_TOKEN = "${GMAIL_TOKEN}" }  # Environment variables (supports ${VAR} expansion)

例子

github：

[[servers]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

文件系统：

[[servers]]
name = "filesystem"
command = "uvx"
args = ["mcp-server-filesystem", "/home/user/documents"]

松弛：

[[servers]]
name = "slack"
command = "uvx"
args = ["mcp-server-slack"]
env = { SLACK_BOT_TOKEN = "${SLACK_BOT_TOKEN}" }

自定义/本地服务器：

[[servers]]
name = "my-server"
command = "python"
args = ["-m", "my_mcp_server"]
env = { MY_API_KEY = "${MY_API_KEY}" }

客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mcpfind": {
      "command": "mcpfind",
      "args": ["serve", "--config", "/path/to/mcpfind.toml"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

克劳德代码

添加到您的 .mcp.json:

{
  "mcpServers": {
    "mcpfind": {
      "command": "mcpfind",
      "args": ["serve", "--config", "/path/to/mcpfind.toml"]
    }
  }
}

光标

添加到MCP设置中：

{
  "mcpServers": {
    "mcpfind": {
      "command": "mcpfind",
      "args": ["serve", "--config", "/path/to/mcpfind.toml"]
    }
  }
}

运作原理

MCPFind向代理提供了3个工具：

  1. search_tools --通过自然语言查询查找相关工具（例如，“发送电子邮件”）。返回按语义相似性+使用频率排序的工具名称、服务器和描述。

  2. get_tool_schema --在调用特定工具之前，先提取其完整的输入模式。在实际需要之前，将模式与上下文分开。

  3. call_tool --在后端服务器上执行工具。MCPFind验证呼叫并将其路由到正确的服务器。

代理工作流程

Agent: search_tools("send an email")
  → [{"server": "gmail", "name": "send_email", "score": 0.94}, ...]

Agent: get_tool_schema(server="gmail", tool="send_email")
  → {"type": "object", "properties": {"to": ..., "subject": ..., "body": ...}}

Agent: call_tool(server="gmail", tool="send_email", arguments={...})
  → "Email sent!"

MFU缓存

MCPFind跟踪每个代理最常用的工具。常用工具通过以下方式在搜索结果中获得排名提升 mfu_boost_weight 配置选项（默认值：0.15）。这意味着85%的排名来自语义相似性，15%来自使用频率。

集 mfu_persist = true 在重启过程中保存使用数据（存储在 mfu.db).

配置参考

[proxy]
embedding_provider = "local"                # "local" (default) or "openai"
embedding_model = "all-MiniLM-L6-v2"        # Model name (provider-specific)
mfu_boost_weight = 0.15                     # Frequency boost weight (0.0-1.0)
mfu_persist = true                          # Persist usage data to SQLite
default_max_results = 5                     # Default number of search results

[[servers]]
name = "server-name"     # Required: unique identifier
command = "command"       # Required: executable to launch
args = ["arg1", "arg2"]  # Optional: command arguments
env = { KEY = "value" }  # Optional: environment variables (${VAR} expansion supported)

CLI参考

# Interactive setup wizard
mcpfind setup

# Start the proxy server (stdio MCP transport)
mcpfind serve --config mcpfind.toml

# List all discovered tools from backend servers
mcpfind list-tools --config mcpfind.toml

# Test semantic search
mcpfind search "query" --config mcpfind.toml --max-results 10

发展

# Clone and install
git clone https://github.com/jcgs2503/mcp-lens.git
cd mcp-lens
uv sync

# Run tests
uv run pytest -v

# Lint and format
uv run ruff check .
uv run black --check .

相关 MCP