待办事项列表MCP服务器
项目介绍
📋 任务清单 MCP 服务器 - 完整教程
<div align="center">
🎯 这个项目是什么？
这是一个使用 TypeScript 和 Zod 实现了强大验证的任务管理系统（任务清单）的 MCP 服务器（模型上下文协议）。该服务器可以直接与 Claude Desktop 集成，允许您通过与 Claude 的自然对话来管理您的任务。
教程 - 步骤详解！
想要学习如何开发这个应用程序并了解 MCP？您可以在这里找到详细的步骤教程：这里
🌟 为什么使用 MCP？
模型上下文协议 是由 Anthropic 开发的一个协议，它允许 AI 助手以标准化的方式连接到外部工具和资源。通过这个项目，您可以：
- 🤖 与 Claude 自然地讨论他的任务
- 🔧 通过聊天直接运行操作
- 📊 获得关于生产力的智能见解
- 🛡️ 确保所有数据的强大验证
✨ 功能
🛠️ 完整的 CRUD 操作
- ✅ 创建任务，包括标题、描述、优先级和标签
- 📖 列出任务，带有高级过滤器和分页
- ✏️ 更新任务（标记为完成、更改优先级等）
- 🗑️ 删除特定任务
- 🔍 按文本搜索任务
📊 智能资源
- 📈 实时统计（总数、已完成、待办）
- 📋 自定义任务摘要
- 🎯 基于 AI 的优先级辅助
- 💡 详细分析的生产力见解
🔒 强大的验证
- ✅ 使用 Zod 模式进行运行时验证
- 🛡️ 完全类型安全（编译时 + 运行时）
- 🚨 清晰且具体的错误消息
- 🧹 数据自动清理
🏷️ 高级组织
- 🎯 优先级（低、中、高）
- 🏷️ 自定义标签用于分类
- 📅 自动时间戳（创建、完成）
- 🔄 统一状态（待办、已完成）
🏗️ 项目架构
该项目遵循 SOLID 原则，确保代码干净、可维护和可扩展：
src/
├── config/ # ⚙️ 配置
│ └── toolDefinitions.ts # 📋 中央化的 MCP 工具定义
├── handlers/ # 🎯 专门的处理器（SOLID）
│ ├── toolHandlers.ts # 🔧 管理工具操作
│ ├── resourceHandlers.ts # 📊 管理数据资源
│ └── promptHandlers.ts # 💡 管理提示模板
├── schemas/ # 📋 Zod 验证模式
│ ├── common.schemas.ts # 基础模式（UUID、Date 等）
│ └── todo.schemas.ts # 特定任务模式
├── services/ # 🔧 业务逻辑
│ └── todo.services.ts # 任务管理
├── utils/ # 🛠️ 工具
│ └── validation.ts # 验证助手
├── types.ts # 📝 TypeScript 类型
├── server.ts # 🖥️ 主 MCP 服务器（编排）
└── index.ts # 🚀 入口点
🏛️ 应用的 SOLID 原则
1. 单一职责原则 (SRP)
每个类都有一个独特的责任：
- ToolHandlers：仅处理工具操作（CRUD）
- ResourceHandlers：仅处理数据资源（查看）
- PromptHandlers：仅处理提示模板（分析）
- TodoMCPServer：仅处理服务器编排和配置
2. 开闭原则 (OCP)
- 每个处理器可以扩展而不修改现有代码
- 可以轻松添加新的操作类型
TOOL_DEFINITIONS允许添加工具而不触碰处理器
3. 里氏替换原则 (LSP)
- 所有处理器都实现了明确的契约
- 可以被替代实现所替换
- 对 MCP 操作的一致接口
4. 接口隔离原则 (ISP)
- 每个处理器都有其责任的具体接口
- 组件之间没有不必要的依赖
- 工具、资源和提示之间的清晰分离
5. 依赖倒置原则 (DIP)
- 处理器依赖于抽象
TodoService - 主服务器向处理器注入依赖
- 便于测试和部署替换
🔄 数据流
graph TB
A[Claude Desktop] --> B[TodoMCPServer]
B --> C{请求类型}
C -->|工具| D[ToolHandlers]
C -->|资源| E[ResourceHandlers]
C -->|提示| F[PromptHandlers]
D --> G[验证层 - Zod]
E --> G
F --> G
G --> H[TodoService]
H --> I[内存存储]
I --> H
H --> G
G --> D
G --> E
G --> F
D --> B
E --> B
F --> B
B --> A
style B fill:#e1f5fe
style D fill:#f3e5f5
style E fill:#e8f5e8
style F fill:#fff3e0
style H fill:#fce4ec
🧩 组件的责任
TodoMCPServer（编排器）
class TodoMCPServer {
private toolHandlers: ToolHandlers; // 委托 CRUD 操作
private resourceHandlers: ResourceHandlers; // 委托资源
private promptHandlers: PromptHandlers; // 委托提示
// 仅配置和路由请求
setupHandlers(): void {
this.server.setRequestHandler(CallToolRequestSchema,
(req) => this.toolHandlers.handleCallTool(req));
// ...
}
}
ToolHandlers（CRUD 操作）
class ToolHandlers {
handleCallTool(request): Promise<CallToolResult> {
switch (name) {
case "create_todo": return this.handleCreateTodo(request);
case "update_todo": return this.handleUpdateTodo(request);
case "delete_todo": return this.handleDeleteTodo(request);
// ...
}
}
}
ResourceHandlers
class ResourceHandlers {
handleReadResource(request): Promise<ReadResourceResult> {
switch (uri) {
case "todo://all": return this.handleAllTodos(uri);
case "todo://stats": return this.handleTodoStats(uri);
// ...
}
}
}
PromptHandlers（模板）
class PromptHandlers {
handleGetPrompt(request): Promise<GetPromptResult> {
switch (name) {
case "todo-summary": return this.handleTodoSummary(args);
case "todo-prioritization": return this.handleTodoPrioritization(args);
// ...
}
}
}
📋 预备知识
- Node.js 安装 18+
- Claude Desktop （最新版本）
- npm 或 yarn
- 代码编辑器（推荐 VS Code）
🚀 安装步骤
步骤 1：克隆/下载项目
# 如果使用 Git
git clone <你的仓库>
cd todo-list-mcp-server
# 或者新建文件夹
mkdir todo-list-mcp-server
cd todo-list-mcp-server
步骤 2：安装依赖
# 安装所有依赖
npm install
# 检查是否正确安装
npm list --depth=0
主要依赖项：
@modelcontextprotocol/sdk- 官方 MCP SDKzod- 方案验证typescript- TypeScript 语言tsx- 开发用 TypeScript 执行器
步骤 3：编译项目
# 将 TypeScript 编译为 JavaScript
npm run build
# 检查是否正确编译
ls dist/
步骤 4：测试服务器
# 测试服务器是否正确启动
npm start
你应该看到：
🔧 初始化 MCP 任务清单服务器...
🚀 MCP 任务清单服务器已启动
✅ 强大的验证已启用
🔒 类型安全已保证
按 Ctrl+C 停止。
⚙️ Claude Desktop 配置
步骤 1：定位配置文件
Windows:
%APPDATA%\Claude\claude_desktop_config.json
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
步骤 2：创建/编辑配置
⚠️ 重要提示： 使用项目的 绝对路径！
# 查找绝对路径
# Windows:
echo %cd%
# macOS/Linux:
pwd
示例配置：
{
"mcpServers": {
"todo-server": {
"command": "node",
"args": ["C:/Users/你的用户/caminho/para/todo-list-mcp-server/dist/index.js"]
}
}
}
步骤 3：重启 Claude Desktop
- 完全关闭 Claude Desktop
- 等待 5 秒
- 重新打开
🎮 如何使用
1. 基本命令
# 列出所有任务
"列出我所有的任务"
# 创建新任务
"创建任务：'学习 TypeScript'，优先级高"
# 搜索任务
"搜索包含 '学习' 的任务"
# 标记为完成
"将 ID [uuid] 的任务标记为完成"
2. 高级命令
# 创建完整任务
"创建任务：'实现身份验证'，描述 '添加 OAuth 登录'，优先级高，标签 '后端'，'安全'"
# 按状态筛选
"只显示未完成的任务"
# 按优先级筛选
"列出所有高优先级的任务"
# 获取统计数据
"显示我的任务统计数据"
3. 智能资源
# 个性化摘要
"生成按优先级分组的任务摘要"
# 优先级帮助
"帮我优先化我的未完成任务"
# 生产力见解
"分析我的生产力并提供建议"
🔧 数据结构
任务模型
interface Todo {
id: string; // 唯一的 UUID
title: string; // 标题（1-200 字符）
description?: string; // 可选描述（最多 500 字符）
completed: boolean; // 完成状态
createdAt: Date; // 创建日期
completedAt?: Date; // 完成日期（如果适用）
priority: 'low' | 'medium' | 'high'; // 优先级
tags: string[]; // 分类标签（最多 10 个）
}
任务示例
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "学习 MCP 协议",
"description": "使用 TypeScript 和 Zod 学习 Model Context Protocol",
"completed": false,
"createdAt": "2024-01-15T10:30:00.000Z",
"priority": "high",
"tags": ["学习", "typescript", "mcp"]
}
🛠️ 实现的 MCP 资源
1. 资源
只读端点用于数据可视化：
| URI | 描述 |
|---|---|
todo://all | 完整的任务列表。 |
todo://stats | 任务统计数据。 |
todo://completed | 仅已完成的任务。 |
todo://pending | 仅未完成的任务。 |
2. 工具
修改数据的操作：
| 工具 | 描述 |
|---|---|
create_todo | 创建新任务。 |
update_todo | 更新现有任务。 |
delete_todo | 删除任务。 |
list_todos | 带过滤器和分页的列表 |
get_todo | 按 ID 搜索任务。 |
search_todos | 文本搜索 |
3. 提示（模板）
用于分析的上下文模板：
| 提示 | 描述 |
|---|---|
todo_summary | 个性化摘要 |
todo_prioritization | 优先级帮助。 |
productivity_insights | 生产力分析 |
🔍 使用 Zod 进行验证
为什么使用 Zod？
Zod 确保所有数据在 编译时 和 运行时 都是有效的：
// ❌ 无 Zod - 危险
function createTodo(data: any) {
return {
title: data.title, // 可能是 undefined, null 或空！
priority: data.priority, // 可以是任何字符串！
};
}
// ✅ 有 Zod - 安全
function createTodo(data: unknown) {
const validatedData = validateData(CreateTodoSchema, data);
return {
title: validatedData.title, // ✅ 有效字符串（1-200 字符）
priority: validatedData.priority, // ✅ 'low' | 'medium' | 'high'
};
}
实现的方案
// 基础任务模式
export const TodoSchema = z.object({
id: UuidSchema,
title: NonEmptyStringSchema.max(200),
description: z.string().max(500).optional(),
completed: z.boolean().default(false),
createdAt: DateSchema,
completedAt: DateSchema.optional(),
priority: z.enum(['low', 'medium', 'high']).default('medium'),
tags: z.array(z.string().min(1).max(50)).max(10).default([])
});
// 创建任务模式
export const CreateTodoSchema = z.object({
title: NonEmptyStringSchema.max(200),
description: z.string().max(500).optional(),
priority: z.enum(['low', 'medium', 'high']).default('medium'),
tags: z.array(z.string().min(1).max(50)).max(10).default([])
});
📊 完整使用示例
场景 1：项目管理
用户: "为我的项目创建以下任务：
1. '项目初始设置' - 高优先级
2. '实现身份验证' - 中优先级
3. '编写测试' - 低优先级"
Claude: [使用 create_todo 工具创建 3 个任务]
用户: "帮我优先化这些任务"
Claude: [使用 todo_prioritization 提示进行分析]
用户: "将第一个任务标记为完成"
Claude: [使用 update_todo 将其标记为 completed: true]
场景 2：生产力分析
用户: "生成我的生产力报告"
Claude: [使用 productivity_insights 进行全面分析]
- 完成率：75%
- 高优先级任务：80% 已完成
- 最常用标签：前端（60%），后端（40%）
- 改进建议...
用户: "只显示高优先级的未完成任务"
Claude: [使用 list_todos 并过滤状态=pending，优先级=高]
🔧 开发和定制
SOLID 架构的好处
✅ 可持续性 每个文件都有特定的责任 ✅ 可测试性 处理器可以独立测试 ✅ 可扩展性 容易添加新功能 ✅ 重用性 组件可以重用 ✅ 调试性 错误按责任隔离
扩展结构
1. 添加新工具
// 1. 在 config/toolDefinitions.ts 中定义
{
name: "set_deadline",
description: "为任务设置截止日期",
inputSchema: {
type: "object",
properties: {
id: { type: "string", format: "uuid" },
deadline: { type: "string", format: "date" }
},
required: ["id", "deadline"]
}
}
// 2. 在 handlers/toolHandlers.ts 中实现
private async handleSetDeadline(request: CallToolRequest): Promise<CallToolResult> {
const { args } = request.params;
const validatedData = validateData(SetDeadlineSchema, args);
// 实现逻辑...
}
// 3. 在 handleCallTool 的 switch 中添加
case "set_deadline": return this.handleSetDeadline(request);
2. 添加新资源
// 1. 在 resourceHandlers.ts 中添加定义
{
uri: "todo://overdue",