@outputty/tasks-mcp

Ein lokaler MCP-Server, der den Aufgaben-Tracker von outputty als typisierte Tools bereitstellt. Der Abhängigkeitsgraph lebt in einem committeten Cache in deinem Repository; jede Aufgabe wird bidirektional mit einem GitHub-Issue und einem GitHub-Projects-Board synchronisiert. Ein Coding-Agent ruft add_task / list_ready / schedule auf, anstatt eine CLI zu bemühen.

• Der Cache besitzt den Graphen. Abhängigkeiten können nicht in einem GitHub-Issue leben, daher ist der maßgebliche Aufgaben-Graph eine committete Datei (.claude/tasks.cache.yaml). Sie reist mit dem Repository und überlebt einen frischen Klon.

• Backends sind Synchronisationsziele. GitHub-Issues tragen den menschenlesbaren Datensatz (Titel, offen/geschlossen, ein Body-Spiegel); GitHub Projects bietet eine Kanban-Ansicht. Lesezugriffe kommen aus dem Cache, warten also nie auf GitHub.

• Deine vorhandenen Anmeldedaten. GITHUB_TOKEN oder was auch immer gh auth login bereits gespeichert hat. Kein neuer Login.

Voraussetzungen

Related MCP server: mcp-server-tasktracker

Installation

Kein Klon. Füge den Server zur .mcp.json deines Projekts hinzu, und Claude Code startet ihn bei Bedarf mit bunx:

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

Das nutzt den stdio-Transport. Für eine langlebige gemeinsame Instanz starte stattdessen den HTTP-Server:

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

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

Was die Tools tun

Jedes Tool nimmt project entgegen — den absoluten Pfad zu dem Repository, auf das es wirkt —, weil der Server kein eigenes Arbeitsverzeichnis hat. Der erste Schreibzugriff auf ein ihm unbekanntes Repository richtet das Label outputty und (falls aktiviert) das Projects-Board automatisch ein.

// 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",
}

Das erfasst die Aufgabe im committeten Cache, öffnet ein GitHub-Issue mit dem Label outputty:id:api und fügt dem Board eine Karte hinzu.

// 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 ist bereit und api nicht, weil api auf schema wartet. Schließe schema (close_task), und api ist bereits beim nächsten Aufruf bereit — Lesezugriffe sind cache-lokal, ohne GitHub-Indizierungsverzögerung.

So funktioniert es

   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]

Aufteilung der Zuständigkeiten. Der Cache besitzt den Abhängigkeitsgraphen — nichts anderes kann ihn halten. GitHub besitzt die Felder, die es darstellen kann: Ein in der UI geschlossenes Issue gewinnt beim nächsten sync. Issues sind primär (ein Schreibvorgang muss dort ankommen); Projects ist Best-Effort (ein Board-Aussetzer ist eine Warnung, niemals eine verlorene Aufgabe).

Die Zuordnung Aufgabe ↔ Issue:

Text, den ein Mensch unterhalb dieses Blocks schreibt, bleibt über Aktualisierungen hinweg erhalten.

Kanban-Board (GitHub Projects v2)

Jede Task-Issue wird zu einem Projects-v2-Board hinzugefügt, und die Spalte Status verfolgt die Aufgabe (open → Todo, done → Done). Standardmäßig findet oder erstellt der Server ein Board namens Tasks, das mit dem Repository verknüpft ist; du kannst den Server mit projectNumber auf ein vorhandenes Board ausrichten oder ganz deaktivieren.

Projects v2 benötigt den project-Scope des Tokens, den gh standardmäßig nicht gewährt — füge ihn einmal mit gh auth refresh -s project hinzu. Ohne diesen Scope wird die Board-Synchronisierung mit einer Warnung übersprungen, und die Aufgabe landet trotzdem als Issue (Projects ist 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

Der MCP-Transport

Ein reiner Tools-Server sendet keine vom Server initiierten Nachrichten. Über stdio ist es zeilengetrenntes JSON-RPC; über HTTP reduziert sich der Streamable-HTTP-Transport auf eine JSON-RPC-Nachricht rein, eine JSON-Antwort raus — kein SSE-Stream, keine Session-ID. Beide behandeln initialize, tools/list und tools/call (plus ping und die initialized-Benachrichtigung). Genau deshalb besteht der gesamte Server nur aus hono + octokit.

Konfiguration

Einschränkungen

• Die Projects-Synchronisierung ist derzeit Best-Effort und unidirektional. Eine auf dem Board verschobene Karte wird noch nicht zurück in den Cache gelesen; der Issue-Status ist der maßgebliche Status. Das Abrufen vom Board in den Cache ist ein Folgeschritt.

• Der REST-Issues-Endpunkt hat ein Ablaufdatum (GitHub stellt die aktuelle Version bis 2028 ein). Octokit gibt einen Hinweis aus; heute bricht nichts.

Entwicklung

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

Jedes Ziel wird gegen einen In-Memory-Fake getestet, daher benötigt die Suite kein Netzwerk und keine Anmeldedaten.