Springboot MCP

Spring Boot 与 MCP 集成示例项目

这是一个演示如何在Spring Boot应用程序中集成MCP（Management Control Plane）的示例项目。

项目结构

src/
├── main/
│   ├── java/
│   │   └── com/example/demo/
│   │       ├── SpringbootMcpDemoApplication.java  # 应用主类
│   │       ├── config/
│   │       │   └── McpConfig.java                 # 原始MCP配置类
│   │       ├── controller/
│   │       │   └── McpDemoController.java         # 原始控制器类
│   │       ├── service/
│   │       │   └── McpService.java                # 原始MCP服务类
│   │       └── mcp/                               # 自定义MCP实现
│   │           ├── config/
│   │           │   └── McpConfig.java            # MCP配置类（包含自定义配置）
│   │           ├── protocol/
│   │           │   └── McpMessageProtocol.java    # MCP消息协议处理类
│   │           ├── client/
│   │           │   └── McpClientService.java      # MCP客户端服务
│   │           ├── exception/
│   │           │   ├── McpException.java          # MCP通用异常
│   │           │   ├── McpConnectionException.java # 连接异常
│   │           │   └── McpTimeoutException.java   # 超时异常
│   │           ├── server/
│   │           │   └── McpServerSimulator.java    # MCP服务器模拟器
│   │           └── McpController.java             # 自定义MCP控制器
│   └── resources/
│       ├── application.yml                        # 应用配置文件
└── pom.xml                                        # Maven配置文件

MCP 集成说明

什么是 MCP？

MCP（Management Control Plane）是一个管理和控制平面，通常用于协调AI系统和现有业务系统之间的交互。它可以：

• 管理提供的工具（如数据库查询、文件读取等）
• 协调AI和系统工具之间的通信
• 提供统一的接口来访问各种后端服务

集成要点

1. 依赖配置：在 pom.xml 中添加了必要的MCP客户端依赖
2. 配置管理：通过 application.yml 文件配置MCP服务器地址、超时时间等参数
3. 客户端初始化：在 McpConfig 类中初始化MCP客户端
4. 服务封装：在 McpService 中封装与MCP交互的业务逻辑
5. API暴露：通过 McpDemoController 提供RESTful API访问MCP功能

自定义MCP实现

本项目还提供了一套完整的自定义MCP实现，包括：

1. MCP消息协议 - 实现了完整的MCP消息格式，包括请求、响应、心跳和错误消息
2. MCP客户端服务 - 提供与MCP服务器通信的功能，包括重试机制
3. 异常处理 - 完善的异常处理机制，包括连接异常和超时异常
4. 配置管理 - 通过配置文件管理MCP相关参数
5. REST API接口 - 提供RESTful API来调用MCP功能

自定义MCP API接口

1. POST /api/custom-mcp/request - 发送MCP请求

- 参数: action (请求操作), data (请求数据)

1. POST /api/custom-mcp/request/async - 异步发送MCP请求

- 参数: action (请求操作), data (请求数据)

1. POST /api/custom-mcp/heartbeat - 发送心跳消息

1. GET /api/custom-mcp/status - 获取MCP服务器状态

1. POST /api/custom-mcp/message/create - 创建MCP消息示例

- 参数: messageType (消息类型), data (消息数据)

自定义MCP配置

在 application.yml 中配置自定义MCP相关参数：

# 自定义MCP配置
custom-mcp:
  server:
    url: http://localhost:9090
    timeout-ms: 5000
    connect-timeout-ms: 10000
  client:
    enabled: true
    max-retries: 3
    retry-delay-ms: 1000

如何运行项目

1. 确保已安装 JDK 17+ 和 Maven
2. 克隆或下载此项目
3. 在项目根目录执行以下命令：

方法1：使用自动化脚本（推荐）

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File "start-app-simple.ps1"

# Linux Shell (基础版)
# 首先为脚本添加可执行权限
chmod +x start-app.sh
chmod +x stop-port.sh

# 然后运行脚本
./start-app.sh

# Linux Shell (增强版)
# 为增强版脚本添加可执行权限
chmod +x start-app-enhanced.sh

# 运行增强版脚本
./start-app-enhanced.sh

方法2：手动执行Maven命令

mvn clean install
mvn spring-boot:run

或者直接运行主类 SpringbootMcpDemoApplication.java

自动端口管理功能

为了解决每次启动应用时端口被占用的问题，我们创建了一个自动化脚本来处理端口占用问题。

功能说明

自动化脚本会：

1. 自动检测并停止占用8082端口的进程
2. 启动Spring Boot应用

脚本文件

• start-app-simple.ps1: PowerShell脚本，自动停止占用端口的进程并启动应用（Windows）
• start-app.sh: Shell脚本，自动停止占用端口的进程并启动应用（Linux）
• start-app-enhanced.sh: 增强版Shell脚本，包含日志记录和错误处理功能（Linux）
• stop-port.bat: 批处理脚本，仅停止占用端口的进程（Windows）
• stop-port.sh: Shell脚本，仅停止占用端口的进程（Linux）

使用前准备

在Linux环境下使用脚本前，需要为脚本添加执行权限：

chmod +x start-app.sh
chmod +x stop-port.sh

使用场景

当遇到以下错误时，使用自动化脚本可以解决问题：

Web server failed to start. Port 8082 was already in use.

API 接口说明

项目启动后，可以通过以下端点访问MCP集成功能：

原始MCP接口

• GET /api/mcp/hello - 基本问候接口
• GET /api/mcp/status - 获取MCP服务器状态
• GET /api/mcp/config - 获取MCP配置信息
• GET /api/mcp/interact?request={message} - 与MCP服务器交互

自定义MCP接口

• POST /api/custom-mcp/request - 发送MCP请求
• POST /api/custom-mcp/request/async - 异步发送MCP请求
• POST /api/custom-mcp/heartbeat - 发送心跳消息
• GET /api/custom-mcp/status - 获取MCP服务器状态
• POST /api/custom-mcp/message/create - 创建MCP消息示例

示例：

# 原始接口
curl http://localhost:8080/api/mcp/status
curl http://localhost:8080/api/mcp/interact?request=hello

# 自定义接口
curl -X POST "http://localhost:8080/api/custom-mcp/request?action=getStatus"
curl -X POST "http://localhost:8080/api/custom-mcp/heartbeat"
curl -X GET "http://localhost:8080/api/custom-mcp/status"

配置说明

在 application.yml 文件中可以配置以下MCP相关参数：

# 原始MCP配置
mcp:
  server:
    url: http://localhost:9090    # MCP服务器地址
    timeout: 5000                 # 超时时间(ms)
  client:
    enabled: true                 # 是否启用MCP客户端
    connection-pool-size: 10      # 连接池大小

# 自定义MCP配置
custom-mcp:
  server:
    url: http://localhost:9090
    timeout-ms: 5000
    connect-timeout-ms: 10000
  client:
    enabled: true
    max-retries: 3
    retry-delay-ms: 1000

扩展建议

要在实际项目中使用此集成，您需要：

1. 替换 McpConfig 中的模拟客户端实现为真实的MCP客户端库
2. 根据实际需求修改 McpService 中的交互逻辑
3. 添加错误处理和日志记录机制
4. 根据安全要求添加认证和授权机制
5. 对于自定义MCP实现，可以进一步扩展协议功能和客户端能力