ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
312 lines
9.4 KiB
Markdown
312 lines
9.4 KiB
Markdown
# MCP 服务集成
|
||
|
||
> 本文档涵盖 Hua.Todo MCP 服务的两部分内容：面向外部系统的接口规范（Part A）与面向内部前端的集成指南（Part B）。
|
||
|
||
---
|
||
|
||
## Part A：MCP 服务接口规范（外部系统接入）
|
||
|
||
### A.1 概述
|
||
|
||
Hua.Todo 提供了基于 **Model Context Protocol (MCP)** 的服务端，允许外部 MCP 客户端通过 Streamable HTTP 传输协议发现并调用待办项管理工具。
|
||
|
||
#### A.1.1 协议与传输
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| 协议版本 | MCP 2025-03-26（Streamable HTTP） |
|
||
| 传输方式 | Streamable HTTP（无状态模式） |
|
||
| 内容格式 | JSON-RPC 2.0 |
|
||
| 端点路径 | `/mcp` |
|
||
| 认证 | 暂无（本地模式）；生产环境建议通过反向代理添加认证 |
|
||
|
||
#### A.1.2 服务端信息
|
||
|
||
```json
|
||
{
|
||
"name": "Hua.Todo MCP Server",
|
||
"version": "1.0.0"
|
||
}
|
||
```
|
||
|
||
#### A.1.3 连接地址
|
||
|
||
| 运行模式 | 默认地址 |
|
||
|---|---|
|
||
| Hua.Todo.Host（独立服务端） | `http://localhost:5173/mcp` |
|
||
| MAUI / Avalonia（嵌入式） | `http://localhost:5057/mcp` |
|
||
|
||
### A.2 接入方式
|
||
|
||
#### A.2.1 MCP 客户端配置示例
|
||
|
||
**Claude Desktop / Cursor / 其他 MCP 客户端** 配置文件：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"hua-todo": {
|
||
"url": "http://localhost:5173/mcp",
|
||
"transport": "streamable-http"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### A.2.2 手动调用示例（curl）
|
||
|
||
**初始化连接**：
|
||
|
||
```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" } }
|
||
}'
|
||
```
|
||
|
||
### A.3 工具清单
|
||
|
||
#### A.3.1 查询类工具
|
||
|
||
**ListAllTodos** — 获取所有待办项列表（含已完成和未完成），无参数。
|
||
|
||
**ListActiveTodos** — 获取未完成的待办项列表，无参数。
|
||
|
||
**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, "parentTaskId": 1, "subTasks": [] }]
|
||
}
|
||
```
|
||
|
||
**ListSubTodos** — 获取指定父待办项下的所有子待办项。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `parentTaskId` | `int` | 是 | 父待办项 ID |
|
||
|
||
#### A.3.2 写入类工具
|
||
|
||
**CreateTodo** — 创建新的待办项。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `title` | `string` | 是 | - | 待办项标题 |
|
||
| `priority` | `string` | 否 | `"Medium"` | 优先级：`Low` / `Medium` / `High` |
|
||
| `parentTaskId` | `int` | 否 | `null` | 父待办项 ID |
|
||
|
||
**UpdateTodo** — 更新已有待办项的标题或优先级。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `id` | `int` | 是 | - | 待办项 ID |
|
||
| `title` | `string` | 否 | `null` | 新标题 |
|
||
| `priority` | `string` | 否 | `null` | 新优先级 |
|
||
|
||
**ToggleTodoComplete** — 切换待办项的完成状态。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `int` | 是 | 待办项 ID |
|
||
|
||
**DeleteTodo** — 删除指定待办项。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `int` | 是 | 待办项 ID |
|
||
|
||
### A.4 数据类型定义
|
||
|
||
#### 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 |
|
||
| `subTasks` | `TaskDto[]` | 子任务列表 |
|
||
|
||
### A.5 与 HTTP 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` 实现，数据完全一致。
|
||
|
||
### A.6 安全建议（生产部署）
|
||
|
||
1. **网络隔离**：MCP 端点默认无认证，建议仅在可信网络内暴露，或通过反向代理添加认证
|
||
2. **CORS 限制**：生产环境应将 CORS 策略从 `AllowAll` 改为指定来源
|
||
3. **HTTPS**：生产环境必须启用 HTTPS
|
||
4. **速率限制**：建议对 MCP 端点添加请求速率限制
|
||
|
||
---
|
||
|
||
## Part B：MCP 前端集成指南（内部使用）
|
||
|
||
> 适用范围：Hua.Todo 前端（Vue / TypeScript）团队。
|
||
|
||
### B.1 背景
|
||
|
||
v1.3.0 起，Hua.Todo 后端在原有 Dynamic API（`/api/*`）基础上，新增了 MCP 服务端点。前端可根据场景选择：
|
||
|
||
| 通道 | 端点 | 适用场景 |
|
||
|---|---|---|
|
||
| Dynamic API | `/api/task/*` | WebView 内常规 CRUD、已有逻辑兼容 |
|
||
| MCP | `/mcp` | AI 辅助、语音指令、外部工具集成 |
|
||
|
||
两套通道共享同一 `ITaskService` 业务层，数据一致。
|
||
|
||
### B.2 连接方式
|
||
|
||
| 模式 | MCP 端点 |
|
||
|---|---|
|
||
| 嵌入式（MAUI / Avalonia） | `http://localhost:5057/mcp` |
|
||
| Host（独立服务端） | `http://<host>:5173/mcp` |
|
||
|
||
### B.3 前端 MCP 客户端
|
||
|
||
推荐使用官方 TypeScript MCP SDK：
|
||
|
||
```bash
|
||
npm install @modelcontextprotocol/sdk
|
||
```
|
||
|
||
**连接示例**：
|
||
|
||
```typescript
|
||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamablehttp.js";
|
||
|
||
const transport = new StreamableHTTPClientTransport(
|
||
new URL("http://localhost:5057/mcp")
|
||
);
|
||
|
||
const client = new Client({ name: "hua-todo-frontend", version: "1.3.0" });
|
||
await client.connect(transport);
|
||
|
||
// 列出所有可用工具
|
||
const tools = await client.listTools();
|
||
|
||
// 调用工具
|
||
const result = await client.callTool({ name: "ListActiveTodos", arguments: {} });
|
||
```
|
||
|
||
**封装建议**（`src/api/mcpClient.ts`）：
|
||
|
||
```typescript
|
||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamablehttp.js";
|
||
|
||
const MCP_BASE_URL = window.__API_BASE_URL__
|
||
? window.__API_BASE_URL__.replace("/api", "/mcp")
|
||
: "/mcp";
|
||
|
||
let client: Client | null = null;
|
||
|
||
export async function getMcpClient(): Promise<Client> {
|
||
if (!client) {
|
||
const transport = new StreamableHTTPClientTransport(
|
||
new URL(MCP_BASE_URL, window.location.origin)
|
||
);
|
||
client = new Client({ name: "hua-todo-frontend", version: "1.3.0" });
|
||
await client.connect(transport);
|
||
}
|
||
return client;
|
||
}
|
||
|
||
export async function disconnectMcp(): Promise<void> {
|
||
if (client) { await client.close(); client = null; }
|
||
}
|
||
```
|
||
|
||
### B.4 工具调用映射
|
||
|
||
| 业务操作 | Dynamic API | MCP Tool |
|
||
|---|---|---|
|
||
| 获取所有待办项 | `GET /api/task` | `ListAllTodos` |
|
||
| 获取未完成待办项 | `GET /api/task/active` | `ListActiveTodos` |
|
||
| 获取已完成待办项 | `GET /api/task/completed` | `ListCompletedTodos` |
|
||
| 获取单个待办项 | `GET /api/task/{id}` | `GetTodoById` |
|
||
| 创建待办项 | `POST /api/task` | `CreateTodo` |
|
||
| 更新待办项 | `PUT /api/task` | `UpdateTodo` |
|
||
| 切换完成状态 | `PATCH /api/task/{id}/toggle` | `ToggleTodoComplete` |
|
||
| 删除待办项 | `DELETE /api/task/{id}` | `DeleteTodo` |
|
||
| 获取子待办项 | `GET /api/task/{pid}/subtasks` | `ListSubTodos` |
|
||
|
||
### B.5 返回格式差异
|
||
|
||
- **列表类** MCP 工具返回可读文本（如 `"未完成待办项（共 2 项）：[1] 完成报告..."`）
|
||
- **单条/创建/更新类** MCP 工具返回 JSON
|
||
- 前端如需结构化数据，建议仍使用 Dynamic API；MCP 通道主要用于 AI 场景和文本交互
|
||
|
||
### B.6 典型场景
|
||
|
||
**AI 对话式操作**：用户通过 AI 助手用自然语言操作待办项 → LLM 调用 MCP 工具 → 返回结果。
|
||
|
||
**语音指令**：语音 → STT → 文本 → LLM 解析意图 → MCP Tool 调用 → TTS 播报结果。
|
||
|
||
### B.7 注意事项
|
||
|
||
1. **无状态模式**：当前不支持服务端→客户端通知
|
||
2. **CORS**：开发环境 `AllowAll` 策略已覆盖 `/mcp`
|
||
3. **认证**：当前 MCP 端点未接入认证中间件
|
||
4. **生命周期**：建议在组件 `onUnmounted` 时调用 `disconnectMcp()`
|
||
|
||
---
|
||
|
||
> MCP 服务端实现细节见 [07-技术架构设计](./07-技术架构设计.md) 中 MCP 工具注册部分。
|