MCP-Todo-Server

xenagarage/MCP-Todo-Server

3.2

If you are the rightful owner of MCP-Todo-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Todo Server is a distributed task management server utilizing the Model Context Protocol (MCP) with TypeScript, Redis, and OpenAI for enhanced task analysis.

Tools
6
Resources
0
Prompts
0

MCP Todo Server

A distributed task management server built on the Model Context Protocol (MCP). Uses TypeScript, Redis for shared state, and OpenAI for smart task analysis.

Features

  • MCP protocol implementation with 6 custom tools
  • Multi-node setup with load balancing via Caddy
  • Redis for distributed state (works across nodes)
  • AI task prioritization using OpenAI
  • Docker Compose for easy deployment
  • Health monitoring and graceful shutdown

Available Tools

  • todo_add - Add new tasks with priority levels
  • todo_list - List todos with status filtering
  • todo_remove - Remove specific tasks
  • todo_clear - Clear all tasks
  • todo_mark_done - Mark tasks as completed
  • todo_analyze - Get AI-powered task prioritization

Architecture

┌─────────────┐
│   Caddy     │  Load Balancer
│  Port 3000  │
└──────┬──────┘
       │
       ├────────────┬────────────┐
       ▼            ▼            ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│  Node 1  │ │  Node 2  │ │  Node N  │
│ Port 3001│ │ Port 3002│ │ Port 300N│
└────┬─────┘ └────┬─────┘ └────┬─────┘
     │            │            │
     └────────────┴────────────┘
                  │
            ┌─────▼──────┐
            │   Redis    │  Shared State
            │  Port 6379 │
            └────────────┘

Getting Started

Prerequisites

  • Docker and Docker Compose
  • Node.js 18+ (for local dev)
  • OpenAI API key

Installation

  1. Clone the repository

    git clone https://github.com/yourusername/mcp-todo-server.git
cd mcp-todo-server

  2. Set up environment variables

    cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

  3. Start with Docker Compose

    docker compose up --build

    This starts:

    • Redis on port 6379
    • MCP Server Node 1 on port 3001
    • MCP Server Node 2 on port 3002
    • Caddy load balancer on port 3000

  4. Verify the deployment

    curl http://localhost:3000/health

API Endpoints

Health Check

GET http://localhost:3000/health

MCP Endpoint

GET/POST http://localhost:3000/mcp

Uses Server-Sent Events (SSE) for communication.

Development

Running Locally (without Docker)

# Install dependencies
npm install

# Start Redis
docker run -d -p 6379:6379 redis:7-alpine

# Set environment variables
export REDIS_URL=redis://localhost:6379
export OPENAI_API_KEY=your_key_here
export NODE_ID=dev-node

# Run development server
npm run dev

Build for Production

npm run build
npm start

Testing

Run the test suite:

./test.sh

Or try the example client:

npm run test:client

Using with MCP Clients

VS Code / Cursor

Add to your MCP config:

{
  "mcpServers": {
    "todo": {
      "url": "http://localhost:3000/mcp",
      "transport": "sse"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todo": {
      "command": "node",
      "args": ["/path/to/mcp-todo-server/dist/main.js"],
      "env": {
        "REDIS_URL": "redis://localhost:6379",
        "OPENAI_API_KEY": "your-key-here"
      }
    }
  }
}

Project Structure

.
├── src/
│   ├── main.ts           # Express server & MCP transport
│   ├── mcp-tools.ts      # MCP tool implementations
│   ├── redis-client.ts   # State management
│   └── ai-service.ts     # OpenAI integration
├── docker-compose.yml    # Multi-node orchestration
├── Dockerfile            # Container definition
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript config
├── test.sh              # Automated testing
└── example-client.js    # MCP client example

Security Notes

For production, add:

  • Authentication
  • HTTPS
  • Redis password
  • Input validation
  • Rate limiting

Resources

License

MIT