todo-mcp: Local-First Kanban Board with FastMCP & Reflex

A personal productivity tool that combines an Azure DevOps-style Kanban Board with a FastMCP (Model Context Protocol) server in a single ASGI process.

You get a responsive, open-source web frontend for humans (built with Reflex and Radix UI, with zero watermarks or branding ribbons) and an MCP interface for AI coding assistants (Claude Desktop, Cursor, etc.), sharing the exact same SQLite database with real-time sync.

Key Features

• Unified ASGI Daemon: Single ASGI process on port 8765 hosting FastMCP SSE at /mcp/sse and the Reflex Kanban UI at /.

• 100% Open Source & Zero Watermarks: Pure Reflex + Radix UI frontend (Apache 2.0). No "Made with X" or framework branding ribbons anywhere.

• Azure DevOps Workflow Rules:

  • Rule 1 (Parent Activation): Moving a parent task to Active automatically moves all its direct subtasks to Active.

  • Rule 2 (Subtask Closure Independence): Subtasks close independently without altering the parent status.

  • Rule 3 (Parent Closure Constraint): Moving a parent to Closed is strictly blocked if any subtasks remain open, raising detailed validation errors.

  • Rule 4 (Time Tracking): Automatically sets closed_at UTC timestamp upon entering Closed, and wipes it to None if reopened.

• Pure Python React-like UI (Reflex & Radix):

  • 4 columns: New, Active, In Review, and Closed.

  • Card anatomy: #ID, title, story point badge, overdue date warning chip, and subtask progress bar.

  • Card Detail Modal: inline title editing, status selector, story points, due date, rich Markdown editor (Edit/Preview tabs), and interactive subtask checklist.

  • Full-Text Search (SQLite FTS5 BM25 relevance ranking).

  • Top velocity metrics bar (Active cards, Backlog points, Closed today).

  • "Suggest Next Task" focus button running heuristic scoring.

• FastMCP Protocol Support:

  • 7 Tools: create_task, update_task_status, update_task_details, break_down_task, search_tasks, get_daily_summary, suggest_next_task.

  • 4 Resources: todo://board, todo://today (and kanban:// aliases).

  • 2 Prompts: plan-my-day, task-breakdown.

• Concurrent Multi-Process Access: Uses SQLite in WAL mode (PRAGMA journal_mode=WAL;), enabling simultaneous access from the web daemon and standalone CLI tools (todo-stdio).

Quickstart

1. Installation

Requires Python 3.12+ and uv.

cd todo_mcp
uv sync

2. Launch the Daemon

uv run todo-serve --port 8765

Once running:

• Browser UI: Open http://127.0.0.1:8765/

• FastMCP SSE Endpoint: http://127.0.0.1:8765/mcp/sse

• Health Check: http://127.0.0.1:8765/health

AI Client Configuration

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Unified SSE Mode (Recommended)

Connects directly to the running todo-serve daemon:

{
  "mcpServers": {
    "todo-mcp": {
      "url": "http://127.0.0.1:8765/mcp/sse",
      "transport": "sse"
    }
  }
}

Option B: Standalone Stdio Mode

Runs FastMCP directly over stdio (shares the same ~/.todo_mcp/todo.db SQLite database):

{
  "mcpServers": {
    "todo-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/todo_mcp",
        "run",
        "todo-stdio"
      ]
    }
  }
}

Cursor

In Cursor Settings → Features → MCP:

• Name: todo-mcp

• Type: sse

• URL: http://127.0.0.1:8765/mcp/sse

Or in .cursor/mcp.json:

{
  "mcpServers": {
    "todo-mcp": {
      "url": "http://127.0.0.1:8765/mcp/sse"
    }
  }
}

FastMCP API Reference

Tools

Resources

• todo://board (or kanban://board): Full Kanban board state organized by column with estimates and subtask completion ratios.

• todo://today (or kanban://today): Daily velocity report and list of tasks completed today.

Prompts

• plan-my-day: Gathers today's board metrics and guides the LLM to propose 1–3 cards to activate based on urgency and backlog points.

• task-breakdown: Prompts the assistant to decompose a specific card ID into 3–6 actionable subtasks.

Testing & Verification

Run the full automated test suite (38 unit and integration tests):

uv run python run_tests.py

Run interactive verification scripts:

# Step 1: Database & Models (WAL, FTS5 BM25, Foreign Keys)
uv run python scripts/verify_step1.py

# Step 2: Kanban Service Layer & Rules 1-4
uv run python scripts/verify_step2.py

# Step 3: FastMCP Tools, Resources, & Prompts
uv run python scripts/verify_step3.py

# Step 4: Unified ASGI Daemon Host & CLI
uv run python scripts/verify_step4.py

# Step 5: Reflex Kanban Board View & Radix UI
uv run python scripts/verify_step5.py

# Step 6: Card Detail Modal & Subtask Management
uv run python scripts/verify_step6.py

# Step 7: Complete End-to-End AI Workflow & Real-Time Sync
uv run python scripts/verify_e2e.py

License

MIT