@turboplan/mcp

A local stdio MCP server that lets an agent interact with plan files on disk, reusing the @turboplan/mdx-spec dialect library for all parsing, projection, mutation, and the comments data model. No hosted service — stdio + Node fs only, consistent with the local-first bet.

File paths are tool arguments; the server reads and writes the disk itself, rooted at the launch directory (or $TURBOPLAN_BASE_DIR). Absolute paths are honoured as-is.

Tools

| Tool | Signature | Result | | --- | --- | --- | | read_plan | (path) | { path, source } — raw MDX source | | outline | (path) | Outline — title, status, headings, tasks, taskCounts | | validate | (path) | ValidationResult — frontmatter + tag-whitelist check | | list_tasks | (path, view?) | { tasks, issues, view } — normalised + projected <Task> rows | | patch_block | (path, op, blockId, …args) | { path, source, validation } — mutate, write back, re-validate | | write_plan | (path, source) | { path, written, validation } — validate then write | | list_comments | (path) | { sidecarPath, exists, threads } — all threads + anchor resolution | | drain_comments | (path) | { sidecarPath, threads } — open, agent-targeted threads to act on | | resolve_thread | (path, threadId) | marks a thread resolved, writes the sidecar back | | reply_thread | (path, threadId, body, author?, resolve?) | appends a reply (optionally resolving), writes back |

patch_block ops

op selects one minimal-diff mutation from @turboplan/mdx-spec's mutate.ts (untouched bytes stay byte-for-byte identical). Each op reads its args from the flat argument object:

• setAttribute — requires name, value
• removeAttribute — requires name
• moveChild — requires childId, toIndex
• replaceText — requires text

After the mutation the new source is written to disk and re-validated; the validation field reports the post-write state.

view for list_tasks

The optional view overlays the dialect's legible mini-syntax:

{ "view": "board", "group": "status", "sort": "-priority", "filter": "owner=ana", "columns": "title,status" }

view may also name a views entry or a bare type (table / board / list).

Draining comments

drain_comments returns exactly the threads with status === "open" and resolutionTarget === "agent" — what the agent should act on this turn. The sidecar is loaded via the dialect's sidecarPathFor(planPath); a missing file yields an empty sidecar (no error). After acting (e.g. with patch_block), record the outcome with reply_thread and/or resolve_thread, which serialize the sidecar back to <plan>.comments.json.

Run

pnpm --filter @turboplan/mcp start   # tsx src/bin.ts
# or, once built / linked, the bin:
turboplan-mcp

The server speaks MCP over stdio; stdout is the protocol channel, so all diagnostics go to stderr.

Client config (Claude Code .mcp.json)

Add to a project's .mcp.json (or ~/.claude.json):

{
  "mcpServers": {
    "turboplan": {
      "command": "pnpm",
      "args": ["--filter", "@turboplan/mcp", "start"],
      "env": { "TURBOPLAN_BASE_DIR": "${workspaceFolder}" }
    }
  }
}

If you publish/build the package and expose the turboplan-mcp bin on PATH, the equivalent is simply:

{
  "mcpServers": {
    "turboplan": { "command": "turboplan-mcp", "args": [] }
  }
}

Plan paths passed to the tools are resolved relative to TURBOPLAN_BASE_DIR (falling back to the server's working directory).