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

python -m venv venv

2. Activate Virtual Environment

Windows (PowerShell):

.\venv\Scripts\activate.ps1

Windows (CMD):

venv\Scripts\activate.bat

Linux/Mac:

source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

Running the Server

Development Mode (with auto-reload)

python app.py

Or using uvicorn directly:

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

Production Mode

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:

{
  "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:

{
  "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

# 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

# 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.