MCP Router - Java版本

这是一个基于Spring Boot的Model Context Protocol (MCP) 路由器实现，用Java重写了原始的Go版本。该项目负责代理和路由MCP服务器的请求，提供统一的访问接口。

功能特性

• MCP代理服务器，支持SSE和HTTP请求
• MCP API服务器，提供工具列表和调用功能
• 支持本地进程和远程HTTP服务器
• 支持服务器配置缓存
• 支持请求和响应日志记录
• 新增：完整的命令行接口
• 新增：调试测试工具

技术栈

• Java 8 (JDK 1.8)
• Spring Boot 2.7.x
• Spring Data JPA
• Spring Data Redis
• Spring WebSocket
• MySQL/H2数据库

系统要求

• JDK 1.8+
• Maven 3.6+
• MySQL 5.7+ (可选，也可使用H2内存数据库)
• Redis 5+ (可选，用于缓存)

构建项目

cd java
mvn clean package

配置

配置文件位于 src/main/resources/application.properties，你也可以通过创建自定义的 .env.properties 文件来覆盖默认配置。

配置文件示例可参考 src/main/resources/.env.example.properties。

你可以通过环境变量覆盖配置：

• 数据库配置：MYSQL_URL, MYSQL_USER, MYSQL_PASSWORD
• Redis配置：REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
• 服务器端口：PROXY_SERVER_PORT, API_SERVER_PORT

运行

使用命令行接口

MCP Router现在支持完整的命令行接口：

java -jar mcprouter.jar [命令] [选项]

可用命令:

• proxy - 启动MCP代理服务器
• api - 启动MCP API服务器
• help - 显示帮助信息
• version - 显示版本信息

通用选项:

• -c, --config <文件> - 指定配置文件路径 (默认: .env.properties)

示例:

# 启动代理服务器
java -jar mcprouter.jar proxy

# 启动API服务器并指定配置文件
java -jar mcprouter.jar api -c custom-config.properties

# 显示帮助信息
java -jar mcprouter.jar help

使用启动脚本

也可以使用提供的启动脚本：

# Linux/macOS
./start-proxy.sh [配置文件路径]
./start-api.sh [配置文件路径]

# Windows
start-proxy.bat [配置文件路径]
start-api.bat [配置文件路径]

如果不指定配置文件路径，将默认使用 .env.properties。

调试工具

MCP Router提供了调试HTTP请求工具，位于 src/main/resources/debug 目录：

• proxytest.http - 代理服务器测试请求
• apitest.http - API服务器测试请求

这些文件可以使用VS Code的REST Client扩展或IntelliJ IDEA的HTTP Client功能来执行。

接口文档

代理服务器接口

• GET /sse/{key} - 创建SSE连接
• POST /messages - 发送SSE消息
• POST /mcp/{key} - 转发MCP请求

API服务器接口

• POST /v1/list-servers - 列出可用的MCP服务器
• POST /v1/list-tools - 列出指定服务器的工具
• POST /v1/call-tool - 调用指定服务器的工具

架构设计

项目遵循标准的Spring Boot架构：

• 控制器(Controller)层：处理HTTP请求和响应
• 服务(Service)层：实现业务逻辑
• 数据访问(Repository)层：处理数据库操作
• 模型(Model)层：定义数据结构
• 命令行(CLI)层：处理命令行交互

许可证

与原始项目保持一致

MCP Router Java 实现改进

本项目针对MCP Router的Java实现中存在的进程管理问题进行了改进。

主要改进

1. 完善的本地进程管理

原有的Java实现在进程管理方面存在以下问题：

• 缺少完整的进程启动、监控和关闭逻辑
• 缺少与Go版本同等的进程控制能力，无法保证MCP服务器进程的可靠性

我们的改进包括：

1. 增强的进程生命周期管理

   • 增加进程启动时的错误处理和日志记录
   • 实现安全的进程关闭机制，支持优雅关闭和强制终止
   • 添加进程退出码监控，以便于问题排查

2. 进程监控机制

   • 实现定期健康检查，确保进程持续运行
   • 在进程异常终止时自动清理资源和更新客户端状态
   • 支持进程异常情况的日志记录和可选的自动重启

3. 错误处理和资源释放

   • 改进标准输入/输出流的管理，防止资源泄露
   • 增强异常处理，确保即使在错误情况下也能正确关闭资源
   • 实现超时控制，防止进程操作无限阻塞

2. 完善的进程共享机制

原有实现中虽然在配置中支持进程共享设置，但实际实现中缺少进程复用的完整逻辑，无法有效处理多客户端共享同一进程的场景。

我们的改进包括：

1. 增强的进程共享逻辑

   • 使用命令哈希作为进程标识，确保相同命令的进程能够被正确共享
   • 实现进程引用计数机制，确保只有在所有客户端都断开连接后才关闭共享进程
   • 支持在使用共享进程时重用现有的输入/输出流，避免资源浪费

2. 健康检查和回调机制

   • 实现定期健康检查，确保共享进程持续正常运行
   • 在进程终止时正确通知所有使用该进程的客户端
   • 支持进程退出时的清理和资源释放

3. 配置和监控支持

   • 完善配置支持，确保进程共享设置能够正确生效
   • 增加进程启动时间和使用情况的记录，便于监控和调试
   • 支持进程日志记录，帮助排查共享进程问题

实现类说明

• McpClientServiceImpl: 实现了进程管理和共享的核心逻辑，包括进程启动、监控和关闭
• ProcessManagementServiceImpl: 提供独立的进程管理服务，专注于进程健康检查和生命周期管理
• ProxyInfoServiceImpl: 提供会话信息存储和检索服务，支持跨会话的进程共享

配置示例

mcp-servers:
  servers:
    claude:
      command: "python -m mcp.server.claude"
      shareProcess: true
      serverType: "local"
    gemini:
      command: "python -m mcp.server.gemini"
      shareProcess: true
      serverType: "local"
    openai:
      serverUrl: "http://localhost:8080"
      serverType: "remote_rest"

使用方法

1. 在Spring应用中注入ProcessManagementServiceImpl服务
2. 使用getOrCreateClient方法获取或创建MCP客户端
3. 客户端将根据配置自动管理和共享进程
4. 应用关闭时调用shutdown方法以释放所有资源