MCP Server Proxy

一个强大的代理服务器，可以聚合多个 MCP (Model Context Protocol) 服务器，让 LLM 客户端通过单一连接访问来自多个后端服务器的工具、资源和提示模板。

✨ 核心特性

• 🔗 多服务器聚合: 同时连接多个 MCP 服务器（已测试 25+ 工具）
• 🚀 多传输协议支持:
  • 代理对外: stdio、HTTP (SSE)、Streamable HTTP
  • 后端连接: stdio、HTTP (SSE)、Streamable HTTP 混合连接
• 🏷️ 命名空间管理: 通过可配置命名空间避免命名冲突
• 📡 实时通知转发: 转发后端服务器的通知到客户端
• 🔥 热重载配置: 配置文件变更自动生效，无需重启服务
• 🌐 Web管理界面: 现代化的Web界面管理MCP服务器配置
• ✅ 协议完全兼容: 完全兼容 MCP 规范和 SDK v1.17.5
• 🔧 会话管理: HTTP 传输的高级会话处理
• 🛡️ 健壮错误处理: 完善的错误处理和连接管理
• 📊 全面日志记录: 可配置级别的详细日志

🏗️ 架构设计

基础架构

LLM Client (Cursor/Claude Desktop)
    ↓ (JSON-RPC 2.0 via stdio/HTTP/Streamable)
MCP Server Proxy (多传输协议支持)
    ↓ (Multiple connections via stdio/HTTP/Streamable)
Backend MCP Servers (Everything, Memory, SSE, Streamable HTTP, etc.)

多传输协议架构

┌─────────────────┐    ┌──────────────────────────────────┐
│   LLM Client    │    │        MCP Server Proxy          │
│                 │    │                                  │
│ ┌─────────────┐ │    │ ┌─────────────┐ ┌──────────────┐ │
│ │ stdio       │◄┼────┼►│ stdio       │ │ BackendMgr   │ │
│ │ HTTP (SSE)  │◄┼────┼►│ HTTP (SSE)  │ │ CapabilityAgg│ │
│ │ Streamable  │◄┼────┼►│ Streamable  │ │ RequestRouter│ │
│ └─────────────┘ │    │ └─────────────┘ │ NotifyMgr    │ │
└─────────────────┘    │                 └──────────────┘ │
                       └──────────────────────────────────┘
                                    │
                       ┌────────────┼────────────┐
                       ▼            ▼            ▼
              ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
              │Everything   │ │Simple SSE   │ │Streamable   │
              │Server       │ │Server       │ │HTTP Server  │
              │(stdio)      │ │(HTTP)       │ │(Streamable) │
              └─────────────┘ └─────────────┘ └─────────────┘

代理服务器对客户端表现为单一的 MCP 服务器，同时管理与多个后端服务器的连接。

🚀 快速开始

环境要求

• Node.js >= 18.0.0
• npm >= 8.0.0
• 操作系统: macOS, Linux, Windows

1. 项目构建

1.1 安装依赖

cd mcp-proxy
npm install

1.2 构建项目

npm run build

构建完成后，编译后的文件将位于 dist/ 目录中。

2. 启动后端测试MCP服务器

2.1 启动 SSE Server (端口 3004)

# 在新的终端窗口中执行
node examples/server-sse.js

服务器将在 http://localhost:3004/sse 启动，提供 2 个工具。

2.2 启动 Streamable HTTP Server (端口 3005)

# 在新的终端窗口中执行
node examples/server-streamable-http.js

服务器将在 http://localhost:3005/mcp 启动，提供 3 个工具。

2.3 Everything Server (通过 stdio)

Everything Server 通过 stdio 协议启动，无需单独启动，将由 Proxy 自动管理。

3. 启动 Admin 管理页面

# 在新的终端窗口中执行
npm run dev:admin examples/config.json

管理界面将在 http://localhost:3001 启动。

4. 启动 Proxy Server

4.1 基本启动 (支持热重载)

# 使用默认配置启动
node dist/index.js examples/config.json

4.2 开发模式启动

# 开发模式，支持自动重启
npm run dev examples/config.json

4.3 启用调试日志

# 启用详细调试日志
LOG_LEVEL=DEBUG node dist/index.js examples/config.json

4.4 使用 MCP Inspector 测试

# 使用inspector启动
npx @modelcontextprotocol/inspector node dist/index.js examples/config.json

5. 配置Cursor连接

5.1 创建 Cursor MCP 配置

编辑或创建 ~/.cursor/mcp.json 文件：

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "node",
      "args": ["/path-to-mcp-proxy/mcp-proxy/dist/index.js", "/path-to-mcp-proxy/mcp-proxy/examples/config.json"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

5.2 重启 Cursor

完全关闭并重新启动 Cursor 以加载新的 MCP 配置。

6. 完整启动序列

按以下顺序启动所有组件：

# 终端 1: 构建项目
npm run build

# 终端 2: 启动 SSE Server
node examples/server-sse.js

# 终端 3: 启动 Streamable Server
node examples/server-streamable-http.js

# 终端 4: 启动管理界面
npm run dev:admin examples/config.json

# 终端 5: 启动 Proxy Server
LOG_LEVEL=DEBUG node dist/index.js examples/config.json

# 终端 6: 测试功能
npx @modelcontextprotocol/inspector node dist/index.js examples/config.json

7. 验证功能

7.1 使用 MCP Inspector 测试

Inspector 将显示：

• 聚合的工具列表 (预期: 16 个工具)
• 资源列表 (预期: 10 个资源)
• 提示模板列表 (预期: 3 个提示模板)

7.2 验证命名空间

工具名称应该带有命名空间前缀：

• everything.* - Everything Server 的工具 (11个)
• sse.* - SSE Server 的工具 (2个)
• stream.* - Streamable Server 的工具 (3个)

7.3 测试热重载功能

编辑 examples/config.json，例如禁用一个服务器，保存后观察：

• Proxy 日志显示服务器被动态移除
• 工具数量实时变化
• Cursor 中的工具列表自动更新

8. 常见问题排查

8.1 端口冲突

如果遇到端口占用问题：

# 查找占用端口的进程
lsof -ti:3004 | xargs kill -9
lsof -ti:3005 | xargs kill -9

8.2 Cursor 连接问题

1. 检查 MCP 配置文件路径是否正确
2. 确保 Proxy 服务器正在运行
3. 查看 Cursor 的 MCP 日志 (Cmd+Shift+U → "MCP Logs")

环境变量

• LOG_LEVEL: 日志级别 (DEBUG, INFO, WARN, ERROR)
• ADMIN_PORT: 管理界面端口 (默认: 3001)

Configuration

Create a configuration file (JSON format) to define your backend servers:

{
  "serverInfo": {
    "name": "mcp-server-proxy",
    "version": "1.0.0"
  },
  "servers": [
    {
      "id": "everything",
      "name": "Everything Server",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"],
      "transport": "stdio",
      "namespace": "everything",
      "enabled": true
    },
    {
      "id": "simple-sse",
      "name": "Simple SSE Server",
      "transport": "http",
      "url": "http://localhost:3004/sse",
      "namespace": "sse",
      "enabled": true
    },
    {
      "id": "streamable-http",
      "name": "Streamable HTTP Server",
      "transport": "streamable",
      "url": "http://localhost:3005/mcp",
      "namespace": "stream",
      "enabled": true
    }
  ]
}

Configuration Options

通用配置

• id: 服务器唯一标识符
• name: 人类可读的服务器名称
• transport: 传输协议类型 ("stdio", "http", "streamable")
• namespace: 工具/资源/提示模板的命名空间前缀
• enabled: 是否启用该服务器

stdio 传输配置

• command: 启动服务器的命令
• args: 命令参数 (可选)
• env: 环境变量 (可选)

HTTP/Streamable 传输配置

• url: 服务器的 HTTP URL
  • HTTP SSE: http://localhost:3004/sse
  • Streamable HTTP: http://localhost:3005/mcp

🔥 热重载功能

MCP Proxy支持配置文件热重载，无需重启即可应用配置变更：

工作原理

1. 文件监听: 自动监听配置文件变化
2. 智能差异检测: 只更新发生变化的服务器
3. 动态管理: 新增/删除/修改服务器配置
4. MCP通知: 自动通知客户端能力变化

使用方法

# 启动支持热重载的代理
node dist/index.js examples/config.json

# 修改配置文件，变更会自动生效
# 查看日志确认重载成功

支持的变更类型

• ✅ 添加新服务器
• ✅ 删除现有服务器
• ✅ 修改服务器配置
• ✅ 启用/禁用服务器

🌐 Web管理界面

现代化的Web界面管理MCP服务器配置：

功能特性

• 服务器列表: 查看所有配置的MCP服务器
• 实时状态: 显示服务器连接状态和能力统计
• 添加服务器: 通过表单添加新的MCP服务器
• 编辑配置: 修改现有服务器配置
• 一键操作: 启用/禁用/删除服务器
• 实时更新: 配置变更立即生效

访问方式

1. 启动管理服务器: npm run dev:admin examples/config.json
2. 打开浏览器访问: http://localhost:3001
3. 通过界面管理服务器配置

详细使用指南请参考 ADMIN_GUIDE.md

🏷️ 命名空间

代理支持命名空间以避免服务器间的冲突：

• 无命名空间: list_files, query_database
• 有命名空间: everything.list_files, sse.simple_tool

实际项目中的命名空间示例：

• everything.* - Everything Server 的工具 (11个)
• sse.* - SSE Server 的工具 (2个)
• stream.* - Streamable Server 的工具 (3个)

🧪 测试验证

使用 MCP Inspector 测试

# 测试代理服务器
npx @modelcontextprotocol/inspector node dist/index.js examples/config.json

Inspector 将显示：

• 16个工具: 来自3个不同服务器的聚合工具
• 10个资源: 文件系统资源访问
• 3个提示模板: 代码生成、文档编写等

验证成功标志

当所有组件正常运行时，你应该看到：

1. Proxy 日志显示:

   • "Starting MCP Server Proxy..."
   • "Connected to server: everything"
   • "Connected to server: stream"
   • "Aggregated capabilities: 16 tools, 10 resources, 3 prompts"

2. MCP Inspector 显示:

   • 16 个工具 (everything., sse., stream.*)
   • 10 个资源
   • 3 个提示模板

3. 管理界面显示:

   • 服务器状态为 "Connected"
   • 实时能力统计正确

API

The proxy implements the full MCP specification:

Lifecycle

• initialize - Initialize connection and negotiate capabilities
• initialized - Confirm initialization complete

Tools

• tools/list - List all available tools from all servers
• tools/call - Execute a tool (routed to appropriate server)

Resources

• resources/list - List all available resources from all servers
• resources/read - Read a resource (routed to appropriate server)

Prompts

• prompts/list - List all available prompts from all servers
• prompts/get - Get a prompt (routed to appropriate server)

Notifications

• notifications/tools/list_changed - Tools list changed
• notifications/resources/list_changed - Resources list changed
• notifications/prompts/list_changed - Prompts list changed

Development

项目结构

src/
├── proxy/           # 主代理服务器
├── managers/        # 组件管理器
│   ├── BackendManager.ts      # 后端服务器连接管理
│   ├── CapabilityAggregator.ts # 能力聚合
│   ├── RequestRouter.ts       # 请求路由
│   └── NotificationManager.ts # 通知处理
├── admin/           # Web管理界面
│   ├── server.ts              # 管理服务器
│   └── public/                # 前端资源
│       ├── index.html         # 管理界面
│       └── app.js             # 前端逻辑
├── types/           # TypeScript类型定义
├── utils/           # 工具函数
└── config/          # 配置管理

Building

npm run build

Linting

npm run lint

开发和测试

构建项目

npm run build

开发模式

# 启动开发模式（支持自动重启）
npm run dev examples/config.json

# 启动管理界面开发模式
npm run dev:admin examples/config.json

集成测试

1. 完整功能测试:

# 启动所有测试服务器
node examples/server-sse.js &
node examples/server-streamable-http.js &

# 启动代理服务器
LOG_LEVEL=DEBUG node dist/index.js examples/config.json

2. 使用 MCP Inspector 测试:

npx @modelcontextprotocol/inspector node dist/index.js examples/config.json

这将：

• 在本地端口启动 MCP Inspector
• 将代理服务器作为子进程启动
• 打开Web界面进行交互式测试
• 验证16个工具的聚合结果

Web界面功能：

• 查看聚合的工具、资源和提示模板
• 使用自定义参数测试工具执行
• 监控实时 JSON-RPC 通信
• 调试协议消息和错误
• 检查服务器能力和元数据

验证清单

• ✅ 代理服务器无错误启动
• ✅ 配置文件正确加载
• ✅ MCP Inspector 成功连接
• ✅ 协议握手完成 (initialize/initialized)
• ✅ 工具/资源/提示模板正确聚合 (16个工具)
• ✅ 命名空间前缀正常工作 (everything., sse., stream.*)
• ✅ 请求路由功能正常
• ✅ 错误处理健壮
• ✅ 通知正确转发
• ✅ 热重载功能正常
• ✅ Web管理界面可访问

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

🔧 故障排除

常见问题

1. 端口冲突

   # 查找占用端口的进程
   lsof -ti:3004 | xargs kill -9  # SSE Server
   lsof -ti:3005 | xargs kill -9  # Streamable Server
   lsof -ti:3001 | xargs kill -9  # Admin界面
   

2. 后端服务器启动失败

   • 检查配置文件中的命令和参数
   • 验证服务器可执行文件是否可用
   • 检查环境变量设置

3. 工具未显示

   • 验证服务器已连接（检查日志）
   • 检查命名空间配置
   • 确保服务器支持工具能力
   • 验证服务器的 enabled 状态

4. Cursor 连接问题

   • 检查 MCP 配置文件路径是否正确
   • 确保 Proxy 服务器正在运行
   • 查看 Cursor 的 MCP 日志 (Cmd+Shift+U → "MCP Logs")
   • 完全重启 Cursor

5. 权限错误

   • 检查文件系统权限
   • 验证环境变量设置正确

   chmod +x dist/index.js
   

调试模式

启用详细调试日志：

LOG_LEVEL=DEBUG node dist/index.js examples/config.json

这将显示详细信息：

• 服务器连接状态
• 能力加载过程
• 请求路由详情
• 通知处理过程
• 热重载操作