cateland/poc_todo_mcp_server

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

1. Server Initialization: Server declares or auto-discovers its capabilities
2. Client Connection: Client connects and receives server capability information during handshake
3. 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
4. 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

• Model Context Protocol Documentation
• Official TypeScript SDK
• MCP Inspector Tool
• MCP Specification

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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Follow the existing code style and patterns
4. Add tests for new functionality
5. Update documentation as needed
6. 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 Model Context Protocol TypeScript SDK