taskboard-mcp

An MCP server that integrates a Kanban task board into a sandboxed agent environment, built with FastMCP.

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.

Related MCP server: ForgeSwarm

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:

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

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

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.

Local development

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

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

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