mcpdeck

# Meta MCP [](https://github.com/anirudhlath/meta-mcp/actions/workflows/ci.yml) 一款智能MCP（模型上下文协议）路由器。Meta MCP 会创建子MCP服务器，嵌入其工具，并通过单个连接将它们暴露给MCP客户端——无论是直接代理每个工具（命名空间）还是通过`find_tools`元工具，让客户端询问“应该使用什么工具进行X？”并返回最相关的工具而不是整个列表。 有两种运行方式： - **`meta-mcp serve`** — 一个通过stdio为Claude Desktop / Claude Code（或任何MCP客户端）提供的MCP服务器。这是大多数人想要的集成。 - **`meta-mcp start`** — 一个独立的仪表板/路由器进程，带有Gradio网页界面，用于开发、调试工具选择和在MCP客户端之外检查子服务器的健康状况。 不在PyPI上：`meta-mcp`名称被占用，因此通过`uvx`/`uv tool install`进行基于git的安装，如下所示。 ## 先决条件 - **Python 3.11+** - **[uv](https://docs.astral.sh/uv/getting-started/installation/)** — 提供`uvx`和`uv`命令在整个README中使用。如果你只有`pipx`，运行`pipx install uv`以获取`uvx`。 - **Docker或[Apple Container](https://github.com/apple/container)**（macOS Apple Silicon）— 需要运行Qdrant，它支持基于向量的工具选择。如果您只使用 `--no-setup`针对已经运行的Qdrant，或者根本不需要工具选择路由，则可选。 - **[LM Studio](https://lmstudio.ai/)**（可选）— 用于本地嵌入和基于LLM的工具选择。没有它，Meta MCP会自动回落到一个捆绑的`sentence-transformers`模型。 ## 与Claude Desktop / Claude Code一起使用 这是`meta-mcp serve`路径：一个通过stdio的MCP服务器，暴露每个子工具为`{server}__{tool}`，并提供一个`find_tools`元工具。`stdout`保留用于JSON-RPC协议 — 所有日志和人类可读的输出都发送到stderr，因此可以在任何MCP客户端的进程监视器下安全运行。 将以下内容添加到您的MCP客户端配置（Claude Desktop的`claude_desktop_config.json`或Claude Code的`.mcp.json`）： ```json { "mcpServers": { "meta-mcp": { "command": "uvx", "args": [ "--from", "git+https://github.com/anirudhlath/meta-mcp", "meta-mcp", "serve", "--mcp-servers-json", "/absolute/path/to/mcp-servers.json" ] } } } ``` `mcp-servers.json`使用与Claude Desktop相同的`mcpServers`格式，因此您可以将`--mcp-servers-json`指向现有的Claude Desktop配置，以通过Meta MCP的工具选择层重新暴露相同的子服务器： ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"] } } } ``` 从本地checkout工作而不是git+https（例如，在开发时）？将`uv run --project`指向它而不是`uvx`： ```json { "mcpServers": { "meta-mcp": { "command": "uv", "args": [ "run", "--project", "/path/to/meta-mcp", "meta-mcp", "serve", "--mcp-servers-json", "/absolute/path/to/mcp-servers.json" ] } } } ``` `serve`支持`--setup`（默认为`--no-setup`），如果您希望它还检测/启动容器运行时和Qdrant，然后再提供服务 — 请参见`meta-mcp serve --help`。编辑配置后重启Claude Desktop / Claude Code。 Gradio网页界面在`serve`路径上**禁用**，即使您的配置设置`web_ui.enabled: true` — Gradio的`launch()`会打印到stdout，这会破坏JSON-RPC通道。 当您想要仪表板时，请使用`meta-mcp start`。 ### `find_tools`和工具命名空间 每个子工具都发布在`{server_name}__{tool_name}`下（MCP工具名称中不允许使用点，因此`server.tool`变为`server__tool`；任何其他不允许的字符都会替换为`-`，并且名称被截断为MCP规定的64个字符）。直接调用这些工具，就像调用其他MCP工具一样。 `find_tools`是一个内置的元工具，始终列出第一个，它对自然语言查询运行Meta MCP的智能选择（向量/LLM/RAG，取决于配置和成功初始化的内容）： ```json {"name": "find_tools", "arguments": {"query": "read a file from disk", "max_results": 5}} ``` 它返回一个JSON列表，包含`{"name": ..., "description": ..., "server": ...}`，用于最相关的工具，然后您可以通过其命名空间名称直接调用这些工具。这是Meta MCP的主要功能：客户端不必一次看到来自所有子服务器的所有工具，而是可以询问当前任务最相关的工具。 ## 快速入门（仪表板模式） 使用`uvx`直接从此存储库运行仪表板/路由器（`start`）： ```bash # 自动设置：检测Docker/Apple Container，启动Qdrant，打开网页界面，网址为http://localhost:8080 uvx --from git+https://github.com/anirudhlath/meta-mcp meta-mcp # 使用显式配置 uvx --from git+https://github.com/anirudhlath/meta-mcp meta-mcp \ --config my-config.yaml --mcp-servers-json my-servers.json # 或安装为持久的CLI工具 uv tool install git+https://github.com/anirudhlath/meta-mcp meta-mcp ``` 运行`meta-mcp`时没有任何参数（或带有顶级标志，如`--config`/`--web-ui`，但没有子命令），会路由到`start`。 启动时，它将： - 检测并设置容器运行时（Docker或Apple Container Framework） - 启动Qdrant矢量数据库（除非`--no-setup`） - 自动检测现有的`mcp-servers.json`或Claude Desktop配置在标准位置（只读 - 它**不**写入或修改您的Claude Desktop配置） - 启动带有网页界面的Meta MCP服务器，网址为`http://localhost:8080` ## 架构 ```mermaid flowchart TD subgraph Server["Meta MCP server"] Engine["路由引擎<br/>(主要策略 + 回落)"] Vector["矢量搜索路由器"] LLM["LLM路由器"] RAG["RAG路由器"] Pipeline["RAG管道<br/>(文档分块 + 检索)"] Emb["嵌入服务"] Manager["子服务器管理器"] Engine --> Vector Engine --> LLM Engine --> RAG RAG --> Pipeline Vector --> Emb Pipeline --> Emb Engine -->|选定的工具 / 代理调用| Manager end Client["MCP客户端<br/>(Claude Desktop / Claude Code)"] -->|"MCP over stdio<br/>(meta-mcp serve)"| Engine Vector --> Qdrant[("Qdrant<br/>工具 + 文档嵌入")] Pipeline --> Qdrant Emb -->|主要| LMS["LM Studio<br/>嵌入 + 本地LLM"] Emb -.->|回落| ST["sentence-transformers<br/>(本地模型)"] LLM --> LMS Pipeline --> LMS Manager --> C1["子MCP服务器<br/>(例如文件系统)"] Manager --> C2["子MCP服务器<br/>(例如github)"] Manager --> C3["子MCP服务器<br/>(...)"] ``` 主要组件（均在`src/meta_mcp/`下）： - **北向MCP服务器** (`server/mcp_stdio.py`)：`meta-mcp serve`入口点 — 包装`MetaMCPServer`在MCP stdio协议中，发布`{server}__{tool}`名称，并提供`find_tools` - **服务器核心** (`server/meta_server.py`)：初始化和拥有其他所有组件；弹性启动意味着失败的嵌入/向量存储/LLM/RAG组件被记录为警告并留空，而不是崩溃 — 即使没有Qdrant/LM Studio运行，子工具仍被暴露 - **路由策略** (`routing/`)：矢量搜索 (`vector_router.py`)，LLM选择 (`llm_router.py`) 和基于RAG的选择 (`rag_router.py`) - **RAG管道** (`rag/pipeline.py`)：分块和索引子服务器文档，检索相关上下文，并增强选择查询 - **嵌入服务** (`embeddings/service.py`)：LM Studio嵌入（如果可用），自动sentence-transformers回落和本地缓存 - **矢量存储** (`vector_store/qdrant_client.py`)：基于Qdrant的存储和工具及文档嵌入的相似性搜索 - **子服务器管理器** (`child_servers/`)：启动和管理下游MCP服务器的生命周期，并代理工具调用到它们 - **网页界面** (`web_ui/`)：基于Gradio的实时监控和配置仪表板（仅`start`使用；`serve`不使用） - **健康/自动设置** (`health/`)：基础设施检测，健康检查和自动Docker/Apple Container + Qdrant设置 ## 功能 ### 智能工具选择 - **矢量搜索** （默认）：使用嵌入的快速语义相似性 - **LLM选择** ：使用本地LLM（LM Studio）进行AI驱动的工具选择 - **基于RAG的选择** ：使用检索的上下文增强选择查询 ### 自动设置（`start` / `--setup`） - 容器运行时检测：Apple Silicon上的Apple Container Framework或Docker - 自动启动Qdrant - 自动检测现有的`mcp-servers.json`或Claude Desktop配置 ### 网页仪表板（仅`start`） - 实时服务器监控和日志 - 交互式配置编辑器 - 工具使用分析和指标 - 子服务器状态监控 - 可选的HTTP基本身份验证（`web_ui.auth_enabled` + `username`/`password`；启用时失败关闭 — 如果启用但没有同时提供凭证，则UI拒绝启动） ## 配置 ### 自动检测 `meta-mcp start`（和裸`meta-mcp`）在未给出`--config`/`--mcp-servers-json`时，会在以下位置查找配置文件： **主配置文件（meta-server.yaml）：** - `./config/meta-server.yaml` - `./meta-server.yaml` - `~/.meta-mcp/config.yaml` - `/etc/meta-mcp/config.yaml` **MCP服务器配置文件（JSON），只读 - 绝不写入：** - `./mcp-servers.json` - `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS） - `~/.config/claude/claude_desktop_config.json` （Linux/Windows） - `~/.claude/claude_desktop_config.json` `meta-mcp serve`不会自动检测Claude Desktop的`mcp-servers.json`（请显式传递`--mcp-servers-json` — 参见上面的Claude Desktop/Code部分），但如果省略`--config`，它仍然会按以下顺序搜索主配置文件：`./config/meta-server.yaml`，`./meta-server.yaml`，`~/.meta-mcp/config.yaml`，`/etc/meta-mcp/config.yaml`（如果不存在，则回落到内置默认值）。 ### 创建自定义配置 `mcp-servers.json`（Claude Desktop格式）： ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"] }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] } } } ``` `meta-server.yaml`（每个字段都是真实且经过验证的 - 未知字段被拒绝；请参见`examples/simple-config.yaml`和`examples/advanced-config.yaml`以获取完整的工作示例）： ```yaml strategy: primary: "vector" # vector, llm, or rag fallback: "vector" # fallback strategy vector_threshold: 0.4 # similarity threshold max_tools: 10 # max tools to return web_ui: enabled: true port: 8080 auth_enabled: false # set true + username/password for basic auth embeddings: # Primary: LM Studio (optional). Canonical endpoint form ends in /v1 — # /v1/ and /v1/embeddings are also accepted and normalized. lm_studio_endpoint: "http://localhost:1234/v1" lm_studio_model: "nomic-embed-text-v1.5" # Fallback: local sentence-transformers model (automatic) fallback_model: "all-MiniLM-L6-v2" vector_store: type: "qdrant" host: "localhost" port: 6333 ``` 在依赖配置之前，请验证配置文件： ```bash uv run meta-mcp validate-config path/to/meta-server.yaml ``` ## 命令 ``` meta-mcp [OPTIONS] COMMAND [ARGS]... ``` 运行`meta-mcp`时没有子命令，或使用顶级标志（例如`meta-mcp --config x.yaml --web-ui`），会路由到`start`。 | 命令 | 目的 | |---|---| | `serve` | 为Claude Desktop/Code运行MCP服务器（请参见上文） | | `start` | 仪表板/全栈模式，带有自动设置 + 网页界面（默认命令） | | `run` | 在没有自动设置或配置自动检测的情况下启动服务器 | | `validate-config FILE` | 验证配置文件 | | `list-strategies` | 列出可用的工具选择策略 | | `debug-vector` | 对向量搜索索引运行测试查询 | | `regenerate-embeddings` | 重新计算工具嵌入（ `--force` 清除并重建） | | `init-config` | 写入默认`meta-server.yaml` | | `health` | 检查系统健康状况和依赖项 | 每个命令都支持`--help`获取其确切的标志，例如`meta-mcp serve --help`。通过`uvx`运行时，请在这些命令前添加`uvx --from git+https://github.com/anirudhlath/meta-mcp`。 ### `health` ```bash uv run meta-mcp health # 文本输出，出现问题时退出非零 uv run meta-mcp health --output-format json uv run meta-mcp health --fix --setup-docker --download-models ``` ## Docker `docker-compose.yml`运行Qdrant和`meta-mcp`仪表板服务（从存储库的`Dockerfile`构建，使用`config/docker.yaml`，将网页界面绑定到`0.0.0.0:8080`，并将`vector_store.host`指向`qdrant`服务）： ```bash docker-compose up -d # 网页界面：http://localhost:8080 # Qdrant：http://localhost:6333/collections ``` 容器的`CMD`是`meta-mcp start --no-setup --config /app/config/docker.yaml`（Qdrant由compose提供，因此跳过设置）；其`HEALTHCHECK`会访问`http://localhost:8080/`（Gradio仪表板根目录 - 没有`/health` HTTP端点）。 有关使用Apple的容器框架运行Qdrant而不是Docker，请参见[`docs/apple-container-setup.md`](docs/apple-container-setup.md)。 ## 开发 ```bash git clone https://github.com/anirudhlath/meta-mcp.git cd meta-mcp uv sync --extra dev uv run pre-commit install uv run pytest uv run ruff check src/ tests/ uv run ruff format src/ tests/ uv run mypy src/ # 或一次性执行所有操作： ./scripts/check-all.sh # 在本地checkout上针对本地checkout运行stdio服务器： uv run meta-mcp serve --no-setup --mcp-servers-json path/to/mcp-servers.json --log-level DEBUG # 在本地checkout上运行仪表板模式： uv run meta-mcp start --log-level DEBUG ``` 测试标记为`unit`、`integration`（可能启动真正的子进程；不需要Docker/Qdrant - 直接练习弹性初始化）和`slow`。 ## 故障排除 **Qdrant连接失败** ```bash curl http://localhost:6333/collections uv run meta-mcp health --setup-docker ``` **升级v0.2.0之前**：vector-store point IDs and embedding cache keys changed（旧方案使用每个进程的salted hash，产生每次重启时重复的点）。运行此操作后升级： ```bash uv run meta-mcp regenerate-embeddings --force ``` **未找到MCP服务器**：创建`mcp-servers.json`文件，或将`--mcp-servers-json`指向现有的Claude Desktop配置。 **网页界面不可访问**：检查端口是否已被占用（`lsof -i :8080`）或选择另一个端口。 **未使用LM Studio**：确认端点响应`http://localhost:1234/v1/models`，并且`lm_studio_endpoint`已设置（默认为`null/ unset` - 使用fallback `sentence-transformers`模型，除非您显式配置）。 日志：`serve`模式下的stderr日志；`./logs/meta-server.log`和`start`/`run`模式下的网页界面日志查看器（来自配置中的`logging.file`）。 ## 安全考虑 - 以最小权限运行子服务器 - 在子服务器`env`块中使用环境变量进行敏感配置（`${VAR}`展开） - 在使用前审查子服务器配置 - 如果仪表板可从localhost以外访问，请启用`web_ui.auth_enabled`（+`username`/`password`）；如果启用但未同时提供凭证，则UI将拒绝启动 ## 贡献 1. 复刻存储库并克隆您的复刻 2. `uv sync --extra dev && uv run pre-commit install` 3. 创建一个功能分支，进行更改，并添加测试（pre-commit 运行ruff格式/检查和mypy 提交） 4. 在打开PR之前运行 `./scripts/check-all.sh` ## 许可 MIT License - 参见[LICENSE](LICENSE)文件了解详情。