# 研发工单 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