# MCP Todo & Context Server

A lightweight backend service that provides AI clients with two core capabilities:
1. **Todo Management**: Create, list, complete, and delete todo items per project
2. **Project Context**: Record and retrieve running context notes about a project's state

## Features

- ✅ Per-project todo lists with priority levels
- 📝 Append-only context notes for tracking project state
- 🔄 Resume work summaries (status + recent notes + open todos)
- 🌐 MCP (Model Context Protocol) endpoint for AI clients
- 💾 Persistent JSON file storage
- 🚀 Single-instance deployment with FastAPI + uvicorn

## Architecture

```
mcp-todo-context-server/
├── app.py              # FastAPI entry point - mounts /mcp and /health
├── server.py           # FastMCP instance + tool definitions
├── storage.py          # Persistence layer - reads/writes data.json
├── data/
│   └── data.json       # Runtime data file (auto-created)
├── requirements.txt
└── README.md
```

## Installation

### 1. Create Virtual Environment

```bash
python -m venv venv
```

### 2. Activate Virtual Environment

**Windows (PowerShell):**
```powershell
.\venv\Scripts\activate.ps1
```

**Windows (CMD):**
```cmd
venv\Scripts\activate.bat
```

**Linux/Mac:**
```bash
source venv/bin/activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

## Running the Server

### Development Mode (with auto-reload)

```bash
python app.py
```

Or using uvicorn directly:

```bash
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

### Production Mode

```bash
uvicorn app:app --host 0.0.0.0 --port 8000
```

The server will be available at:
- MCP endpoint: `http://localhost:8000/mcp`
- Health check: `http://localhost:8000/health`
- API docs: `http://localhost:8000/docs`

## MCP Tools

The server exposes the following tools via the MCP protocol:

### Todo Management

1. **create_todo** - Create a new todo item
   - `project_name` (required): Project identifier
   - `title` (required): Todo title
   - `description` (optional): Detailed description
   - `priority` (optional): low/medium/high (default: medium)

2. **list_todos** - List todos for a project
   - `project_name` (required): Project identifier
   - `filter_status` (optional): 'open', 'done', or None for all

3. **complete_todo** - Mark a todo as complete
   - `project_name` (required): Project identifier
   - `todo_id` (required): Todo ID to complete

4. **delete_todo** - Delete a todo permanently
   - `project_name` (required): Project identifier
   - `todo_id` (required): Todo ID to delete

### Project Context

5. **append_context_note** - Add a context note to project history
   - `project_name` (required): Project identifier
   - `note` (required): Context note text
   - `status` (optional): Update project status label

6. **get_project_summary** - Get resume-work summary
   - `project_name` (required): Project identifier
   - `recent_notes_count` (optional): Number of recent notes (default: 10)
   - Returns: status, recent notes, and all open todos

### Project Directory

7. **list_projects** - List all projects
   - No parameters required
   - Returns: All projects with status and open todo counts

## Connecting AI Clients

### Claude Desktop Configuration

Add to your Claude Desktop MCP settings:

```json
{
  "mcpServers": {
    "todo-context": {
      "command": "uvicorn",
      "args": ["app:app", "--host", "localhost", "--port", "8000"],
      "cwd": "/path/to/mcp-todo-context-server",
      "env": {
        "VIRTUAL_ENV": "/path/to/mcp-todo-context-server/venv"
      }
    }
  }
}
```

## Data Storage

Data is stored in `data/data.json` with the following structure:

```json
{
  "projects": {
    "project-name": {
      "name": "project-name",
      "status": "active",
      "context_log": [
        {
          "timestamp": "2026-08-13T10:30:00.000Z",
          "note": "Implemented user authentication"
        }
      ],
      "todos": [
        {
          "id": "20260813103000123456",
          "title": "Add password reset",
          "description": "Implement email-based password reset flow",
          "priority": "high",
          "done": false,
          "created": "2026-08-13T10:30:00.000Z",
          "completed": null
        }
      ]
    }
  }
}
```

## Example Usage

### Creating a Todo

```python
# Via MCP tool call
{
  "tool": "create_todo",
  "arguments": {
    "project_name": "my-app",
    "title": "Implement user authentication",
    "description": "Add JWT-based auth with refresh tokens",
    "priority": "high"
  }
}
```

### Getting Project Summary

```python
# Via MCP tool call
{
  "tool": "get_project_summary",
  "arguments": {
    "project_name": "my-app",
    "recent_notes_count": 5
  }
}
```

Response includes:
- Current project status
- 5 most recent context notes
- All open todos
- Metadata (counts, timestamps)

## API Endpoints

- `GET /` - Service information
- `GET /health` - Health check
- `GET /docs` - Interactive API documentation (Swagger UI)
- `POST /mcp` - MCP protocol endpoint

## Requirements

- Python 3.8+
- FastAPI
- uvicorn
- fastmcp (FastMCP - Model Context Protocol SDK)
- pydantic
- python-dotenv

## Roadmap

### v1.0 (Current)
- ✅ MCP endpoint with 7 tools
- ✅ JSON file storage
- ✅ Direct uvicorn deployment

### Future Considerations
- SQLite/PostgreSQL backend option
- Authentication/authorization layer
- Docker containerization
- Multi-user support
- Tags/categories for context notes
- Due dates and reminders for todos

## License

MIT License - see LICENSE file for details

## Contributing

Contributions welcome! Please open an issue or PR.

## Support

For issues or questions, please open a GitHub issue.