# 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**
   ```bash
   git clone https://github.com/yourusername/mcp-todo-server.git
   cd mcp-todo-server
   ```

2. **Set up environment variables**
   ```bash
   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY
   ```

3. **Start with Docker Compose**
   ```bash
   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**
   ```bash
   curl http://localhost:3000/health
   ```

## API Endpoints

### Health Check
```bash
GET http://localhost:3000/health
```

### MCP Endpoint
```bash
GET/POST http://localhost:3000/mcp
```

Uses Server-Sent Events (SSE) for communication.

## Development

### Running Locally (without Docker)

```bash
# 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

```bash
npm run build
npm start
```

## Testing

Run the test suite:
```bash
./test.sh
```

Or try the example client:
```bash
npm run test:client
```

## Using with MCP Clients

### VS Code / Cursor

Add to your MCP config:
```json
{
  "mcpServers": {
    "todo": {
      "url": "http://localhost:3000/mcp",
      "transport": "sse"
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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

- [Model Context Protocol Docs](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## License

MIT