ShaoHua
9223ceca50
- 规则重组：全局/ 下 8 个规则合并为 6 个（01+02→01，05+06→04），序号顺延 - 新增项目规则 05-多入口功能同步规范（UI/语音入口覆盖检查） - 新增 MCP 服务基础设施：Mcp/ 目录（DI 注册、端点扩展、动态工具描述符）、单元测试 - v1.3.0 工单文档：03 系列（会议任务拆分）、04（富文本描述与附件管理） - MCP 接口与前端集成指南：docs/manual/08、09
390 lines
8.8 KiB
Markdown
390 lines
8.8 KiB
Markdown
# MCP 服务接口文档
|
||
|
||
> Hua.Todo MCP Server 接口规范，供外部系统（AI 客户端、第三方集成）通过 MCP 协议接入 Hua.Todo 待办项管理能力。
|
||
|
||
## 1. 概述
|
||
|
||
Hua.Todo 提供了基于 **Model Context Protocol (MCP)** 的服务端，允许外部 MCP 客户端通过 Streamable HTTP 传输协议发现并调用待办项管理工具。
|
||
|
||
### 1.1 协议与传输
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| 协议版本 | MCP 2025-03-26（Streamable HTTP） |
|
||
| 传输方式 | Streamable HTTP（无状态模式） |
|
||
| 内容格式 | JSON-RPC 2.0 |
|
||
| 端点路径 | `/mcp` |
|
||
| 认证 | 暂无（本地模式）；生产环境建议通过反向代理添加认证 |
|
||
|
||
### 1.2 服务端信息
|
||
|
||
```json
|
||
{
|
||
"name": "Hua.Todo MCP Server",
|
||
"version": "1.0.0"
|
||
}
|
||
```
|
||
|
||
### 1.3 连接地址
|
||
|
||
| 运行模式 | 默认地址 |
|
||
|---|---|
|
||
| Hua.Todo.Host（独立服务端） | `http://localhost:5173/mcp` |
|
||
| MAUI / Avalonia（嵌入式） | `http://localhost:5057/mcp` |
|
||
|
||
> 实际端口以部署配置为准。
|
||
|
||
---
|
||
|
||
## 2. 接入方式
|
||
|
||
### 2.1 MCP 客户端配置示例
|
||
|
||
**Claude Desktop / Cursor / 其他 MCP 客户端** 配置文件（`mcp_servers.json` 或等效）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"hua-todo": {
|
||
"url": "http://localhost:5173/mcp",
|
||
"transport": "streamable-http"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 手动调用示例（curl）
|
||
|
||
MCP 协议基于 JSON-RPC 2.0，可通过 HTTP POST 手动调用：
|
||
|
||
#### 初始化连接
|
||
|
||
```bash
|
||
curl -X POST http://localhost:5173/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-H "MCP-Protocol-Version: 2025-03-26" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "initialize",
|
||
"params": {
|
||
"protocolVersion": "2025-03-26",
|
||
"capabilities": {},
|
||
"clientInfo": { "name": "my-client", "version": "1.0.0" }
|
||
}
|
||
}'
|
||
```
|
||
|
||
#### 列出可用工具
|
||
|
||
```bash
|
||
curl -X POST http://localhost:5173/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-H "MCP-Protocol-Version: 2025-03-26" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"method": "tools/list",
|
||
"params": {}
|
||
}'
|
||
```
|
||
|
||
#### 调用工具
|
||
|
||
```bash
|
||
curl -X POST http://localhost:5173/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-H "MCP-Protocol-Version: 2025-03-26" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 3,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "CreateTodo",
|
||
"arguments": {
|
||
"title": "完成项目报告",
|
||
"priority": "High"
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 工具清单
|
||
|
||
### 3.1 查询类工具
|
||
|
||
#### ListAllTodos
|
||
|
||
获取所有待办项列表（含已完成和未完成）。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| 无 | - | - | - |
|
||
|
||
**返回示例**：
|
||
|
||
```
|
||
所有待办项（共 3 项）：
|
||
[1] 完成项目报告 | 优先级:High | 进行中
|
||
[2] 购买办公用品 | 优先级:Medium | 已完成
|
||
[3] 整理会议纪要 | 优先级:Low | 进行中
|
||
```
|
||
|
||
---
|
||
|
||
#### ListActiveTodos
|
||
|
||
获取未完成的待办项列表。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| 无 | - | - | - |
|
||
|
||
**返回示例**：
|
||
|
||
```
|
||
未完成待办项（共 2 项）：
|
||
[1] 完成项目报告 | 优先级:High | 进行中
|
||
[3] 整理会议纪要 | 优先级:Low | 进行中
|
||
```
|
||
|
||
---
|
||
|
||
#### ListCompletedTodos
|
||
|
||
获取已完成的待办项列表。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| 无 | - | - | - |
|
||
|
||
---
|
||
|
||
#### GetTodoById
|
||
|
||
根据 ID 获取单个待办项详情（含子任务）。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `int` | 是 | 待办项 ID |
|
||
|
||
**返回示例**：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"title": "完成项目报告",
|
||
"priority": "High",
|
||
"isCompleted": false,
|
||
"createdAt": "2026-06-16T08:30:00Z",
|
||
"updatedAt": "2026-06-16T08:30:00Z",
|
||
"parentTaskId": null,
|
||
"subTasks": [
|
||
{
|
||
"id": 4,
|
||
"title": "收集数据",
|
||
"priority": "Medium",
|
||
"isCompleted": true,
|
||
"createdAt": "2026-06-16T08:35:00Z",
|
||
"updatedAt": "2026-06-16T10:00:00Z",
|
||
"parentTaskId": 1,
|
||
"subTasks": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**未找到时**：返回文本 `"未找到 ID 为 {id} 的待办项"`
|
||
|
||
---
|
||
|
||
#### ListSubTodos
|
||
|
||
获取指定父待办项下的所有子待办项。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `parentTaskId` | `int` | 是 | 父待办项 ID |
|
||
|
||
---
|
||
|
||
### 3.2 写入类工具
|
||
|
||
#### CreateTodo
|
||
|
||
创建新的待办项。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `title` | `string` | 是 | - | 待办项标题 |
|
||
| `priority` | `string` | 否 | `"Medium"` | 优先级：`Low` / `Medium` / `High` |
|
||
| `parentTaskId` | `int` | 否 | `null` | 父待办项 ID（创建子任务时传入） |
|
||
|
||
**返回示例**：
|
||
|
||
```
|
||
已创建待办项：
|
||
{
|
||
"id": 5,
|
||
"title": "完成项目报告",
|
||
"priority": "High",
|
||
"isCompleted": false,
|
||
"createdAt": "2026-06-16T10:00:00Z",
|
||
"updatedAt": "2026-06-16T10:00:00Z",
|
||
"parentTaskId": null,
|
||
"subTasks": []
|
||
}
|
||
```
|
||
|
||
**优先级无效时**：返回文本 `"无效的优先级 'xxx'，有效值为：Low、Medium、High"`
|
||
|
||
---
|
||
|
||
#### UpdateTodo
|
||
|
||
更新已有待办项的标题或优先级。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `id` | `int` | 是 | - | 待办项 ID |
|
||
| `title` | `string` | 否 | `null` | 新标题 |
|
||
| `priority` | `string` | 否 | `null` | 新优先级：`Low` / `Medium` / `High` |
|
||
|
||
**未找到时**：返回文本 `"未找到 ID 为 {id} 的待办项"`
|
||
|
||
---
|
||
|
||
#### ToggleTodoComplete
|
||
|
||
切换待办项的完成状态（已完成 ↔ 未完成）。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `int` | 是 | 待办项 ID |
|
||
|
||
**返回示例**：
|
||
|
||
```
|
||
已切换完成状态：
|
||
{
|
||
"id": 1,
|
||
"title": "完成项目报告",
|
||
"priority": "High",
|
||
"isCompleted": true,
|
||
...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### DeleteTodo
|
||
|
||
删除指定待办项。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `int` | 是 | 待办项 ID |
|
||
|
||
**成功时**：返回文本 `"已删除待办项 {id}"`
|
||
|
||
**未找到时**：返回文本 `"未找到 ID 为 {id} 的待办项"`
|
||
|
||
---
|
||
|
||
## 4. 数据类型定义
|
||
|
||
### 4.1 TaskDto（待办项）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | `int` | 唯一标识符 |
|
||
| `title` | `string` | 标题 |
|
||
| `priority` | `string` | 优先级枚举值：`"Low"` / `"Medium"` / `"High"` |
|
||
| `isCompleted` | `bool` | 是否已完成 |
|
||
| `createdAt` | `string` | 创建时间（ISO 8601 UTC） |
|
||
| `updatedAt` | `string` | 更新时间（ISO 8601 UTC） |
|
||
| `parentTaskId` | `int?` | 父待办项 ID（顶层任务为 null） |
|
||
| `subTasks` | `TaskDto[]` | 子任务列表（递归结构） |
|
||
|
||
### 4.2 优先级枚举
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `"Low"` | 低优先级 |
|
||
| `"Medium"` | 中优先级（默认） |
|
||
| `"High"` | 高优先级 |
|
||
|
||
---
|
||
|
||
## 5. 错误处理
|
||
|
||
MCP 工具调用中的错误通过返回文本内容表达（而非 MCP 协议级错误），常见情况：
|
||
|
||
| 场景 | 返回内容 |
|
||
|---|---|
|
||
| 待办项不存在 | `"未找到 ID 为 {id} 的待办项"` |
|
||
| 优先级值无效 | `"无效的优先级 'xxx'，有效值为：Low、Medium、High"` |
|
||
| 列表为空 | `"没有{label}"` |
|
||
|
||
MCP 协议级错误（如方法不存在、参数格式错误）遵循 JSON-RPC 2.0 标准：
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"error": {
|
||
"code": -32600,
|
||
"message": "Invalid Request"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 与 HTTP API 的对照
|
||
|
||
MCP 工具与原有 HTTP Dynamic API 的对应关系：
|
||
|
||
| MCP 工具 | HTTP API | 说明 |
|
||
|---|---|---|
|
||
| `ListAllTodos` | `GET /api/task` | 获取全部 |
|
||
| `ListActiveTodos` | `GET /api/task/active` | 获取未完成 |
|
||
| `ListCompletedTodos` | `GET /api/task/completed` | 获取已完成 |
|
||
| `GetTodoById` | `GET /api/task/{id}` | 按 ID 查询 |
|
||
| `CreateTodo` | `POST /api/task` | 创建 |
|
||
| `UpdateTodo` | `PUT /api/task` | 更新 |
|
||
| `ToggleTodoComplete` | `PATCH /api/task/{id}/toggle` | 切换完成 |
|
||
| `DeleteTodo` | `DELETE /api/task/{id}` | 删除 |
|
||
| `ListSubTodos` | `GET /api/task/{parentTaskId}/subtasks` | 子任务 |
|
||
|
||
> 两套 API 共享同一 `ITaskService` 实现，数据完全一致，可根据场景选择使用。
|
||
|
||
---
|
||
|
||
## 7. 安全建议（生产部署）
|
||
|
||
1. **网络隔离**：MCP 端点默认无认证，建议仅在可信网络内暴露，或通过反向代理添加 API Key / Bearer Token 认证
|
||
2. **CORS 限制**：生产环境应将 CORS 策略从 `AllowAll` 改为指定来源
|
||
3. **HTTPS**：生产环境必须启用 HTTPS
|
||
4. **速率限制**：建议对 MCP 端点添加请求速率限制
|
||
|
||
---
|
||
|
||
## 8. 常见问题
|
||
|
||
### Q: MCP 端点和 HTTP API 可以同时使用吗？
|
||
可以。两者共享相同的数据源和服务层，不存在冲突。
|
||
|
||
### Q: Streamable HTTP 无状态模式下支持服务端通知吗？
|
||
不支持。无状态模式下服务端无法向客户端主动推送通知。如需通知能力，需改为有状态模式（`Stateless = false`），但需要会话亲和。
|
||
|
||
### Q: 如何验证 MCP 服务是否正常运行？
|
||
发送 `initialize` 请求（见 2.2 节），若返回服务端信息则表示正常。
|
||
|
||
---
|
||
|
||
**文档版本**：1.0.0
|
||
**最后更新**：2026-06-16
|