OneMCP-通用MCP聚合器

一种通用的模型上下文协议（MCP）聚合器，将多个外部MCP服务器组合成一个具有渐进发现功能的统一接口。

版本0.2.0 -具有元工具架构的生产就绪通用聚合器，可提高效率和可扩展性。

与官方合作建造 MCP Go SDK 来自Anthropic/Google合作。

什么是OneMCP？

OneMCP是一个 通用MCP聚合器 即：

聚合来自多个外部MCP服务器的工具
支持具有类型安全注册的自定义内部工具
公开统一的元工具接口以减少令牌使用
支持渐进式工具发现（加载模式前搜索）
适用于任何符合MCP标准的服务器

为什么选择OneMCP？

当使用许多MCP服务器时，将数百个工具直接暴露给LLM会消耗大量的令牌和上下文窗口。正如Anthropic的使用MCP执行代码文章中，元工具模式通过以下方式解决了这个问题：

减少代币开销：只公开2个元工具，而不是加载50多个工具模式（数万个令牌）
渐进式发现：LLM仅在需要时搜索相关工具
保存上下文：实际对话和代码的空间更大，工具定义的空间更小
优雅地缩放：添加新服务器而不增加基线令牌使用量

OneMCP将此模式实现为 通用聚合器 适用于：

任何支持MCP的LLM（Claude、OpenAI、Gemini、通过Claude Desktop的本地模型等）
任何符合MCP标准的服务器
任何部署场景（本地开发、生产API、代理框架）

建筑

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

益处

代币效率：减少99%-公开2个元工具，而不是数百个单独的工具
渐进式发现：首先搜索，仅加载所需工具的模式
通用：适用于任何符合MCP标准的服务器
灵活的：支持外部服务器（配置）和内部工具（Go代码）
类型安全：内置工具利用Go的类型系统和自动模式推理

性能优化

OneMCP包括几个针对令牌效率和速度的优化：

可配置的结果限制：默认情况下，每次搜索返回5个工具（可通过配置 .onemcp.json)
LLM支持的语义搜索：Claude、Codex或Copilot智能地将查询与工具匹配
渐进式发现：四个细节级别（仅名称→ 总结→ 详细的→ 完整示意图）
架构缓存：启动时缓存外部工具架构，无重复获取
延迟加载：模式仅在通过detail_level明确请求时发送

令牌使用示例（默认5个工具）：

names_only 搜索：总共约50个令牌
summary 搜索：总共约200-400个代币
full_schema 搜索：总计约2000-5000个代币

LLM支持的语义搜索

OneMCP使用 基于LLM的语义搜索 智能地将您的查询与正确的工具相匹配。它不是使用精确的关键字匹配，而是使用AI模型来理解意图和上下文。

例子： 查询“为页面拍照”→ finds browser_screenshot

根据您的需求从3个LLM提供商中选择：

1. 克劳德（人为，默认）

最适合： 使用Claude模型实现最高质量的语义理解
速度： 每次搜索约3-5秒
质量： 优秀-克劳德·海库/十四行诗/关于工具描述的作品理由
内存： \<10MB RAM
要求： Claude CLI(brew install anthropics/claude/claude-code)
成本： 使用本地Claude CLI

{
  "settings": {
    "searchProvider": "claude",
    "claudeModel": "haiku"  // Options: "haiku" (fast, default), "sonnet", "opus"
  }
}

2. 法典（OpenAI GPT-5）

最适合： OpenAI最新的Codex工具搜索模型
速度： 每次搜索约3-5秒
质量： 优秀-GPT-5 Codex推理
内存： \<10MB RAM
要求： Codex CLI
成本： 使用Codex CLI

{
  "settings": {
    "searchProvider": "codex",
    "codexModel": "gpt-5-codex-mini"  // Options: "gpt-5-codex-mini" (default), "gpt-5-codex"
  }
}

3. 副驾驶（GitHub Copilot）

最适合： GitHub Copilot集成用于工具发现
速度： 每次搜索约3-5秒
质量： 优秀-通过GitHub Copilot使用Claude Haiku 4.5
内存： \<10MB RAM
要求： 带Copilot的GitHub CLI(gh copilot)
成本： 需要GitHub Copilot订阅

{
  "settings": {
    "searchProvider": "copilot",
    "copilotModel": "claude-haiku-4.5"  // Default model
  }
}

它是如何工作的： 对于每次搜索，OneMCP都会将您的查询+所有工具模式发送给LLM，LLM会根据语义相关性对工具进行排名。LLM比传统的关键字搜索更了解上下文、同义词和意图。

性能比较：

提供者	延迟	内存	质量	要求
克劳德（俳句）	~3s	\<10MB	⭐⭐⭐⭐⭐	Claude CLI
Codex（gpt-5-Codex-mini）	~3s	\<10MB	⭐⭐⭐⭐⭐	Codex CLI
副驾驶	~3s	\<10MB	⭐⭐⭐⭐⭐	GitHub CLI+Copilot

建议： 使用 克劳德与俳句 （默认）以实现速度和质量的最佳平衡。

技术

OneMCP由以下组件构建：

官方MCP Go SDK v1.1.0-人类/谷歌协作
转到1.25 -现代、高效、类型安全
JSON-RPC 2.0 -MCP通信的标准协议
多个传输 -Stdio（命令）、HTTP（SSE）等

官方SDK提供：

具有自动模式推理的类型安全工具注册
多种传输选项（通过CommandTransport的stdio、通过SSE的HTTP、StreamableHTTP、内存中用于测试）
内置客户端，用于连接外部服务器
完全支持MCP协议功能

支持的交通工具：

命令（stdio）：执行本地命令，并使用JSON-RPC通过stdin/stdout进行通信-最常见于本地工具
流式HTTP：使用JSON-RPC over HTTP通过可选的SSE流连接到远程基于HTTP的MCP服务器（MCP规范2025-03-26+）-非常适合云服务
在存储器中：直接进程内通信-对测试有用

协议详细信息：

所有MCP通信使用 JSON-RPC 2.0 用于消息编码
标准运输：通过stdin/stdout发送JSON-RPC消息
可流式HTTP传输：通过HTTP POST/GET使用可选的服务器发送事件（SSE）进行JSON-RPC流式响应

- 单端点（无双端点复杂性） - 支持请求/响应和流媒体 - 会话管理通过 Mcp-Session-Id 头球 - 自动重新连接 Last-Event-ID 为了韧性

快速开始

1.构建聚合器

# Build for macOS
GOOS=darwin GOARCH=amd64 go build -o one-mcp ./cmd/one-mcp

# Build for 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.运行聚合器

# Start OneMCP aggregator (uses .onemcp.json by default)
./one-mcp

# Use custom config file
ONEMCP_CONFIG=/path/to/config.json ./one-mcp

# Or with custom server name/version
MCP_SERVER_NAME=my-aggregator MCP_SERVER_VERSION=0.2.0 ./one-mcp

# Enable debug logging
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"
      }
    }
  }
}

Meta-Tools API金属工具

1. `tool_search`

发现具有可选过滤功能的可用工具。使用 基于LLM的语义搜索 智能地将您的查询与最相关的工具相匹配。退货 默认情况下，每个查询有5个工具 （可通过以下方式配置 .onemcp.json).

论据：

query （可选）-自然语言搜索查询（例如，“截图”、“导航到网页”、“读取文件”）
category （可选）-按类别筛选（例如，“浏览器”、“文件系统”）
detail_level （可选）-返回的详细程度：

- "names_only" -只需工具名称和类别（最小标记） - "summary" -名称、类别和描述（默认） - "detailed" -包括参数架构 - "full_schema" -包含所有详细信息的完整架构

offset （可选）-分页时要跳过的结果数（默认值：0）

语义搜索： LLM理解自然语言查询、上下文和意图。它在语义上将您的查询与工具描述相匹配，而不仅仅是通过关键字。

架构缓存： 外部工具模式在启动时缓存，以便快速重复搜索。

混合方法： 搜索返回 默认情况下，共有5个工具 （可配置）加上a schema_file 路径(/tmp/onemcp-tools-schema.json)包含 所有具有完整模式的可执行工具 （仅限外部和内部工具，不包括已通过MCP公开的元工具 tools/list).为了进行全面的工具探索，请使用文件系统工具搜索模式文件，而不是在搜索结果中分页。这减少了令牌的使用，同时保持了对完整工具信息的访问。

示例-基本搜索：

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

示例-分页搜索：

{
  "tool_name": "tool_search",
  "arguments": {
    "query": "browser",
    "category": "browser",
    "detail_level": "detailed",
    "offset": 5
  }
}

退货：

{
  "total_count": 21,
  "returned_count": 5,
  "offset": 0,
  "limit": 5,
  "has_more": true,
  "schema_file": "/tmp/onemcp-tools-schema.json",
  "message": "Showing 5 of 21 tools. For complete tool list with full schemas, search with filesystem tools in: /tmp/onemcp-tools-schema.json",
  "tools": [
    {
      "name": "playwright_browser_navigate",
      "category": "browser",
      "description": "Navigate to a URL",
      "schema": {...}
    },
    {
      "name": "playwright_browser_click",
      "category": "browser",
      "description": "Click an element",
      "schema": {...}
    }
  ]
}

2. `tool_execute`

按名称执行单个工具。

论据：

tool_name （必填）-工具名称（例如。， playwright_browser_navigate)
arguments （必填）-工具特定参数

例子：

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

配置

OneMCP使用 .onemcp.json 用于配置。配置文件支持 带注释的JSON（JSONC） 格式-添加 // 用于行评论或 /* */ 用于记录配置的块注释。

看 .onemcp.json.example 查看带有注释的完整示例。

设置

配置OneMCP行为：

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

可用设置：

searchResultLimit （number）-每个搜索查询返回的工具数量。默认值：5。较低的值会减少令牌的使用，但需要更多的搜索才能发现。
searchProvider （string）-用于语义搜索的LLM提供程序。选项： "claude" （默认）， "codex", "copilot"。有关详细信息，请参阅上面的“LLM驱动语义搜索”部分。
claudeModel （string）-使用Claude模型时 searchProvider 是 "claude".选项： "haiku" （默认）， "sonnet", "opus".
codexModel （string）-使用Codex模型时 searchProvider 是 "codex".选项： "gpt-5-codex-mini" （默认）， "gpt-5-codex".
copilotModel （string）-复制模型在以下情况下使用 searchProvider 是 "copilot"默认值： "claude-haiku-4.5".

外部服务器配置

在中定义外部MCP服务器 mcpServers 部分。OneMCP支持多种传输类型：

1.命令传输（stdio） -最常见的是，运行本地命令：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",                // Command to execute
      "args": ["-y", "@playwright/mcp"], // Command arguments
      "env": {                          // Optional: Environment variables
        "DEBUG": "1"
      },
      "category": "browser",           // Optional: Category for grouping tools
      "enabled": true                  // Required: Whether to load this server
    }
  }
}

2.HTTP传输（流式HTTP） -通过HTTP连接到远程MCP服务器：

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp", // HTTP endpoint URL (Streamable HTTP)
      "category": "api",
      "enabled": true
    }
  }
}

注： OneMCP对所有HTTP连接使用流式HTTP传输（MCP规范2025-03-26+）。这是取代已弃用的SSE传输的现代标准。

配置字段：

command （string）-要执行的命令（用于stdio传输）
args （array）-命令参数（仅限stdio）
url （string）-HTTP端点URL（用于流式HTTP传输）
env （object）-环境变量（仅限stdio）
category （string）-分组工具的类别
enabled （boolean）-是否加载此服务器

注：提供其中之一 command 或 url不是两者都有。

环境变量

ONEMCP_CONFIG -配置文件路径（默认：“.onemcp.json”）
MCP_SERVER_NAME -服务器名称（默认：“一个mcp聚合器”）
MCP_SERVER_VERSION -服务器版本（默认：“0.2.0”）
MCP_LOG_FILE -日志文件路径（默认：“/tmp/one mcp.Log”）
MCP_LOG_LEVEL -日志级别：“调试”或“信息”（默认值：“信息”）

工具命名约定

外部工具会自动以其服务器名称作为前缀：

browser_navigate 从 playwright → playwright_browser_navigate
take_screenshot 从 chrome → chrome_take_screenshot

这可以防止在聚合多个服务器时发生命名冲突。

渐进式发现工作流程

LLM的推荐工作流程：

搜索工具：使用 tool_search 使用过滤器查找相关工具
获取详细的架构：使用 detail_level: "full_schema" 您计划使用的工具
执行工具：使用 tool_execute 有经过验证的论点

对话示例：

User: "Take a screenshot of example.com"

LLM: Let me search for screenshot tools...
→ tool_search(query="screenshot", detail_level="full_schema")

LLM: Found playwright_browser_navigate and playwright_browser_take_screenshot. 
Let me navigate first...
→ tool_execute(tool_name: "playwright_browser_navigate", arguments: {url: "https://example.com"})

LLM: Now taking screenshot...
→ tool_execute(tool_name: "playwright_browser_take_screenshot", arguments: {filename: "example.png"})

日志记录

日志被写入由指定的文件 MCP_LOG_FILE （默认值： /tmp/one-mcp.log):

time=2025-11-11T10:00:00.000+00:00 level=INFO msg="Starting OneMCP aggregator server over stdio..." name=one-mcp-aggregator version=0.2.0
time=2025-11-11T10:00:01.000+00:00 level=INFO msg="Loaded external MCP server" name=playwright tools=21 category=browser
time=2025-11-11T10:00:02.000+00:00 level=INFO msg="Registered tool" name=playwright_browser_navigate category=browser
time=2025-11-11T10:00:03.000+00:00 level=INFO msg="Executing tool" name=playwright_browser_navigate
time=2025-11-11T10:00:04.000+00:00 level=INFO msg="Tool execution successful" name=playwright_browser_navigate execution_time_ms=245

故障排除

外部服务器无法启动

检查命令路径是否正确 .onemcp.json
验证是否设置了所需的环境变量
检查登录 MCP_LOG_FILE 启动错误
手动测试服务器命令： command args...

未找到工具

使用 tool_search 验证该工具是否存在
检查工具名称是否包括服务器前缀（例如。， playwright_browser_navigate)
验证是否在中启用了外部服务器 .onemcp.json

工具执行失败

使用 tool_search 随着 detail_level: "full_schema" 查看所需参数
检查参数类型是否与架构匹配
查看日志以了解详细的错误消息

发展

项目结构

.
├── cmd/
│   └── one-mcp/
│       └── main.go              # Entry point
├── internal/
│   ├── mcp/
│   │   └── server.go            # Aggregator server with meta-tools
│   ├── tools/
│   │   ├── types.go             # Tool type definitions
│   │   └── registry.go          # Tool registry and dispatcher
│   └── mcpclient/
│       └── client.go            # External MCP server client
├── .onemcp.json                 # Configuration (settings + external servers)
├── go.mod
└── README.md

添加外部服务器

只需添加到 mcpServers 部分在 .onemcp.json -无需更改代码：

{
  "settings": {
    "searchResultLimit": 5,
    "searchProvider": "claude"
  },
  "mcpServers": {
    "your-server": {
      "command": "/path/to/your-mcp-server",
      "args": ["--config", "config.json"],
      "env": {
        "API_KEY": "your-key"
      },
      "category": "custom",
      "enabled": true
    }
  }
}

OneMCP将自动：

启动外部服务器
获取其工具列表
在工具名称前加上 your-server_
使工具可通过以下方式发现 tool_search
路线 tool_execute 调用外部服务器

添加内部工具

备注：添加内部工具需要修改OneMCP源代码。您需要：

克隆此存储库： git clone https://github.com/radutopala/onemcp.git
进行更改（请参阅下面的步骤）
重新生成二进制文件： go build -o one-mcp ./cmd/one-mcp

要将自定义内部工具直接添加到OneMCP聚合器中，请执行以下操作：

1.使用输入/输出类型定义工具结构

// internal/tools/mytools.go
package tools

type CalculatorInput struct {
    A int `json:"a" jsonschema:"First number"`
    B int `json:"b" jsonschema:"Second number"`
}

type CalculatorOutput struct {
    Result int `json:"result" jsonschema:"Calculation result"`
}

2.实施工具处理器

func (s *AggregatorServer) handleCalculate(ctx context.Context, req *mcp.CallToolRequest, input CalculatorInput) (*mcp.CallToolResult, any, error) {
    result := CalculatorOutput{
        Result: input.A + input.B,
    }
    
    resultJSON, _ := json.Marshal(result)
    
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: string(resultJSON)},
        },
    }, nil, nil
}

3.在服务器中注册该工具

// internal/mcp/server.go - in registerMetaTools() or a new registration function
func (s *AggregatorServer) registerCustomTools(server *mcp.Server) error {
    mcp.AddTool(server, &mcp.Tool{
        Name:        "calculate",
        Description: "Add two numbers together",
    }, s.handleCalculate)
    
    return nil
}

4.调用注册功能

// In NewAggregatorServer(), after registerMetaTools()
if err := aggregator.registerCustomTools(server); err != nil {
    return nil, fmt.Errorf("failed to register custom tools: %w", err)
}

要点

类型安全：官方SDK会自动从你的Go结构推断模式
结构标签：使用 jsonschema:"description" 记录论点
经办人签名: func(ctx, *CallToolRequest, InputType) (*CallToolResult, any, error)
响应格式：始终在TextContent中返回JSON，以与元工具保持一致
无需架构：如果你不提供 inputSchema 在Tool结构中，它是根据您的输入类型推断出来的

示例：回声工具

// Simple echo tool that returns what you send
type EchoInput struct {
    Message string `json:"message" jsonschema:"Message to echo back"`
}

func (s *AggregatorServer) handleEcho(ctx context.Context, req *mcp.CallToolRequest, input EchoInput) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: input.Message},
        },
    }, nil, nil
}

// Register in server
mcp.AddTool(server, &mcp.Tool{
    Name:        "echo",
    Description: "Echo back a message",
}, s.handleEcho)

内部工具通过以下方式直接暴露 tools/list 与2个元工具一起使用，无需使用即可立即使用 tool_search.

何时使用内部工具与外部服务器：

使用外部服务器 （推荐）：对于大多数用例，不需要更改代码，只需要配置
使用内部工具：仅当您需要与OneMCP的核心逻辑紧密集成，或希望自定义业务逻辑使用Go的类型安全时

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请在GitHub上打开问题或PR。

One MCP (Radutopala)

快速接入

详细介绍