Omnimcp

🚀 OmniMCP

MCP生态系统的语义路由器

在不造成上下文臃肿的情况下，跨多个MCP服务器发现并执行工具

🚀 快速开始

1. 创建MCP服务器配置文件 (mcp-servers.json)：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",  // or "uvx", "docker", any executable
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {},  // optional: environment variables for this server
      "timeout": 30.0,  // optional: seconds to wait for MCP server startup (default: 30)
      "hints": ["file operations", "read write files"],  // optional: help semantic search discover this server
      "blocked_tools": [],  // optional: tools to index but block at runtime
      "ignore": false,  // optional: skip indexing this server entirely
      "overwrite": false  // optional: force re-indexing even if already indexed
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "..."},
      "blocked_tools": ["delete_repository", "fork_repository"]  // indexed but execution blocked
    },
    "elevenlabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {"ELEVENLABS_API_KEY": "..."},
      "hints": [
        "When the user requests audio generation (speech or music), always execute in background mode",
        "Proactively offer to play audio using the ElevenLabs tool when contextually relevant"
      ]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"],
      "env": {"EXA_API_KEY": "..."},
      "hints": [
        "Always execute web searches in background mode to avoid blocking the conversation",
        "Multiple Exa tool calls can be fired in parallel to efficiently gather information from different sources"
      ]
    }
  }
}

2. 设置环境变量：

export OPENAI_API_KEY="sk-..."
export QDRANT_DATA_PATH="/path/to/qdrant_data"
export TOOL_OFFLOADED_DATA_PATH="/path/to/tool_offloaded_data"

3. 对服务器进行索引（建议在启动服务前执行）：

uvx --env-file .env omnimcp index --config-path mcp-servers.json

4. 启动服务器：

# 默认：HTTP传输（推荐）
uvx --env-file .env omnimcp serve --config-path mcp-servers.json --transport http --host 0.0.0.0 --port 8000

# stdio传输（适用于本地MCP客户端 - 需要预先索引）
uvx --env-file .env omnimcp serve --config-path mcp-servers.json --transport stdio

✨ 主要特性

• 语义搜索：通过意图而非名称查找相关工具，工具预先使用嵌入进行索引，在运行时进行搜索，并以文本结果返回（而非工具定义）。
• 懒加载服务器：服务器仅在需要时启动，完成后关闭。
• 渐进式模式加载：仅在执行前获取完整的JSON模式，并在对话中以文本形式返回。
• 内容卸载：大结果进行分块处理，图像进行描述，并存储以便检索。

📦 安装指南

uv pip install omnimcp // or uv add omnimcp 

💻 使用示例

基础用法

search_tools("read CSV files and analyze data")
    → Returns: filesystem.read_file, database.query (ranked by relevance)

get_tool_details("filesystem", "read_file")
    → Returns: Full JSON schema with parameters

manage_server("filesystem", "start")
    → Launches the server process

execute_tool("filesystem", "read_file", {"path": "/data/sales.csv"})
    → Returns: File content (chunked if large)

高级用法

# 长时间运行工具的后台执行
# Queue for background execution
execute_tool("server", "slow_tool", args, in_background=True, priority=1)
# Returns: task_id

# Check status
poll_task_result(task_id)
# Returns: status, result when done

📚 详细文档

问题描述

MCP工具定义会快速消耗令牌，带来诸多问题：

• 上下文臃肿影响性能：工具定义消耗大量令牌，导致实际对话、文档和推理的空间有限，模型将注意力放在工具模式而非任务上。
• 工具增多导致幻觉：大量相似工具会使模型选择错误的工具并产生参数幻觉，工具选择准确性随工具集增长而下降。
• 动态工具加载破坏缓存：推理期间按需加载工具会使提示缓存失效，每次添加新工具都需重新处理整个上下文。
• 工具结果也会使上下文臃肿：单个文件读取或图像编码可能返回大量令牌，堆积在对话历史中，挤出早期上下文。

解决方案

OmniMCP通过暴露单个semantic_router工具作为整个MCP生态系统的唯一入口，解决了上述问题：

传统方式: 58个工具 → 工具定义中55K个令牌
OmniMCP:      1个工具   → ~500个令牌 (semantic_router)

架构：元工具模式

OmniMCP使用元工具模式，类似于Claude Code的Agent Skills系统，通过单个semantic_router工具作为整个MCP生态系统的网关，而非暴露数十个单独的工具。

与Claude Skills的对比

实际示例

Claude Code使用OmniMCP（以前的pulsar-mcp）协调多个MCP服务器生成视频，展示了语义发现、后台执行、跨服务器协调和单一接口等优势。

配置

环境变量

OmniMCP需要配置多个环境变量，包括必需变量、Qdrant连接模式和可选变量。可以通过本地文件存储、Docker Qdrant服务器、Qdrant Cloud或.env文件等方式进行配置。

传输模式

• HTTP传输（默认 - 推荐）：适用于大多数用例，如远程访问、Web集成等。索引在服务器启动时进行一次，多个客户端共享相同的索引数据。
• stdio传输：适用于通过标准输入/输出进行通信的本地MCP客户端。使用前必须先运行uvx omnimcp index以避免启动缓慢。

操作说明

内容管理

大工具结果会自动处理：

• 文本超过5000个令牌 → 分块处理，返回带有引用ID的预览
• 图像 → 卸载，使用GPT - 4视觉进行描述，返回引用
• 音频 → 卸载，返回引用

可以使用get_content(ref_id, chunk_index)检索完整内容。

Docker使用

可以在Docker容器中运行OmniMCP，支持npx（Node.js MCP服务器）和uvx（Python MCP服务器）。提供了构建和运行的命令示例。

开发

git clone https://github.com/milkymap/omnimcp.git
cd omnimcp
uv sync
uv run pytest

相关研究

• ScaleMCP：解决了MCP工具选择的可扩展性问题，强调动态工具检索、自动同步存储和新颖的嵌入策略，验证了语义搜索在MCP生态系统中的重要性。
• Anthropic的高级工具使用：引入的工具搜索、编程工具调用和工具使用示例等功能与OmniMCP的架构一致，强调按需发现和加载工具，仅保留与当前任务相关的内容。

🔧 技术细节

语义搜索实现

工具预先使用嵌入进行索引，在运行时根据意图进行搜索，返回相关工具的文本结果，而非工具定义。

懒加载服务器机制

服务器仅在需要时启动，完成任务后关闭，提高资源利用率。

渐进式模式加载策略

仅在执行前获取完整的JSON模式，并在对话中以文本形式返回，减少上下文占用。

内容卸载处理

大结果进行分块处理，图像进行描述，并存储以便检索，避免上下文臃肿。

📄 许可证

本项目采用MIT许可证，详情请见LICENSE。