# springboot-mcp-server

**Repository Path**: luckyworkspace/springboot-mcp-server

## Basic Information

- **Project Name**: springboot-mcp-server
- **Description**: mcp测试用例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Server开发方案

## 一、技术栈选择

- **框架**: Spring Boot 2.7+ (响应式)
- **Web框架**: Spring WebFlux
- **JSON处理**: Jackson
- **构建工具**: Maven
- **测试工具**: MCP Inspector

## 二、项目结构设计

```
springboot-mcp-server/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           ├── HelloWorldApplication.java       # 应用入口
│   │   │           ├── config/                           # HTTP配置
│   │   │           │   └── McpConfig.java
│   │   │           └── mcp/
│   │   │               ├── protocol/                     # JSON-RPC 2.0格式定义
│   │   │               │   ├── McpRequest.java
│   │   │               │   └── McpResponse.java
│   │   │               ├── transport/                    # 传输层实现
│   │   │               │   └── SseTransport.java         # SSE和HTTP POST端点
│   │   │               ├── server/                       # MCP协议处理
│   │   │               │   └── McpServerHandler.java     # 请求处理逻辑
│   │   │               └── tools/                        # 工具管理
│   │   │                   └── McpToolRegistry.java      # 工具注册与调用
│   │   └── resources/
│   │       ├── application.properties                   # 应用配置
│   │       └── static/
│   │           └── mcp-test.html                        # 内置测试客户端
│   └── test/
│       └── java/
│           └── com/
│               └── example/
│                   └── HelloWorldApplicationTests.java
└── README.md
```

## 三、核心组件实现

### 1. 协议定义层 (protocol)

#### McpRequest.java
- 定义JSON-RPC 2.0请求格式
- 包含jsonrpc版本、method方法名、params参数和id请求ID

#### McpResponse.java
- 定义JSON-RPC 2.0响应格式
- 包含jsonrpc版本、id请求ID、result成功结果或error错误信息
- 内部类McpError定义错误格式

### 2. 传输层 (transport)

#### SseTransport.java
- 实现**GET /sse**端点，建立SSE长连接
  - 处理客户端连接，生成会话ID
  - 发送endpoint事件，提供POST通信端点
  - 维护客户端连接映射
  - 实现心跳机制
  - 处理连接关闭和错误

- 实现**POST /message/{sessionId}**端点，处理客户端请求
  - 解析JSON-RPC请求
  - 调用McpServerHandler处理请求
  - 通过SSE返回响应

### 3. 服务层 (server)

#### McpServerHandler.java
- 实现MCP协议的请求处理逻辑
  - `initialize`：处理初始化请求，返回服务器能力
  - `tools/list`：返回可用工具列表
  - `tools/call`：处理工具调用请求
  - `notifications/initialized`：处理客户端初始化完成通知
  - 错误处理：返回适当的错误响应

### 4. 工具层 (tools)

#### McpToolRegistry.java
- 管理可用工具列表
- 提供工具注册机制
- 实现工具调用逻辑
- 内置示例工具：
  - `hello_world`：返回Hello World消息
  - `get_time`：返回当前服务器时间
  - `echo`：回显客户端消息

## 四、开发步骤

1. **项目初始化**
   - 使用Spring Initializr创建Spring Boot项目
   - 添加WebFlux和Jackson依赖
   - 配置pom.xml

2. **创建核心类**
   - 实现McpRequest和McpResponse
   - 实现McpServerHandler
   - 实现McpToolRegistry
   - 实现SseTransport

3. **配置HTTP端点**
   - 配置SSE端点和POST端点
   - 配置CORS和安全设置

4. **实现工具逻辑**
   - 实现示例工具
   - 配置工具注册

5. **添加测试客户端**
   - 创建mcp-test.html内置测试页面
   - 实现基本的MCP客户端功能

6. **测试验证**
   - 启动服务器
   - 使用MCP Inspector测试
   - 使用内置测试客户端测试

## 五、测试计划

### 使用MCP Inspector测试
1. 启动服务器：`mvn spring-boot:run`
2. 运行MCP Inspector：`npx "@modelcontextprotocol/inspector@0.9"`
3. 选择"SSE Transport"
4. 输入URL：`http://localhost:8080/sse`
5. 点击"Connect"
6. 执行标准MCP流程：
   - Initialize
   - List Tools
   - Call Tools

### 使用内置测试客户端
1. 访问：`http://localhost:8080/mcp-test.html`
2. 点击"Connect to MCP Server"
3. 按顺序执行：
   - Initialize
   - List Tools
   - Call Hello World
   - Get Time
   - Echo Message

## 六、预期功能

1. 成功建立SSE长连接
2. 正确返回endpoint事件
3. 支持initialize初始化流程
4. 支持tools/list获取工具列表
5. 支持tools/call调用具体工具
6. 支持错误处理
7. 支持连接关闭和资源清理

## 七、扩展建议

1. 添加更多示例工具
2. 实现更完善的安全机制
3. 添加日志记录
4. 实现监控指标
5. 支持集群部署

## 八、技术要点

1. **SSE实现**：使用Spring WebFlux的`Flux<ServerSentEvent>`和`Sinks.Many`
2. **JSON-RPC 2.0**：严格按照规范实现请求和响应格式
3. **并发处理**：使用线程安全的数据结构管理客户端连接
4. **错误处理**：统一的错误响应格式
5. **心跳机制**：定期发送ping事件保持连接

通过以上方案，我将按照文章中的指导实现一个完整的MCP Server，支持MCP协议的所有核心功能。