How do I use Todo MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Todo MCP Server Show me all high priority pending todos" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Todo MCP Server

A robust Model Context Protocol (MCP) server for managing todos, built with TypeScript and the official MCP SDK. This implementation demonstrates modern MCP best practices including proper error handling, server capabilities configuration, and comprehensive tool/resource/prompt integration.

🚀 Features

🛠️ Tools (AI can execute)

create_todo - Create new todos with title, description, priority levels, and tags
list_todos - List and filter todos by status (completed/pending), priority, and tags
update_todo - Update any todo field including completion status and metadata
delete_todo - Remove todos by ID with confirmation
todo_stats - Generate comprehensive statistics and analytics

📄 Resources (AI can read)

todos://json - Complete todo dataset as structured JSON
todos://summary - Quick summary with counts, completion rates, and metrics

💬 Prompts (AI templates)

daily_report - Generate professional daily todo reports with filtering
prioritize_tasks - Get AI assistance with intelligent task prioritization

📋 Quick Start

Prerequisites

Node.js 18+
npm or yarn
TypeScript knowledge (optional for usage)

Installation & Setup

# 1. Clone and install dependencies git clone <repository-url> 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

Configuration

For Cursor IDE:

Add to your Cursor settings (~/.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" } } }

For Claude Desktop:

Add to ~/.claude_desktop_config.json:

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

🎯 Usage Examples

Once connected to your MCP client, you can interact naturally:

Creating & Managing Todos

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

Viewing & Filtering

"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-Powered Insights

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

🏗️ Architecture & Implementation

Modern MCP SDK Patterns

This implementation follows current MCP SDK best practices:

// 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 }; } });

How Capability Discovery Works

Server Initialization: Server declares or auto-discovers its capabilities
Client Connection: Client connects and receives server capability information during handshake
Dynamic Discovery: Client calls these methods to discover available features:
- client.listTools() - Discover available tools
- client.listResources() - Discover available resources
- client.listPrompts() - Discover available prompts
Usage: Client can then call specific tools, read resources, or use prompts

The high-level McpServer API automatically handles capability advertisement based on what you actually register, making it much simpler to use.

Project Structure

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)

Data Model

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

Available Scripts

# 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

Testing with MCP Inspector

The MCP Inspector is the official testing tool:

# Install MCP Inspector globally npm install -g @modelcontextprotocol/inspector # Test your server npx @modelcontextprotocol/inspector node dist/index.js

Error Handling & Logging

The server implements comprehensive error handling:

Tool errors: Graceful failure with user-friendly messages
Resource errors: Proper exception handling with context
Process errors: Graceful shutdown and cleanup
Validation errors: Zod schema validation with detailed feedback

Performance Considerations

In-memory storage: Fast for development; replace with database for production
Async operations: All operations are properly async/await
Resource management: Proper cleanup on server shutdown
Error isolation: Errors in one operation don't crash the server

🚀 Production Deployment

Database Integration

Replace the in-memory Map with a proper database:

// Example with PostgreSQL import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // Implement CRUD operations with proper transactions

Environment Configuration

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

Monitoring & Observability

Consider adding:

Structured logging (Winston, Pino)
Metrics collection (Prometheus)
Health check endpoints
Request tracing

🔮 Extending the Server

Adding New Tools

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

Adding New Resources

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

Adding New Prompts

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

📚 Learn More

MCP Resources

Advanced Topics

Authentication: Implement OAuth or API key authentication
Rate Limiting: Add request throttling for production use
Caching: Implement Redis or in-memory caching
Webhooks: Add real-time notifications
Collaboration: Multi-user todo management
Sync: Cross-device synchronization

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Follow the existing code style and patterns
Add tests for new functionality
Update documentation as needed
Submit a pull request

Code Standards

Use TypeScript with strict mode
Follow the existing error handling patterns
Add JSDoc comments for public APIs
Ensure all tests pass
Follow semantic versioning

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ using the official