@outputty/tasks-mcp

Un servidor MCP local que expone el rastreador de tareas de outputty como herramientas tipadas. El grafo de dependencias vive en una caché confirmada en tu repositorio; cada tarea se sincroniza bidireccionalmente con una incidencia de GitHub y con un tablero de GitHub Projects. Un agente de codificación llama a add_task / list_ready / schedule en lugar de recurrir a una CLI.

• La caché es dueña del grafo. Las dependencias no pueden vivir en una incidencia de GitHub, por lo que el grafo de tareas autoritativo es un archivo confirmado (.claude/tasks.cache.yaml). Viaja con el repositorio y sobrevive a un clon nuevo.

• Los backends son destinos de sincronización. Las incidencias de GitHub contienen el registro orientado a personas (título, abierto/cerrado, un espejo del cuerpo); GitHub Projects ofrece una vista kanban. Las lecturas provienen de la caché, por lo que nunca esperan a GitHub.

• Tus credenciales existentes. GITHUB_TOKEN, o lo que gh auth login ya haya guardado. Sin nuevo inicio de sesión.

Requisitos

Related MCP server: mcp-server-tasktracker

Instalación

Sin clonar. Añade el servidor al .mcp.json de tu proyecto y Claude Code lo lanza bajo demanda con bunx:

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

Eso ejecuta el transporte stdio. Para una instancia compartida de larga duración, ejecuta el servidor HTTP en su lugar:

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

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

Qué hacen las herramientas

Cada herramienta recibe project, la ruta absoluta al repositorio sobre el que actúa, porque el servidor no tiene un directorio de trabajo propio. La primera escritura en un repositorio que no ha visto crea automáticamente la etiqueta outputty y (si está habilitado) el tablero de Projects.

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

Eso registra la tarea en la caché confirmada, abre una incidencia de GitHub etiquetada outputty:id:api y añade una tarjeta al tablero.

// 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 está lista y api no, porque api espera a schema. Cierra schema (close_task) y api estará lista en la siguiente llamada: las lecturas son locales a la caché, sin retraso de indexación de GitHub.

Cómo funciona

   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]

División de autoridad. La caché es dueña del grafo de dependencias: nada más puede contenerlo. GitHub es dueño de los campos que puede representar: una incidencia cerrada en la interfaz gana en el siguiente sync. Las incidencias son la fuente principal (una escritura debe aterrizar allí); Projects es de mejor esfuerzo (un contratiempo del tablero es una advertencia, nunca una tarea perdida).

Correspondencia tarea ↔ incidencia:

La prosa que una persona escribe debajo de ese bloque se conserva a lo largo de las actualizaciones.

Tablero Kanban (GitHub Projects v2)

Cada tarea-incidencia se añade a un tablero de Projects v2 y su columna Status hace el seguimiento de la tarea (open → Todo, done → Done). Por defecto, el servidor encuentra o crea un tablero llamado Tasks vinculado al repositorio; apúntalo a un tablero existente con projectNumber, o desactívalo por completo.

Projects v2 necesita el alcance project del token, que gh no concede por defecto: añádelo una vez con gh auth refresh -s project. Sin él, la sincronización del tablero se omite con una advertencia y la tarea sigue creándose como incidencia (Projects es de mejor esfuerzo).

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

El transporte MCP

Un servidor solo de herramientas no envía mensajes iniciados por el servidor. Por stdio es JSON-RPC delimitado por nuevas líneas; por HTTP, el transporte HTTP Streamable se reduce a un mensaje JSON-RPC de entrada y una respuesta JSON de salida: sin flujo SSE, sin id de sesión. Ambos manejan initialize, tools/list y tools/call (además de ping y la notificación initialized). Por eso todo el servidor es solo hono + octokit.

Configuración

Limitaciones

• La sincronización de Projects es de mejor esfuerzo y unidireccional por ahora. Una tarjeta movida en el tablero aún no se lee de vuelta en la caché; el estado de la incidencia es el estado canónico. La extracción del tablero a la caché es una tarea pendiente.

• El endpoint REST de incidencias está en proceso de deprecación (GitHub retira la versión actual para 2028). Octokit imprime un aviso; hoy no se rompe nada.

Desarrollo

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

Cada objetivo se prueba contra un fake en memoria, por lo que la suite no necesita red ni credenciales.