# taskboard-mcp

An MCP server that integrates a Kanban task board into a sandboxed agent
environment, built with [FastMCP](https://gofastmcp.com).

The interesting part is not the task board. It is the **integration contract**:
what an RL sandbox needs from an application before it can be used to train or
evaluate an agent — a deterministic starting state, an exact snapshot, a
restore that round-trips, and rules that hold at the protocol boundary rather
than only in the UI.

```
┌──────────────┐   MCP over stdio/http   ┌─────────────────┐
│  agent /     │◄───────────────────────►│  server.py      │  protocol layer
│  harness     │                         │  (FastMCP)      │  15 tools, 3 resources
└──────────────┘                         └────────┬────────┘
       │                                          │
       │ populate / snapshot / restore            │
       │ (out of band, via CLI)                   ▼
       │                                 ┌─────────────────┐
       └────────────────────────────────►│  db.py          │  application layer
                                         │  state.py       │  rules + persistence
                                         └────────┬────────┘
                                                  ▼
                                            SQLite @ /data
```

## Why the layers are split

`server.py` contains no business rules. Every tool is a two-line translation
between an MCP call and a function in `db.py` or `state.py`. That split buys
three things:

- The app is testable without a protocol client in the loop (`test_db.py`).
- The protocol surface is testable without reasoning about business rules
  (`test_mcp_surface.py`).
- The same rules apply whether a call arrives from an agent, the CLI, or the
  harness — an agent cannot reach an illegal board state by going around the
  tool layer, because the tool layer is not where the check lives.

Expected failures raise `TaskboardError` subclasses and are mapped to
`ToolError` at the boundary. Unexpected exceptions are deliberately **not**
caught, so a genuine bug surfaces as a server error instead of being disguised
as a normal negative result.

## State hooks

Snapshots are JSON, not a copy of the SQLite file. That costs a little speed
and buys a lot: snapshots are diffable, hand-editable, portable across
schema-compatible versions, and comparable by hash.

Every snapshot carries a `digest` — a SHA-256 over the logical state with
volatile fields (row ids, timestamps) excluded, and comments keyed to their
task by title rather than by id. Two boards that arrive at the same logical
state by different routes produce the same digest:

```python
# different ids, different timestamps, same digest
assert snapshot_a["digest"] == snapshot_b["digest"]
```

That is what makes "did the agent reach the target state?" a one-line check
instead of a bespoke comparison per task.

```bash
python -m taskboard_mcp populate sprint_demo   # deterministic start state
python -m taskboard_mcp snapshot > before.json
python -m taskboard_mcp restore before.json    # exact round trip
python -m taskboard_mcp reset                  # empty board
python -m taskboard_mcp healthcheck            # exit 0 if usable
```

## Tool surface

| Tag | Tools |
| --- | --- |
| `read` | `board_summary`, `list_tasks`, `get_task`, `search_tasks`, `list_transitions` |
| `write` | `create_task`, `move_task`, `assign_task`, `comment_on_task`, `delete_task` |
| `admin` | `populate_state`, `snapshot_state`, `restore_state`, `reset_state`, `list_fixtures` |

Resources: `taskboard://board/summary`, `taskboard://task/{task_id}`,
`taskboard://schema`.

Tags are how a deployment filters the agent-visible tool list — see
`tool_visibility` in `app.yaml`. The harness still calls `admin` tools out of
band.

### Transition rules

Tasks move through `backlog → in_progress → review → done`. Skipping a column
is rejected, and so is a no-op move. `list_transitions` and the
`taskboard://schema` resource both expose the table so a client can check
before it calls rather than discovering the rule through an error.

## Configuration

All configuration is environment-driven, so one image deploys to any sandbox
slot without a rebuild.

| Variable | Default | Purpose |
| --- | --- | --- |
| `TASKBOARD_DB_PATH` | `/data/taskboard.db` | SQLite location |
| `TASKBOARD_FIXTURES_DIR` | `/app/fixtures` | Where `populate` looks |
| `TASKBOARD_TRANSPORT` | `stdio` | `stdio`, `http`, or `sse` |
| `TASKBOARD_HOST` / `TASKBOARD_PORT` | `0.0.0.0` / `8080` | HTTP bind |
| `TASKBOARD_READ_ONLY` | unset | Reject all mutating tools |

## Local development

```bash
make install      # venv + editable install with dev extras
make test         # 51 tests
make smoke        # spawns the server as a subprocess, drives a full episode
make lint
make run          # serve on stdio against ./local.db
```

### Docker

```bash
make docker-build
docker run --rm -i -v taskboard-data:/data taskboard-mcp:0.1.0 serve
docker run --rm -v taskboard-data:/data taskboard-mcp:0.1.0 populate sprint_demo
```

Multi-stage build, non-root user (uid 10001), `/data` as the only writable
path, and a `HEALTHCHECK` wired to the CLI's `healthcheck` subcommand.

## Testing approach

51 tests across three layers:

- **`test_db.py`** — business rules: transition legality, validation, cascade
  deletes, search behaviour, summary arithmetic.
- **`test_state.py`** — the hooks that matter for sandbox integration: exact
  round-trip, digest stability under id/timestamp churn, digest sensitivity to
  real changes, path-traversal rejection on fixture names, autoincrement reset
  after restore.
- **`test_mcp_surface.py`** — protocol layer via an in-memory `Client`: tool
  registration, docstring coverage, resource templates, error mapping,
  read-only enforcement.

Each test runs against its own SQLite file in a `tmp_path`, so the suite is
order-independent.

The suite is mutation-checked: making an illegal transition legal in
`config.py` turns three tests red, including one that only reads the schema
resource. Tests that stay green under a rule change are not testing the rule.

## Connecting a client

```json
{
  "mcpServers": {
    "taskboard": {
      "command": "python",
      "args": ["-m", "taskboard_mcp", "serve"],
      "env": {
        "TASKBOARD_DB_PATH": "/data/taskboard.db",
        "TASKBOARD_FIXTURES_DIR": "/app/fixtures"
      }
    }
  }
}
```

## Known limitations

- SQLite means a single writer. Fine for one sandbox per container, which is
  the deployment model; it would need revisiting for a shared instance.
- Full-state snapshots are `O(n)` in board size. At fixture scale that is
  microseconds, but a board with millions of tasks would want incremental
  capture.
- Search is `LIKE`-based substring matching, not FTS. Adequate for the tool
  surface; `sqlite3` FTS5 would be the upgrade path if search quality mattered.