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。