@outputty/tasks-mcp

outputty のタスクトラッカーを型付きツールとして公開するローカル MCP サーバーです。依存グラフはリポジトリ内のコミット済みキャッシュに格納され、各タスクは GitHub Issue と GitHub Projects ボードに双方向に同期されます。コーディングエージェントは CLI を呼び出す代わりに add_task / list_ready / schedule を呼び出します。

• キャッシュがグラフを所有します。 依存関係は 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 はベストエフォートです（ボードの問題は警告になり、タスクが失われることはありません）。

タスク ↔ 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 はベストエフォートです）。

# .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 トランスポートが、1つの JSON-RPC メッセージの入力に対して1つの JSON 応答を返す形に集約されます。SSE ストリームやセッション ID はありません。どちらも initialize、tools/list、tools/call（および ping と initialized 通知）を処理します。これが、サーバー全体が単なる hono + octokit で構成されている理由です。

設定

制限事項

• Projects の同期は現時点ではベストエフォートかつ一方向です。 ボード上で移動されたカードはまだキャッシュに読み戻されません。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

すべてのターゲットはインメモリのフェイクに対してテストされるため、テストスイートはネットワークも認証情報も必要としません。