Onemcp

🚀 OneMCP - 通用MCP聚合器

OneMCP是一個通用的模型上下文協議（MCP）聚合器，它通過漸進式發現功能，將多個外部MCP服務器整合為一個統一的接口。該聚合器能有效解決在處理多個MCP服務器時，直接向大語言模型（LLM）暴露大量工具所導致的大量令牌和上下文窗口消耗問題。

版本信息

當前版本為0.2.0，這是一個可用於生產環境的通用聚合器，採用元工具架構，提高了效率和可擴展性。

構建基礎

OneMCP基於Anthropic和Google合作開發的官方MCP Go SDK構建。

🚀 快速開始

1. 構建聚合器

# 為macOS構建
GOOS=darwin GOARCH=amd64 go build -o one-mcp ./cmd/one-mcp

# 為Linux構建
GOOS=linux GOARCH=amd64 go build -o one-mcp-linux ./cmd/one-mcp

2. 配置OneMCP

創建.onemcp.json文件：

{
  "settings": {
    "searchResultLimit": 5,
    "searchProvider": "claude"
  },
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "category": "browser",
      "enabled": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "category": "filesystem",
      "enabled": true
    }
  }
}

3. 運行聚合器

# 啟動OneMCP聚合器（默認使用.onemcp.json）
./one-mcp

# 使用自定義配置文件
ONEMCP_CONFIG=/path/to/config.json ./one-mcp

# 或指定自定義服務器名稱/版本
MCP_SERVER_NAME=my-aggregator MCP_SERVER_VERSION=0.2.0 ./one-mcp

# 啟用調試日誌
MCP_LOG_LEVEL=debug ./one-mcp

4. 與MCP客戶端配合使用

將其添加到你的MCP客戶端配置中。例如，在Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "onemcp": {
      "command": "/path/to/one-mcp",
      "env": {
        "MCP_SERVER_NAME": "my-aggregator",
        "MCP_LOG_FILE": "/tmp/onemcp.log"
      }
    }
  }
}

✨ 主要特性

聚合功能

• 聚合來自多個外部MCP服務器的工具。
• 支持通過類型安全的註冊方式添加自定義內部工具。
• 提供統一的元工具接口，減少令牌使用。

漸進式發現

• 支持漸進式工具發現（在加載模式之前進行搜索）。
• 可與任何符合MCP標準的服務器配合使用。

性能優化

• 可配置結果限制：默認每次搜索返回5個工具（可通過.onemcp.json配置）。
• 大語言模型驅動的語義搜索：使用Claude、Codex或Copilot智能匹配查詢與工具。
• 漸進式發現：提供四個詳細級別（僅名稱 → 摘要 → 詳細信息 → 完整模式）。
• 模式緩存：外部工具模式在啟動時緩存，避免重複獲取。
• 懶加載：僅在通過詳細級別顯式請求時才發送模式。

📦 安裝指南

依賴環境

• 官方MCP Go SDK v1.1.0
• Go 1.25
• JSON-RPC 2.0

構建步驟

參考快速開始部分的構建聚合器步驟。

💻 使用示例

基礎用法

# 構建並運行OneMCP聚合器
GOOS=darwin GOARCH=amd64 go build -o one-mcp ./cmd/one-mcp
./one-mcp

高級用法

# 使用自定義配置文件和服務器名稱/版本
ONEMCP_CONFIG=/path/to/config.json MCP_SERVER_NAME=my-aggregator MCP_SERVER_VERSION=0.2.0 ./one-mcp

📚 詳細文檔

元工具API

1. tool_search

用於發現可用工具，可選擇過濾條件。使用大語言模型驅動的語義搜索智能匹配查詢與最相關的工具。默認每次查詢返回5個工具（可通過.onemcp.json配置）。 參數說明：

• query（可選）：自然語言搜索查詢（例如，"take a screenshot", "navigate to webpage", "read files"）。
• category（可選）：按類別過濾（例如，"browser", "filesystem"）。
• detail_level（可選）：返回的詳細程度：
  • "names_only"：僅返回工具名稱和類別（最少令牌）。
  • "summary"：返回名稱、類別和描述（默認）。
  • "detailed"：包含參數模式。
  • "full_schema"：包含所有詳細信息的完整模式。
• offset（可選）：分頁時跳過的結果數量（默認：0）。

示例 - 基本搜索：

{
  "tool_name": "tool_search",
  "arguments": {
    "query": "navigate",
    "detail_level": "summary"
  }
}

2. tool_execute

用於執行單個工具。 參數說明：

• tool_name（必需）：工具名稱（例如，playwright_browser_navigate）。
• arguments（必需）：工具特定的參數。

示例：

{
  "tool_name": "tool_execute",
  "arguments": {
    "tool_name": "playwright_browser_navigate",
    "arguments": {
      "url": "https://example.com"
    }
  }
}

配置說明

設置

{
  "settings": {
    "searchResultLimit": 5,
    "searchProvider": "claude"
  }
}

可用設置：

• searchResultLimit（數字）：每次搜索查詢返回的工具數量。默認：5。較低的值可減少令牌使用，但可能需要更多搜索來發現工具。
• searchProvider（字符串）：用於語義搜索的大語言模型提供商。選項："claude"（默認），"codex"，"copilot"。
• claudeModel（字符串）：當searchProvider為"claude"時使用的Claude模型。選項："haiku"（默認），"sonnet"，"opus"。
• codexModel（字符串）：當searchProvider為"codex"時使用的Codex模型。選項："gpt-5-codex-mini"（默認），"gpt-5-codex"。
• copilotModel（字符串）：當searchProvider為"copilot"時使用的Copilot模型。默認："claude-haiku-4.5"。

外部服務器配置

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "category": "browser",
      "enabled": true
    }
  }
}

配置字段說明：

• command（字符串）：要執行的命令（適用於stdio傳輸）。
• args（數組）：命令參數（僅適用於stdio）。
• url（字符串）：HTTP端點URL（適用於可流式HTTP傳輸）。
• env（對象）：環境變量（僅適用於stdio）。
• category（字符串）：工具分組的類別。
• enabled（布爾值）：是否加載此服務器。

環境變量

• ONEMCP_CONFIG：配置文件路徑（默認：".onemcp.json"）。
• MCP_SERVER_NAME：服務器名稱（默認："one-mcp-aggregator"）。
• MCP_SERVER_VERSION：服務器版本（默認："0.2.0"）。
• MCP_LOG_FILE：日誌文件路徑（默認："/tmp/one-mcp.log"）。
• MCP_LOG_LEVEL：日誌級別："debug" 或 "info"（默認："info"）。

🔧 技術細節

架構設計

OneMCP Aggregator
    ├── Meta-Tools (2)
    │   ├── tool_search        - Discover available tools
    │   └── tool_execute       - Execute a single tool
    │
    ├── Internal Tools (optional)
    │   └── Custom Go-based tools with type-safe handlers
    │
    └── External MCP Servers (configured via .onemcp.json)
        ├── Playwright (21 tools) - Browser automation
        ├── Filesystem (N tools) - File operations
        └── Your Server (N tools) - Any MCP-compliant server

技術選型

• 官方MCP Go SDK v1.1.0：提供類型安全的工具註冊和自動模式推斷。
• Go 1.25：現代、高效且類型安全的編程語言。
• JSON-RPC 2.0：MCP通信的標準協議。
• 多種傳輸方式：支持Stdio（命令）、HTTP（SSE）等。

性能優化

• 大語言模型驅動的語義搜索：使用Claude、Codex或Copilot智能匹配查詢與工具。
• 模式緩存：外部工具模式在啟動時緩存，避免重複獲取。
• 懶加載：僅在通過詳細級別顯式請求時才發送模式。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

貢獻說明

歡迎貢獻代碼！請在GitHub上提交問題或拉取請求。