# MCP ToDo Server

Production-ready Model Context Protocol server for task and todo management with dual storage backends, error handling, and modern Python tooling.

## Features

- **Dual Storage**: File-based JSON or database (SQLite/PostgreSQL)
- **Todo Management**: Standalone todos and structured tasks with priorities/due dates
- **Bulk Operations**: Efficient multi-item management and analytics
- **Security**: Input validation, error handling, containerization
- **Modern Tooling**: uv package manager, comprehensive testing, structured logging

## Architecture

```
MCP Server → Business Logic → Storage (File/Database) → Infrastructure
```

## Quick Start

```bash
# Clone and install
git clone https://github.com/AnoRebel/mcp-todo-server.git
cd mcp-todo-server
uv sync  # or pip install -r requirements.txt

# Run with file storage (default)
uv run python server.py

# Run with database storage
export MCP_STORAGE_TYPE=database
export MCP_DATABASE_URL=sqlite:///todos.db
uv run python server.py

# Docker
docker-compose up -d

# Development
make test && make format
```

## Configuration

Environment variables:
- `MCP_STORAGE_TYPE`: `file` or `database` (default: file)
- `MCP_DATABASE_URL`: Database connection string
- `MCP_LOG_LEVEL`: DEBUG, INFO, WARNING, ERROR
- `MCP_MAX_TASKS`: Maximum tasks (default: 1000)
- `MCP_MAX_TODOS`: Maximum todos (default: 1000)

## Usage

### Basic Operations
```python
# Standalone todos
add_todo("Buy groceries")
list_todos(status="open")
complete_todo("todo-id")

# Structured tasks
create_task(name="Project", priority="high", due_date="2024-12-31")
add_task_todo("task-id", "Subtask description")
bulk_task_operation(operation="complete", filters={"priority": "low"})

# Analytics
get_productivity_stats()
```

## Error Handling

- Circuit breaker pattern for failure prevention
- Automatic retry with exponential backoff
- Categorized errors with user-friendly messages
- Comprehensive logging and monitoring

## Testing

```bash
make test              # All tests with coverage
pytest tests/ -v       # Verbose test output
```

Coverage includes storage backends, CRUD operations, error handling, and data models.

## Security & Performance

- Input validation and sanitization
- Container security (non-root execution)
- Database connection pooling and atomic operations
- Configurable limits and graceful degradation
- Structured logging for observability

## Deployment

### Docker
```bash
docker-compose up -d                              # File storage
docker-compose --profile database up -d           # With PostgreSQL
```

### Kubernetes
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-todo-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: mcp-todo-server
        image: mcp-todo-server:latest
        env:
        - name: MCP_STORAGE_TYPE
          value: "database"
        - name: MCP_DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
```

## Integration

### Claude Desktop
```json
{
  "mcpServers": {
    "todo-manager": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "MCP_STORAGE_TYPE": "file",
        "MCP_DATA_DIR": "/Users/username/.claude_todos"
      }
    }
  }
}
```

### Project Structure
```
mcp-todo-server/
├── server.py             # Main server
├── config.py            # Configuration
├── models/              # Data models
├── storage/             # Storage backends
├── tests/              # Test suite
├── docker-compose.yml  # Container setup
└── requirements.txt    # Dependencies
```

## Contributing

1. Fork and create feature branch
2. Add tests and follow PEP 8
3. Run `make test && make format`
4. Submit PR with clear description

## Performance

**Storage Comparison:**
- File: Simple, <1000 items recommended
- Database: Scalable, concurrent access, millions of items

**Benchmarks:**
| Operation | File | SQLite | PostgreSQL |
|-----------|------|--------|------------|
| Add Todo | 5ms | 2ms | 3ms |
| List 100 | 15ms | 5ms | 8ms |

## License

MIT License - see [LICENSE](LICENSE) file.

## Support

- GitHub Issues for bugs/features
- Email: hacker4rebel@gmail.com

---

**Built with ❤️ following MCP best practices**