MCP简单聚合器

使用命名空间工具将多个MCP服务器聚合到一个统一的服务器中。

![TypeScript](https://www.typescriptlang.org/) ](https://nodejs.org/) ![License](LICENSE)

概述

MCP简单聚合器结合了多个模型上下文协议（MCP）将服务器整合为一个统一的服务器。它公开了来自所有配置的具有命名空间前缀的子服务器的工具（例如。， serverKey:toolName)，使得在Claude Desktop或其他MCP客户端中同时使用多个MCP服务器变得容易。

主要特点：

✅ 将多个MCP服务器聚合到一个
✅ 自动工具命名空间以避免冲突
✅ 标准Claude桌面配置格式
✅ 环境变量扩展($VAR 和 ${VAR})
✅ 缓慢降级（如果一台服务器崩溃，其余服务器将继续降级）
✅ 超出标准MCP配置的零配置
✅ 基于TypeScript的完全类型安全

快速开始

安装

npm install -g mcp-simple-aggregator

创建配置

使用MCP服务器创建JSON配置文件（使用标准的Claude Desktop格式）：

config.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

设置环境变量

export GITHUB_TOKEN="your-github-token"

运行聚合器

mcp-simple-aggregator --config config.json

与Claude Desktop一起使用

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "aggregator": {
      "command": "mcp-simple-aggregator",
      "args": ["--config", "/path/to/your/config.json"]
    }
  }
}

重新启动Claude Desktop，您的聚合工具将可用！

运作原理

聚合器：

读取您的MCP服务器配置
通过stdio生成所有子MCP服务器
从每个服务器中发现工具
在工具名称前加上服务器密钥（例如。， filesystem:read_file)
将工具调用路由到相应的子服务器
将响应透明地转发回客户端

工具命名

所有工具都以配置中的服务器密钥作为前缀：

配置键	原始工具	聚合工具名称
`filesystem`	`read_file`	`filesystem:read_file`
`github`	`create_issue`	`github:create_issue`
`postgres`	`query`	`postgres:query`

这可以防止在多个服务器提供同名工具时发生命名冲突。

自定义分隔符

默认情况下，工具使用冒号分隔符进行名称分隔(:例如。， github:create_issue).您可以使用自定义分隔符 --separator 论点：

单字符分隔符：

# Dot separator
mcp-simple-aggregator --config config.json --separator "."
# Result: github.create_issue, filesystem.read_file

# Underscore separator
mcp-simple-aggregator --config config.json --separator "_"
# Result: github_create_issue, filesystem_read_file

多字符分隔符：

# Double underscore
mcp-simple-aggregator --config config.json --separator "__"
# Result: github__create_issue, filesystem__read_file

# Double colon
mcp-simple-aggregator --config config.json --separator "::"
# Result: github::create_issue, filesystem::read_file

# Arrow notation
mcp-simple-aggregator --config config.json --separator "->"
# Result: github->create_issue, filesystem->read_file

验证：

分隔符不能为空
分隔符不能包含空格（空格、制表符、换行符）
任何非空格字符或字符串都是有效的

使用案例：

语言规约：使用 . 用于Java/Python样式的命名空间
可读性：使用 __ 为了更清晰的视觉分离
兼容性：使用 - 或 _ 如果 : 与其他工具冲突

自动命令解析

聚合器自动解析 node, npm，以及 npx 命令到绝对路径，以防止“找不到命令”错误，特别是在这些可执行文件不在PATH中的环境中。

它是如何工作的：

当您指定时 "command": "node"，它会自动解析为运行聚合器的相同Node.js可执行文件（例如。， /usr/local/bin/node)
当您指定时 "command": "npm" 或 "command": "npx"，聚合器检查它们是否与Node.js存在于同一目录中
如果找到npm/npx，则将其解析为绝对路径（例如。， /usr/local/bin/npm)
如果未找到，则使用原始命令（依赖于系统PATH）

优点：

✅ 版本一致性：子服务器使用与聚合器相同的Node.js版本
✅ 可靠性：即使PATH配置不正确，也能正常工作
✅ 跨平台：处理窗口 .cmd 自动扩展
✅ 透明：无需更改配置

例子：

{
  "mcpServers": {
    "my-server": {
      "command": "node",  // Automatically resolved to /usr/local/bin/node
      "args": ["server.js"]
    }
  }
}

调试： 启用 --debug 模式查看日志文件中的解析路径：

mcp-simple-aggregator --config config.json --debug
tail -f /tmp/mcp-aggregator-*.log
# Shows: [INFO] Resolved 'node' to '/usr/local/bin/node'

以（权力）否决 要使用特定的Node.js版本，请提供一个绝对路径：

{
  "command": "/usr/local/bin/node18"  // Absolute paths are never modified
}

配置

基本配置

{
  "mcpServers": {
    "server-key": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

领域：

mcpServers （必需）：包含服务器配置的对象
server-key （必需）：服务器的唯一标识符（用作工具前缀）
command （必填）：执行命令
args （可选）：命令行参数数组
env （可选）：传递给服务器的环境变量

环境变量扩展

聚合器支持在字符串值中扩展环境变量：

语法：

外壳样式： $VARIABLE_NAME
支架样式： ${VARIABLE_NAME}

例子：

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_URL": "$API_URL",
        "LOG_LEVEL": "info"
      }
    }
  }
}

跑步前：

export API_KEY="sk-..."
export API_URL="https://api.example.com"

如果缺少任何引用的环境变量，聚合器将在启动时失败，并显示一条明确的错误消息，指示需要哪个变量。

多个服务器实例

您可以使用不同的配置多次运行同一台服务器：

{
  "mcpServers": {
    "fs-home": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "fs-work": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/work/projects"]
    }
  }
}

这给了你 fs-home:read_file 和 fs-work:read_file 作为单独的工具。

命令行选项

mcp-simple-aggregator --config 
 [options]

选项：

`--config

` （必填）：MCP配置JSON文件的路径

--separator ：工具名称间距的自定义分隔符（默认值： :)
--debug：启用调试日志记录到文件
`--log-file

：日志文件的路径（默认值： /tmp/mcp-aggregator-{pid}.log`)

--name ：自定义服务器名称（默认值： mcp-simple-aggregator)
--version ：自定义服务器版本（默认值： 1.0.0)
--help, -h：显示帮助消息

示例：

# Basic usage (default ':' separator)
mcp-simple-aggregator --config config.json

# Custom separator (double underscore)
mcp-simple-aggregator --config config.json --separator "__"

# Custom separator (dot notation)
mcp-simple-aggregator --config config.json --separator "."

# With debug logging (logs to /tmp/mcp-aggregator-{pid}.log)
mcp-simple-aggregator --config config.json --debug

# With custom log file
mcp-simple-aggregator --config config.json --debug --log-file /var/log/mcp.log

# Custom separator and log file
mcp-simple-aggregator --config config.json --separator "__" --debug --log-file /var/log/mcp.log

# Custom server name
mcp-simple-aggregator --config config.json --name my-aggregator

调试日志记录

聚合器支持基于文件的调试日志记录，使MCP JSON-RPC协议的stdio保持干净：

启用调试日志记录：

# Default log location: /tmp/mcp-aggregator-{pid}.log
mcp-simple-aggregator --config config.json --debug

# Custom log location
mcp-simple-aggregator --config config.json --debug --log-file /var/log/mcp.log

实时查看日志：

tail -f /tmp/mcp-aggregator-*.log

日志格式：

2025-11-04T15:18:05.880Z [INFO] Child server initialized: filesystem
2025-11-04T15:18:05.901Z [DEBUG] Discovered 12 tools from filesystem
2025-11-04T15:18:05.950Z [ERROR] Failed to connect to postgres: ECONNREFUSED

重要提示： 调试日志只写入文件，从不写入stdout/stderr。这可以防止JSON-RPC协议污染，从而破坏MCP通信。

用例

1.组合不同的MCP服务器

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "node",
      "args": ["/path/to/postgres-server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

2.多个数据库连接

{
  "mcpServers": {
    "db-prod": {
      "command": "node",
      "args": ["postgres-server.js"],
      "env": {
        "DATABASE_URL": "${PROD_DB_URL}"
      }
    },
    "db-staging": {
      "command": "node",
      "args": ["postgres-server.js"],
      "env": {
        "DATABASE_URL": "${STAGING_DB_URL}"
      }
    }
  }
}

3.自定义MCP服务器

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/my-server/dist/index.js"],
      "env": {
        "CONFIG_PATH": "/etc/my-server/config.yaml"
      }
    }
  }
}

错误处理

启动错误

聚合器使用 快速失败 启动过程中的行为。如果任何服务器无法启动，整个聚合器将退出并显示一条明确的错误消息：

Error: Failed to start server 'postgres': spawn ENOENT

常见启动错误：

缺少配置文件
JSON语法无效
缺失 mcpServers 领域
缺少必填项 command 领域
缺少环境变量
未找到子服务器命令

运行期错误

聚合器使用 故障弱化 在运行时。如果子服务器崩溃：

错误记录到stderr
故障服务器的工具将从注册表中删除
聚合器继续为剩余服务器提供服务

例子：

[ERROR] Server 'postgres' crashed: Connection refused
[INFO] Removing tools for crashed server 'postgres' from registry
[INFO] Aggregator continues serving with 47 tools from remaining servers

发展

从源头构建

# Clone the repository
git clone https://github.com/your-org/mcp-simple-aggregator.git
cd mcp-simple-aggregator

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linter
npm run lint

项目结构

mcp-simple-aggregator/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── server.ts         # MCP server implementation
│   ├── registry.ts       # Tool registry
│   ├── config.ts         # Config parsing & env expansion
│   ├── child-manager.ts  # Child process management
│   └── types.ts          # TypeScript types
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── examples/
│   └── sample-config.json
├── package.json
├── tsconfig.json
└── README.md

运行测试

# Run all tests
npm test

# Run specific test file
npm test -- config.test.ts

# Run with coverage
npm run test:coverage

# Watch mode
npm test -- --watch

故障排除

“找不到配置文件”

解决方案： 为配置文件使用绝对路径：

mcp-simple-aggregator --config /Users/username/config.json

“缺少环境变量：API_KEY”

解决方案： 运行前导出变量：

export API_KEY="your-api-key"
mcp-simple-aggregator --config config.json

“启动服务器'xyz'失败”

解决方案： 验证该命令是否存在以及是否在您的 $PATH:

which npx
which node

或者使用绝对路径：

{
  "command": "/usr/local/bin/node"
}

“找不到工具：文件系统：read_file”

解决方案： 检查工具名称中的拼写错误。使用 tools/list 查看可用工具。

演出

聚合器专为高性能而设计：

初创公司：10多台服务器在\<5秒内
工具发现：响应时间\<1秒
路由开销：每个请求\<50ms
注册表查找：O（1）时间复杂度

技术细节

语言：TypeScript 5.7+
运行时：Node.js v18+（LTS）
运输：仅限stdio
协议: MCP（模型上下文协议）
软件开发工具包: @模型上下文协议/sdk

资源

MCP规范: https://modelcontextprotocol.io
MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
MCP服务器示例: https://github.com/modelcontextprotocol/servers
Claude桌面配置: https://docs.anthropic.com/claude/docs/mcp

贡献

欢迎投稿！请看贡献.md 了解详情。

许可证

MIT许可证-请参阅许可证了解详情。

支持

问题: https://github.com/your-org/mcp-simple-aggregator/issues
讨论: https://github.com/your-org/mcp-simple-aggregator/discussions
文档：参见 /specs/001-mcp-aggregator/ 详细设计文档

______________________________________________________________________

由以下材料制成❤️ 对于MCP社区

MCP Simple Aggregator

快速接入

详细介绍

MCP简单聚合器

概述

快速开始

安装

创建配置

设置环境变量

运行聚合器

与Claude Desktop一起使用

运作原理

工具命名

自定义分隔符

自动命令解析

配置

基本配置

环境变量扩展

多个服务器实例

命令行选项

调试日志记录

用例

1.组合不同的MCP服务器

2.多个数据库连接

3.自定义MCP服务器

错误处理

启动错误

运行期错误

发展

从源头构建

项目结构

运行测试

故障排除

“找不到配置文件”

“缺少环境变量：API_KEY”

“启动服务器'xyz'失败”

“找不到工具：文件系统：read_file”

演出

技术细节

资源

贡献

许可证

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP