@outputty/tasks-mcp

A local MCP server that exposes outputty's task tracker as typed tools. The dependency graph lives in a committed cache in your repo; each task is synced two-way to a GitHub Issue and onto a GitHub Projects board. A coding agent calls add_task / list_ready / schedule instead of shelling out to a CLI.

• The cache owns the graph. Deps can't live in a GitHub Issue, so the authoritative task graph is a committed file (.claude/tasks.cache.yaml). It travels with the repo and survives a fresh clone.

• Backends are sync targets. GitHub Issues carry the human-facing record (title, open/closed, a body mirror); GitHub Projects gives a kanban view. Reads come from the cache, so they never wait on GitHub.

• Your existing credentials. GITHUB_TOKEN, or whatever gh auth login already stored. No new login.

Requirements

Related MCP server: mcp-server-tasktracker

Install

No clone. Add the server to your project's .mcp.json and Claude Code launches it on demand with bunx:

{
  "mcpServers": {
    "tasks": { "command": "bunx", "args": ["-y", "@outputty/tasks-mcp"] }
  }
}

That runs the stdio transport. For a long-running shared instance, run the HTTP server instead:

bunx -y @outputty/tasks-mcp --http        # http://localhost:3917/mcp  (health: /health)

{
  "mcpServers": {
    "tasks": { "type": "http", "url": "http://localhost:3917/mcp" }
  }
}

What the tools do

Every tool takes project — the absolute path to the repo it acts on — because the server has no working directory of its own. The first write to a repo it hasn't seen provisions the outputty label and (if enabled) the Projects board automatically.

// add_task — a typed call, so a multi-line brief needs no shell quoting
{
  "project": "/abs/path/to/repo",
  "id": "api",
  "title": "Build the API",
  "deps": ["schema"],
  "scope": ["src/api"],
  "tier": 2,
  "qa": "inline",
  "brief": "turn the contract into a failing test,\nthen the laziest diff",
}

That records the task in the committed cache, opens a GitHub issue labelled outputty:id:api, and adds a card to the board.

// list_ready — the graph engine over the cache
{ "project": "/abs/path/to/repo" }
// -> { "ids": ["schema"], "tasks": [ { "id": "schema", "status": "open", "tier": 3, "qa": "subagent" } ] }

schema is ready and api is not, because api waits on schema. Close schema (close_task) and api is ready on the very next call — reads are cache-local, with no GitHub indexing lag.

How it works

   MCP tools    ── stdio (bunx, for Claude Code)  ·  http (hono, standalone)
        │  each call carries { project, branch? }
        ▼
   CACHE  .claude/tasks.cache.yaml   ── the authoritative task model + DEPENDENCY GRAPH (committed)
        │  the pure graph engine (ready / schedule / planning) runs over this
        ▼
   Sync targets (two-way, per representable field)
        ├── GitHub Issues (REST)      title · status(open/closed) · id(label) · body-mirror   [primary]
        └── GitHub Projects v2 (GraphQL)   each task-issue → a board card; status → a column   [best-effort]

Authority split. The cache owns the dependency graph — nothing else can hold it. GitHub owns the fields it can represent: an issue closed in the UI wins on the next sync. Issues are primary (a write must land there); Projects is best-effort (a board hiccup is a warning, never a lost task).

The task ↔ issue mapping:

Prose a human writes below that block is preserved across updates.

Kanban board (GitHub Projects v2)

Each task-issue is added to a Projects v2 board and its Status column tracks the task (open → Todo, done → Done). By default the server finds or creates a board named Tasks linked to the repo; point it at an existing board with projectNumber, or turn it off entirely.

Projects v2 needs the token's project scope, which gh does not grant by default — add it once with gh auth refresh -s project. Without it, the board sync is skipped with a warning and the task still lands as an issue (Projects is best-effort).

# .claude/tasks-mcp.config.yaml   (all optional)
projects: true # set false to disable the board
projectNumber: 7 # target an existing board instead of find/create "Tasks"
board: Tasks # the title to find/create when projectNumber is absent

The MCP transport

A tools-only server sends no server-initiated messages. Over stdio it is newline-delimited JSON-RPC; over HTTP the Streamable HTTP transport collapses to one JSON-RPC message in, one JSON reply out — no SSE stream, no session id. Both handle initialize, tools/list, and tools/call (plus ping and the initialized notification). This is why the whole server is just hono + octokit.

Config

Limitations

• Projects sync is best-effort and one-way for now. A card moved on the board is not yet read back into the cache; issue state is the canonical status. Board-to-cache pull is a follow-up.

• The REST issues endpoint is on a deprecation clock (GitHub retires the current version by 2028). Octokit prints a notice; nothing breaks today.

Development

bun test            # graph engine · GitHub Issues + Projects targets (mocked) · service · MCP protocol
bun run dev         # hot-reloading HTTP server

Every target is tested against an in-memory fake, so the suite needs no network and no credentials.