Hua.Todo/docs/manual/10-MCP服务集成.md

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 服务端信息

{
  "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 客户端 配置文件：

{
  "mcpServers": {
    "hua-todo": {
      "url": "http://localhost:5173/mcp",
      "transport": "streamable-http"
    }
  }
}

A.2.2 手动调用示例（curl）

初始化连接：

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" }
    }
  }'

列出可用工具：

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": {}}'

调用工具：

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

返回示例：

{
  "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：

npm install @modelcontextprotocol/sdk

连接示例：

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）：

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-技术架构设计 中 MCP 工具注册部分。