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

• 캐시가 그래프를 소유합니다. 의존성은 GitHub Issue에 있을 수 없으므로, 권위 있는 작업 그래프는 커밋된 파일(.claude/tasks.cache.yaml)입니다. 이 파일은 저장소와 함께 이동하며 새 클론에서도 유지됩니다.

• 백엔드는 동기화 대상입니다. GitHub Issues는 사람이 보는 기록(제목, 열림/닫힘, 본문 미러)을 담고, GitHub Projects는 칸반 뷰를 제공합니다. 읽기는 캐시에서 오기 때문에 GitHub를 기다리지 않습니다.

• 기존 자격 증명을 사용합니다. GITHUB_TOKEN 또는 gh auth login이 이미 저장한 것을 사용합니다. 새 로그인이 필요 없습니다.

요구 사항

Related MCP server: mcp-server-tasktracker

설치

클론이 필요 없습니다. 서버를 프로젝트의 .mcp.json에 추가하면 Claude Code가 bunx로 필요할 때 실행합니다:

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

이것은 stdio 전송을 실행합니다. 오래 실행되는 공유 인스턴스가 필요하면 대신 HTTP 서버를 실행하세요:

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

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

도구가 하는 일

모든 도구는 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",
}

그러면 커밋된 캐시에 작업이 기록되고, outputty:id:api 라벨이 붙은 GitHub issue가 열리며, 보드에 카드가 추가됩니다.

// 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 인덱싱 지연이 없습니다.

작동 방식

   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는 표현할 수 있는 필드를 소유합니다. UI에서 닫힌 issue는 다음 sync에서 우선합니다. Issues가 기본입니다(쓰기는 반드시 거기에 반영되어야 함). Projects는 최선 노력(best-effort)입니다(보드 문제는 경고일 뿐 작업이 손실되지는 않습니다).

작업 ↔ issue 매핑:

사람이 해당 블록 아래에 작성한 일반 텍스트는 업데이트 시에도 보존됩니다.

칸반 보드 (GitHub Projects v2)

각 작업-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

MCP 전송

도구 전용 서버는 서버 시작 메시지를 보내지 않습니다. stdio에서는 줄바꿈으로 구분된 JSON-RPC를 사용하고, HTTP에서는 Streamable HTTP 전송이 하나의 JSON-RPC 메시지 입력과 하나의 JSON 응답 출력으로 축소됩니다. SSE 스트림이나 세션 ID가 없습니다. 둘 다 initialize, tools/list, tools/call을 처리합니다(그리고 ping 및 initialized 알림도). 이것이 서버 전체가 hono + octokit만으로 구성된 이유입니다.

구성

제한 사항

• Projects 동기화는 현재로서는 best-effort이며 단방향입니다. 보드에서 이동된 카드는 아직 캐시로 다시 읽히지 않습니다. issue 상태가 정식 상태입니다. 보드에서 캐시로의 풀은 후속 작업입니다.

• REST issues 엔드포인트는 폐지 예정입니다 (GitHub는 현재 버전을 2028년까지 지원 종료). Octokit이 공지를 출력하지만 지금은 아무것도 깨지지 않습니다.

개발

모든 대상은 인메모리 페이크로 테스트되므로 테스트 스위트는 네트워크와 자격 증명이 필요 없습니다.

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