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
  comple