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

```bash
cd todo_mcp
uv sync
```

### 2. Launch the Daemon

```bash
uv run todo-serve --port 8765
```

Once running:
- **Browser UI:** Open [http://127.0.0.1:8765/](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](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:

```json
{
  "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):

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

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

---

## FastMCP API Reference

### Tools

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `create_task` | `title: str`, `description: str = ""`, `status: str = "New"`, `story_points: int?`, `due_date: str?`, `parent_id: int?` | Create a new task card. |
| `update_task_status` | `task_id: int`, `status: str` | Move a card through `New`, `Active`, `In Review`, `Closed`. Enforces Rules 1, 2, and 3. |
| `update_task_details` | `task_id: int`, `title: str?`, `description: str?`, `story_points: int?`, `due_date: str?` | Modify card metadata and description. |
| `break_down_task` | `task_id: int`, `subtasks: list[dict]` | Decomposes a card into subtasks inheriting the parent's active state. |
| `search_tasks` | `query: str`, `status_filter: str?` | Token-sanitized FTS5 search with BM25 relevance ranking. |
| `get_daily_summary` | *(none)* | Returns velocity ledger: cards completed today, points remaining, active tasks. |
| `suggest_next_task` | *(none)* | Heuristic recommendation for the next best card to focus on. |

### 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):

```bash
uv run python run_tests.py
```

Run interactive verification scripts:

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