Poc Todo MCP Server

Todo MCP服务器

一个强大的模型上下文协议（MCP）服务器，用于管理todo，使用TypeScript和官方MCP SDK构建。此实现演示了现代MCP最佳实践，包括正确的错误处理、服务器功能配置和全面的工具/资源/提示集成。

🚀 特性

🛠️ 工具（AI可以执行）

• create_todo -创建带有标题、描述、优先级和标签的新待办事项
• list_todos -按状态（已完成/待处理）、优先级和标签列出和过滤待办事项
• update_todo -更新任何待办事项字段，包括完成状态和元数据
• delete_todo -按ID删除待办事项并确认
• todo_stats -生成全面的统计数据和分析

📄 资源（AI可以读取）

• todos://json -以结构化JSON形式完成todo数据集
• todos://summary -快速总结计数、完成率和指标

💬 提示（AI模板）

• daily_report -通过过滤生成专业的每日待办事项报告
• prioritize_tasks -通过智能任务优先级排序获得人工智能帮助

📋 快速开始

先决条件

• Node.js 18+
• npm或纱线
• TypeScript知识（可选使用）

安装和设置

# 1. Clone and install dependencies
git clone 
cd todo-mcp-server
npm install

# 2. Build the TypeScript project
npm run build

# 3. Test with MCP Inspector (optional)
npm test

# 4. Configure with your MCP client

配置

对于游标IDE：

添加到光标设置(~/.cursor/settings.json):

{
  "mcp-servers": {
    "todo-manager": {
      "command": "node",
      "args": ["/path/to/your/todo-mcp-server/dist/index.js"],
      "env": {},
      "cwd": "/path/to/your/todo-mcp-server"
    }
  }
}

对于Claude Desktop：

增添 ~/.claude_desktop_config.json:

{
  "mcpServers": {
    "todo-manager": {
      "command": "node",
      "args": ["/path/to/your/todo-mcp-server/dist/index.js"]
    }
  }
}

🎯 使用示例

连接到MCP客户端后，您可以自然地进行交互：

创建和管理待办事项

"Create a high-priority todo to review the quarterly report with tags 'work' and 'urgent'"
"Add a shopping task for groceries with medium priority"
"Mark the quarterly report todo as completed"
"Update my shopping task to high priority and add description 'organic produce'"

查看和筛选

"Show me all high priority pending todos"
"List all completed todos from this week"
"Display todos tagged with 'work'"
"Show my todo statistics and completion rate"

AI驱动的洞察

"Generate a daily report for today excluding completed tasks"
"Help me prioritize my current pending tasks"
"Create a professional summary of my productivity"

🏗️ 架构与实施

现代MCP SDK模式

此实现遵循当前的MCP SDK最佳实践：

// High-level API - capabilities are automatically discovered
const server = new McpServer({
  name: "todo-manager",
  version: "1.0.0"
});

// The SDK automatically discovers capabilities based on what you register:
server.tool("create_todo", schema, handler);      // Adds 'tools' capability
server.resource("todos://json", handler);         // Adds 'resources' capability  
server.prompt("daily_report", schema, handler);   // Adds 'prompts' capability

// Comprehensive error handling
server.tool("create_todo", schema, async (params) => {
  try {
    // Implementation
    return { content: [...] };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Error: ${error.message}` }],
      isError: true
    };
  }
});

能力发现的工作原理

1. 服务器初始化：服务器声明或自动发现其功能
2. 客户端连接：客户端在握手过程中连接并接收服务器能力信息
3. 动态发现：客户端调用这些方法来发现可用功能：

- client.listTools() -发现可用工具 - client.listResources() -发现可用资源 - client.listPrompts() -发现可用提示

1. 用法：然后，客户端可以调用特定工具、阅读资源或使用提示

高层 McpServer API根据您实际注册的内容自动处理功能广告，使其使用更加简单。

项目结构

todo-mcp-server/
├── src/
│   └── index.ts          # Main server implementation with modern patterns
├── dist/                 # Compiled JavaScript output
├── package.json          # Dependencies and build scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # Documentation (this file)

数据模型

interface Todo {
  id: string;               // Unique identifier
  title: string;            // Todo title (required)
  description?: string;     // Optional detailed description
  completed: boolean;       // Completion status
  priority: 'low' | 'medium' | 'high';  // Priority level
  createdAt: Date;          // Creation timestamp
  updatedAt: Date;          // Last modification timestamp
  tags: string[];           // Organizational tags
}

🔧 发展

可用脚本

# Development mode with hot reload
npm run dev

# Production build
npm run build

# Run the server
npm start

# Test with MCP Inspector
npm test

# Lint and format code
npm run lint
npm run format

MCP检验员测试

这 MCP检查员 是官方测试工具：

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Test your server
npx @modelcontextprotocol/inspector node dist/index.js

错误处理和记录

服务器实现了全面的错误处理：

• 工具错误：优雅的失败，用户友好的消息
• 资源错误：使用上下文进行适当的异常处理
• 流程错误：优雅的关机和清理
• 验证错误：Zod模式验证，并提供详细反馈

性能注意事项

• 内存存储发展迅速；替换为生产数据库
• 异步操作：所有操作都是正确的async/await
• 资源管理：服务器关闭时进行适当的清理
• 错误隔离：一次操作中的错误不会导致服务器崩溃

🚀 生产部署

数据库集成

用适当的数据库替换内存中的映射：

// Example with PostgreSQL
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// Implement CRUD operations with proper transactions

环境配置

# .env file
NODE_ENV=production
DATABASE_URL=postgresql://user:pass@localhost/todos
LOG_LEVEL=info
PORT=3000

监测和可观察性

考虑添加：

• 结构化日志（Winston，Pino）
• 度量收集（普罗米修斯）
• 健康检查端点
• 请求跟踪

🔮 扩展服务器

添加新工具

server.tool(
  "archive_todo",
  { id: z.string() },
  async ({ id }) => {
    // Implementation
  }
);

添加新资源

server.resource(
  "todos-by-date",
  "todos://by-date/{date}",
  async (uri, { date }) => {
    // Implementation
  }
);

添加新提示

server.prompt(
  "weekly_review",
  "Generate a weekly productivity review",
  { week: z.string() },
  async ({ week }) => {
    // Implementation
  }
);

📚 了解更多

MCP资源

• 模型上下文协议文档
• TypeScript官方SDK
• MCP检查工具
• MCP规范

高级主题

• 认证：实现OAuth或API密钥身份验证
• 速率限制：添加用于生产的请求限制
• 缓存：实现Redis或内存缓存
• 网页插件：添加实时通知
• 协作：多用户待办事项管理
• 同步：跨设备同步

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 遵循现有的代码样式和模式
4. 添加新功能的测试
5. 根据需要更新文档
6. 提交拉取请求

代码规范

• 使用严格模式的TypeScript
• 遵循现有的错误处理模式
• 为公共API添加JSDoc注释
• 确保所有测试通过
• 遵循语义版本控制

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

______________________________________________________________________

内置于❤️ 使用官方 模型上下文协议TypeScript SDK