@outputty/tasks-mcp

Локальный MCP-сервер, который предоставляет трекер задач outputty в виде типизированных инструментов. Граф зависимостей хранится в закоммиченном кэше в вашем репозитории; каждая задача двусторонне синхронизируется с GitHub Issue и на доску GitHub Projects. Программный агент вызывает add_task / list_ready / schedule вместо обращения к CLI.

• Кэш владеет графом. Зависимости не могут жить в GitHub Issue, поэтому авторитетный граф задач — это закоммиченный файл (.claude/tasks.cache.yaml). Он путешествует вместе с репозиторием и переживает свежий клон.

• Бэкенды — это цели синхронизации. GitHub Issues содержат запись для людей (заголовок, открыто/закрыто, зеркало тела); GitHub Projects даёт канбан-вид. Чтения идут из кэша, поэтому никогда не ждут GitHub.

• Ваши существующие учётные данные. GITHUB_TOKEN или то, что уже сохранено через gh auth login. Никакого нового входа.

Requirements

Related MCP server: mcp-server-tasktracker

Install

Без клонирования. Добавьте сервер в .mcp.json вашего проекта, и Claude Code запустит его по требованию через bunx:

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

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

Каждый инструмент принимает project — абсолютный путь к репозиторию, с которым он работает, — потому что у сервера нет собственной рабочей директории. При первой записи в репозиторий, который сервер ещё не видел, автоматически создаются метка outputty и (если включено) доска 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",
}

Это записывает задачу в закоммиченный кэш, открывает GitHub issue с меткой outputty:id:api и добавляет карточку на доску.

// 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 готова, а api — нет, потому что api ждёт schema. Закройте schema (close_task), и api станет готовой при самом следующем вызове — чтения локальны для кэша, без задержки индексации GitHub.

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]

Разделение полномочий. Кэш владеет графом зависимостей — никто другой не может его хранить. GitHub владеет полями, которые может представлять: issue, закрытая в интерфейсе, побеждает при следующем sync. Issues первичны (запись должна попасть туда); Projects — best-effort (сбой доски — предупреждение, но не потерянная задача).

Соответствие задачи и issue:

Проза, которую человек пишет ниже этого блока, сохраняется при обновлениях.

Kanban board (GitHub Projects v2)

Каждая task-issue добавляется на доску Projects v2, и её колонка Status отслеживает задачу (open → Todo, done → Done). По умолчанию сервер находит или создаёт доску Tasks, связанную с репозиторием; укажите существующую доску через projectNumber или полностью отключите её.

Projects v2 требует область project у токена, которую gh не выдаёт по умолчанию — добавьте её один раз через gh auth refresh -s project. Без неё синхронизация доски пропускается с предупреждением, и задача всё равно попадает как issue (Projects — 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

Сервер, работающий только с инструментами, не отправляет сообщений, инициированных сервером. По stdio это JSON-RPC с разделителями строк; по HTTP транспорт Streamable HTTP сводится к одному входящему JSON-RPC сообщению и одному исходящему JSON-ответу — без SSE-потока и без идентификатора сессии. Оба обрабатывают initialize, tools/list и tools/call (а также ping и уведомление initialized). Именно поэтому весь сервер — это просто hono + octokit.

Config

Limitations

• Синхронизация Projects пока best-effort и односторонняя. Карточка, перемещённая на доске, ещё не считывается обратно в кэш; состояние issue — канонический статус. Тянуть доску в кэш — последующая задача.

• REST-эндпоинт issues находится на таймере устаревания (GitHub выведет текущую версию из эксплуатации к 2028 году). Octokit печатает уведомление; сегодня ничего не ломается.

Development

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

Каждая цель тестируется против фейка в памяти, поэтому набору тестов не нужны сеть и учётные данные.