ShaoHua
105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# 研发工单 v1.3.0 - 01 HTTP 服务转换为 MCP 服务
|
||
|
||
---
|
||
|
||
## 一、目标与范围
|
||
|
||
### 1.1 目标
|
||
基于 C# 现有映射框架，将 Hua.Todo 的 HTTP API 转换为 MCP（Model Context Protocol）服务，提升服务调用效率与可扩展性。
|
||
|
||
### 1.2 范围
|
||
|
||
**包含**：
|
||
- 任务管理 API 的 MCP 映射
|
||
- 云同步 API 的 MCP 映射
|
||
- MCP 服务契约文档生成
|
||
- MCP 服务可用性验证
|
||
|
||
**不包含**：
|
||
- 新增业务功能开发
|
||
- 前端 UI 修改
|
||
|
||
---
|
||
|
||
## 二、前置条件
|
||
|
||
| 条件 | 说明 |
|
||
|---|---|
|
||
| Hua.Todo v1.2.0 | 已完成，提供基础 HTTP API |
|
||
| TRAE MCP SDK | 平台内置，已就绪 |
|
||
| 现有 API 文档 | 参考 [README.md](../../../README.md) |
|
||
|
||
---
|
||
|
||
## 三、需求规格
|
||
|
||
### 3.1 MCP 服务描述符生成
|
||
|
||
为以下 HTTP API 端点生成 MCP 工具描述符：
|
||
|
||
#### 任务管理 API
|
||
| HTTP 端点 | MCP 工具名 | 功能描述 |
|
||
|---|---|---|
|
||
| `GET /api/task` | `getTaskList` | 获取任务列表 |
|
||
| `GET /api/task/{id}` | `getTaskById` | 获取单个任务 |
|
||
| `POST /api/task` | `createTask` | 创建任务 |
|
||
| `PUT /api/task` | `updateTask` | 更新任务 |
|
||
| `PATCH /api/task/{id}/toggle` | `toggleTaskStatus` | 切换完成状态 |
|
||
| `DELETE /api/task/{id}` | `deleteTask` | 删除任务 |
|
||
| `GET /api/task/{parentTaskId}/subtasks` | `getSubtasks` | 获取子任务列表 |
|
||
|
||
#### 云同步 API（Host 模式）
|
||
| HTTP 端点 | MCP 工具名 | 功能描述 |
|
||
|---|---|---|
|
||
| `POST /auth/login` | `cloudLogin` | 用户登录 |
|
||
| `POST /auth/logout` | `cloudLogout` | 用户注销 |
|
||
| `GET /tasks/` | `getCloudTasks` | 获取云端任务 |
|
||
| `POST /sync/` | `syncTasks` | 推送/拉取合并同步 |
|
||
| `GET /security/policy` | `getSecurityPolicy` | 获取安全策略 |
|
||
|
||
### 3.2 契约文档生成
|
||
|
||
生成符合 MCP 规范的 JSON 契约文档，包含：
|
||
- 工具名称
|
||
- 参数定义（名称、类型、是否必填）
|
||
- 返回值定义
|
||
- 错误处理说明
|
||
|
||
### 3.3 服务注册与验证
|
||
|
||
- 按照平台标准流程注册 MCP 服务
|
||
- 验证所有工具的调用可用性
|
||
|
||
---
|
||
|
||
## 四、验收标准
|
||
|
||
| 验收项 | 验证方法 | 预期结果 |
|
||
|---|---|---|
|
||
| MCP 服务注册 | 检查服务列表 | 服务成功注册 |
|
||
| 工具描述符生成 | 查看 JSON 输出 | 所有工具描述符生成完整 |
|
||
| getTaskList | 调用工具 | 返回任务列表 |
|
||
| createTask | 调用工具 | 创建成功，返回任务 ID |
|
||
| updateTask | 调用工具 | 更新成功 |
|
||
| deleteTask | 调用工具 | 删除成功 |
|
||
| cloudLogin | 调用工具 | 登录成功，返回 Token |
|
||
| syncTasks | 调用工具 | 同步成功 |
|
||
|
||
---
|
||
|
||
## 五、Touch List
|
||
|
||
| 文件路径 | 修改类型 | 说明 |
|
||
|---|---|---|
|
||
| `src/Hua.Todo.Application/Mcp/` | 新增 | MCP 服务实现目录 |
|
||
| `src/Hua.Todo.Application/Mcp/McpServiceCollectionExtensions.cs` | 新增 | MCP 服务注册扩展 |
|
||
| `src/Hua.Todo.Application/Mcp/TaskMcpService.cs` | 新增 | 任务管理 MCP 服务 |
|
||
| `src/Hua.Todo.Application/Mcp/CloudSyncMcpService.cs` | 新增 | 云同步 MCP 服务 |
|
||
| `src/Hua.Todo.Application/Mcp/Models/` | 新增 | MCP DTO 模型 |
|
||
|
||
---
|
||
|
||
**工单编号**：01
|
||
**标题**：HTTP 服务转换为 MCP 服务
|
||
**版本**：v1.3.0
|