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上提交问题或拉取请求。