内容
# SpringMCP — 待办事项管理 MCP 服务器
一个 Spring Boot 应用程序，作为 **MCP（模型上下文协议）服务器**，暴露待办事项管理系统。像 Claude 这样的 AI 助手可以通过结构化的工具调用连接到此服务器并管理待办事项。
---
## 什么是 MCP？
[模型上下文协议](https://modelcontextprotocol.io) 是一个开放标准，允许 AI 模型以结构化、安全的方式与外部工具和数据源交互。该项目使用 [Spring AI](https://docs.spring.io/spring-ai/reference/) 实现了一个 MCP 服务器，使待办事项操作可作为可调用工具供任何 MCP 兼容客户端使用。
---
## 功能
- 创建带有标题、描述和优先级（低 / 中 / 高）的待办事项
- 列出所有待办事项
- 按 ID 检索特定待办事项
- 按状态（待处理 / 进行中 / 已完成）或优先级筛选待办事项
- 通过服务器发送事件（SSE）实现完全同步的 MCP 服务器
- 零配置内存存储 — 无需数据库
---
## 技术栈
| 层 | 技术 |
|-------|-----------|
| 语言 | Java 24 |
| 框架 | Spring Boot 4.1.0 |
| MCP 集成 | Spring AI MCP Server（WebMVC）2.0.0 |
| 构建工具 | Gradle 9.5+ |
| 样板减少 | Lombok |
---
## 项目结构
```
SpringMCP/
├── src/main/java/com/example/SpringMCP/
│ ├── SpringMcpApplication.java # 应用程序入口点
│ ├── config/
│ │ └── MCPServerConfig.java # 在 MCP 服务器上注册工具
│ ├── models/
│ │ └── Todo.java # 带有状态和优先级枚举的待办事项实体
│ ├── services/
│ │ └── TodoServices.java # 业务逻辑和内存存储
│ └── tools/
│ └── TodoManagementTool.java # 通过 MCP 暴露的 @Tool 方法
└── src/main/resources/
└── application.properties # 服务器名称、端口、SSE 端点配置
```
---
## MCP 工具
这些是向 MCP 客户端暴露的工具：
### `createTodo`
创建新的待办事项。
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `title` | 字符串 | 待办事项的短标题 |
| `description` | 字符串 | 详细描述 |
| `priority` | 字符串 | `高`、`中` 或 `低` |
成功时返回创建的待办事项的 UUID。
---
### `listAllTodos`
返回当前存储的所有待办事项。不需要参数。
---
### `getTodoById`
通过 UUID 获取单个待办事项。
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `id` | 字符串 | 要检索的待办事项的 UUID |
---
## 待办事项模型
```java
Todo {
id 字符串 // 自动生成的 UUID
title 字符串
description 字符串
priority 优先级 // 低 | 中 | 高 （默认：中）
status 状态 // 待处理 | 进行中 | 已完成 （默认：待处理）
createdAt 本地日期时间
updatedAt 本地日期时间
}
```
---
## 入门指南
### 先决条件
- Java 24+
- Gradle 9.5+ （或使用包含的 `./gradlew` 包装器）
### 运行服务器
```bash
./gradlew bootRun
```
MCP 服务器在 **端口 8080** 上启动，并在以下地址监听 SSE 连接：
```
http://localhost:8080/mcp/sse/messages
```
### 构建 JAR
```bash
./gradlew build
java -jar build/libs/SpringMCP-*.jar
```
---
## 配置
所有设置都位于 `src/main/resources/application.properties` 中：
```properties
spring.application.name=SpringMCP
spring.ai.mcp.server.name=todo-management-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.sse-message-endpoint=/mcp/sse/messages
server.port=8080
```
---
## 将 Claude 连接到此服务器
在您的 Claude Desktop `claude_desktop_config.json` 中添加以下内容：
```json
{
"mcpServers": {
"todo-management": {
"url": "http://localhost:8080/mcp/sse/messages",
"transport": "sse"
}
}
}
```
连接后，Claude 可以直接在对话中调用 `createTodo`、`listAllTodos` 和 `getTodoById`。
---
## 架构
```
MCP 客户端（Claude）
│
│ SSE / MCP 协议
▼
TodoManagementTool ← 通过 MCPServerConfig 注册的 @Tool 方法
│
▼
TodoServices ← 业务逻辑
│
▼
HashMap<字符串, 待办事项> ← 内存存储（重启时重置）
```
---
## 限制
- **仅内存存储** — 所有待办事项在应用程序重启时都会丢失。
- 暂时没有更新或删除工具（仅创建、列表、获取）。
- MCP 端点上没有身份验证。
- 测试覆盖率最小（仅上下文加载测试）。
---
## 路线图
- [ ] 使用 JPA + H2/PostgreSQL 持久化待办事项
- [ ] 添加 `updateTodoStatus` 和 `deleteTodo` MCP 工具
- [ ] 添加单元测试和集成测试
- [ ] 保护 SSE 端点
- [ ] Docker 支持
