Task Graph MCP

🚀 Task Graph MCP Server

実際に機能するエージェントタスクワークフロー

AIエージェントが複雑なタスクを実行する際には、すぐに問題が発生します。エージェントがコンテキストを失い、ステップをスキップし、調整を忘れることがあります。Task Graphは、構造化されたワークフローによってこれらの問題を解決します。作業をガイドするフェーズ、自動ガイダンスのためのプロンプト、品質を保証するゲート、およびマルチエージェントシナリオのための調整プリミティブを、すべてModel Context Protocolを通じて提供します。

🚀 クイックスタート

インストール

# インストール
cargo install task-graph-mcp

# MCPクライアント（Claude Codeなど）に追加

{
  "mcpServers": {
    "task-graph": {
      "command": "task-graph-mcp"
    }
  }
}

エージェントワークフロー（worker_idを省略すると自動生成）

connect(workflow="swarm", tags=["code"])                 → "bright-lunar-swift-fox"
list_tasks(ready=true, agent="bright-lunar-swift-fox")   → 請求可能な作業
claim(worker_id="bright-lunar-swift-fox", task="add-auth")  → タスクを取得
update(..., phase="implement")                           → 実装フェーズに入る
thinking(agent="bright-lunar-swift-fox", thought="Adding JWT...")  → 他のエージェントに表示される
update(worker_id="bright-lunar-swift-fox", task="add-auth",
       status="completed",
       attachments=[{type:"commit", content:"abc123"}])  → 完了

✨ 主な機能

なぜTask Graphを選ぶのか？

問題点：複雑なタスクを構造化された実行方法で処理する必要があります。単一のエージェントがフェーズを経て作業する場合や、複数のエージェントが並行して調整する場合があります。適切なワークフローがないと、エージェントは追跡を失い、ステップをスキップし、一貫性のない結果を生み出します。

得られるもの：

• 構造化されたワークフロー — フェーズ（探索、実装、レビュー、テスト）がエージェントの作業をガイドします。遷移プロンプトは各ステップで自動的なガイダンスを提供します。
• 品質ゲート — 遷移前にテストを通過し、コードをコミットし、またはレビューを完了する必要があります。自動的に標準を強制します。
• すぐに使えるトポロジー — 単独作業、並列スワーム、専門家リレー、または階層的な委任のための事前構築されたワークフローがあります。すぐに開始でき、後でカスタマイズできます。
• 設定可能なワークフロー — 独自の状態、フェーズ、プロンプト、およびゲートを定義できます。あなたのプロセスに合わせることができます。
• マルチエージェント調整 — アドバイザリファイルロック、DAG依存関係、アトミッククレームがあります。競合や重複作業がなくなります。
• トークン効率 — LLMのコンテキスト制限に合わせて設計されています。コンパクトなクエリ、最小限の往復、構造化された出力が可能です。
• 組み込みの会計機能 — タスクごとのトークン、コスト、および時間を追跡します。エージェントがどれだけ費やしているかを正確に把握できます。
• ゼロインフラストラクチャ — WALモードのSQLiteを使用しています。データベースサーバーを実行する必要がありません。単にファイルを指定するだけです。

機能一覧

📦 インストール

crates.ioからのインストール（推奨）

cargo install task-graph-mcp

事前ビルド済みバイナリのインストール

GitHub Releasesからあなたのプラットフォーム用の最新リリースをダウンロードします。

バイナリを抽出し、PATHに配置します。

ソースからのインストール

git clone https://github.com/Oortonaut/task-graph-mcp.git
cd task-graph-mcp
cargo build --release

バイナリはtarget/release/task-graph-mcpに配置されます。

💻 使用例

MCPサーバーとしての使用

MCPクライアントの設定に追加します。

{
  "mcpServers": {
    "task-graph": {
      "command": "task-graph-mcp",
      "args": []
    }
  }
}

CLIオプション

task-graph-mcp [OPTIONS]

Options:
  -c, --config <FILE>     設定ファイルのパス
  -d, --database <FILE>   データベースファイルのパス（設定を上書き）
  -v, --verbose           詳細なログを有効にする
  -h, --help              ヘルプを表示
  -V, --version           バージョンを表示

📚 ドキュメント

設定

完全なリファレンス：ワークフロー、プロンプト、ゲート、ロール、およびタグを含む完全な設定ドキュメントについては、docs/CONFIGURATION.mdを参照してください。

.task-graph/config.yamlを作成します。

server:
  db_path: .task-graph/tasks.db
  media_dir: .task-graph/media  # ファイル添付用のディレクトリ
  skills_dir: .task-graph/skills  # カスタムスキルの上書き
  stale_timeout_seconds: 900
  default_format: json  # またはmarkdown

paths:
  style: relative  # またはproject_prefixed

auto_advance:
  enabled: false        # ブロックされていないタスクを自動遷移させる
  target_state: ready   # ターゲット状態（states設定でカスタム状態が必要）

状態設定

タスクの状態は設定可能です。デフォルトの状態はpending、working、completed、failed、cancelledです。

自動進行のためのready状態を追加するには：

states:
  initial: pending
  disconnect_state: pending  # 所有者が切断したときのタスクの状態（タイム制限なしでなければならない）
  blocking_states: [pending, working]
  definitions:
    pending:
      exits: [ready, working, cancelled]
    ready:
      exits: [working, cancelled]
    working:
      exits: [completed, failed, pending]
      timed: true    # この状態の時間はtime_actual_msにカウントされる
    completed:
      exits: []
    failed:
      exits: [pending]
    cancelled:
      exits: []

auto_advance:
  enabled: true
  target_state: ready

状態定義の完全なドキュメントについては、SCHEMA.mdを参照してください。

依存関係設定

依存関係のタイプは、タスク同士の関係を定義します。デフォルトのタイプはblocks、follows、contains、duplicate、see-also、relates-toです。

dependencies:
  definitions:
    blocks:
      display: horizontal  # 同じレベルの関係
      blocks: start        # 依存タスクのクレームをブロックする
    follows:
      display: horizontal
      blocks: start
    contains:
      display: vertical    # 親子関係
      blocks: completion   # 親の完了をブロックする
    duplicate:
      display: horizontal
      blocks: none         # 情報のみ
    see-also:
      display: horizontal
      blocks: none
    relates-to:
      display: horizontal
      blocks: none

添付ファイル設定

事前構成された添付キーは、デフォルトのMIMEタイプとモードを提供し、一般的なコンテンツタイプを添付する際のボイラープレートを削減します。

attachments:
  unknown_key: warn  # allow | warn (default) | reject
  definitions:
    commit:
      mime: text/git.hash
      mode: append
    checkin:
      mime: text/p4.changelist
      mode: append
    meta:
      mime: application/json
      mode: replace
    note:
      mime: text/plain
      mode: append

組み込みのデフォルト：

使用方法：

# MIMEとモードは設定から自動入力されます。
attach(task="123", name="commit", content="abc1234")
# → mime=text/git.hash, mode=append

attach(task="123", name="meta", content='{"v":1}')
# → mime=application/json, mode=replace (既存のmetaを上書き)

# 明示的な値はデフォルトを上書きします。
attach(task="123", name="commit", mime="text/plain", content="override")

環境変数：

• TASK_GRAPH_CONFIG_PATH：設定ファイルのパス（.task-graph/config.yamlより優先）
• TASK_GRAPH_DB_PATH：データベースファイルのパス（設定ファイルがない場合のフォールバック）
• TASK_GRAPH_MEDIA_DIR：ファイル添付用のメディアディレクトリ（設定ファイルがない場合のフォールバック）
• TASK_GRAPH_LOG_DIR：ログディレクトリのパス（設定ファイルがない場合のフォールバック）

MCPツール

ワーカー管理

タスクCRUD

タスククレーム

注意：update(status="pending")で解放し、update(status="completed")で完了します。ステータスの変更は自動的に所有権を管理します。

依存関係

追跡

ファイル調整

添付ファイル

高度な機能

MCPリソース

タスクツリー構造

create_treeを使用して階層的なタスクを作成します。

{
  "tree": {
    "title": "Implement auth",
    "children": [
      { "title": "Design schema" },
      { "title": "Write migrations" },
      { "title": "Implement endpoints", "children": [
        { "title": "Login endpoint" },
        { "title": "Logout endpoint" },
        { "title": "Refresh endpoint" }
      ]},
      { "title": "Write tests" }
    ]
  },
  "sibling_type": "follows"
}

ツリーノードフィールド

トップレベルパラメータ

既存のタスクを参照する

refを使用して既存のタスクをツリー構造に統合します。

{
  "tree": {
    "title": "Sprint 5",
    "children": [
      { "title": "New feature" },
      { "ref": "existing-task-id" },
      { "title": "Another task" }
    ]
  },
  "sibling_type": "follows"
}

タグベースのアフィニティ

ワーカーは接続時にタグを介して機能を宣言します。タスクは特定のタグを要求することで、どのワーカーがタスクを請求できるかを制御できます。

タグカテゴリの例：

• モデル機能：image-in、audio-out、video-in、code、bulk
• アクセスレベル：prod-access、admin、external
• 専門分野：rust、python、frontend、database

注意: コーディネーター/レビューアー/デプロイヤーなどのロールは、フェーズを使用してより適切に表現できます。

タスク要件：

• needed_tags (AND)：エージェントはすべてのタグを持っている必要があります。
• wanted_tags (OR)：エージェントは少なくとも1つのタグを持っている必要があります。

{
  "title": "Analyze screenshot and generate code",
  "needed_tags": ["image-in", "code"],
  "wanted_tags": ["bulk"]
}

{
  "title": "Deploy to production",
  "phase": "deploy",
  "needed_tags": ["prod-access"],
  "wanted_tags": ["aws", "gcp"]
}

ワークフローとフェーズ

フェーズ

タスクはphaseを持つことで、実行中の作業のタイプを分類できます。

{
  "title": "Add authentication",
  "phase": "implement"
}

組み込みのフェーズ：explore、implement、review、test、security、deploy、triage、diagnose、design、plan、doc、integrate、monitor、optimize

フェーズによって可能になること：

• 遷移プロンプト — フェーズに入る/出るときの自動ガイダンス
• ゲート — フェーズ遷移前に満たす必要がある要件
• ロールベースのルーティング — リレーワークフローでは、専門家が特定のフェーズを担当

名前付きワークフロー

事前構築されたワークフロートポロジーは、さまざまな調整パターンに最適化されています。

接続時にワークフローを選択します。

connect(worker_id="agent-1", workflow="swarm")

各ワークフローは、カスタマイズされたプロンプトと調整ガイダンスを提供します。詳細なパターンについては、WORKFLOW_TOPOLOGIES.mdを参照してください。

遷移プロンプト

エージェントはステータスまたはフェーズが変更されると自動的なガイダンスを受け取ります。

# workflows.yaml
states:
  working:
    prompts:
      enter: |
        あなたは現在このタスクに取り組んでいます。
        {{current_status}}から{{valid_exits}}に遷移できます。
      exit: |
        離れる前に：
        - [ ] 結果を添付する
        - [ ] コストを記録する

プロンプトはテンプレート変数をサポートします：{{current_status}}、{{valid_exits}}、{{current_phase}}、{{valid_phases}}

ゲート

ゲートは、ステータスまたはフェーズ遷移前に満たす必要がある要件です。

gates:
  status:working:
    - type: gate/tests
      enforcement: warn
      description: "テストを通過する必要があります"

ゲートを満たすには、証拠を添付します。

attach(task="123", type="gate/tests", content="All tests passing")

エンフォースメントレベル：allow（アドバイザリ）、warn（force=trueでない限りブロック）、reject（ハードブロック）

ファイル調整

エージェントはアドバイザリマークと変更追跡を使用してファイル編集を調整できます。

Worker A: connect() -> "worker-a"
Worker A: mark_file("worker-a", "src/main.rs", "refactoring")
Worker B: connect() -> "worker-b"
Worker B: mark_updates("worker-b") -> worker-aのマークを確認
Worker A: unmark_file("worker-a", "src/main.rs", "ready for review")
Worker B: mark_updates("worker-b") -> 理由付きでマークの削除を確認
Worker B: mark_file("worker-b", "src/main.rs", "adding tests")

アーキテクチャ

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Agent A    │     │  Agent B    │     │  Agent C    │
│  (Claude)   │     │  (GPT-4)    │     │  (Worker)   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │ stdio             │ stdio             │ stdio
       ▼                   ▼                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ task-graph  │     │ task-graph  │     │ task-graph  │
│    MCP      │     │    MCP      │     │    MCP      │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           ▼
                  ┌─────────────────┐
                  │   SQLite + WAL  │
                  │  .task-graph/   │
                  │    tasks.db     │
                  └─────────────────┘

• トランスポート：Stdio — 各ワーカーは独自のサーバープロセスを起動します。
• データベース：WALモードのSQLiteを使用して、プロセス間での同時アクセスを可能にします。
• デプロイメント：単一のバイナリ、外部依存関係なし、オフラインでも動作します。

他のソリューションとの比較

ドキュメント一覧

📄 ライセンス

Apache 2.0

構造化されたワークフローと信頼性の高い調整が必要なAIエージェント向けに構築されています。