Task Graph MCP

🚀 任務圖MCP服務器

真正有效的代理任務工作流。

當你讓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"}])  → 任務完成

✨ 主要特性

為何選擇任務圖？

問題所在：你有需要結構化執行的複雜任務。可能是單個代理按階段工作，也可能是多個代理並行協調。如果沒有合適的工作流，代理會迷失方向、跳過步驟，導致結果不一致。

你將獲得：

• 結構化工作流 —— 階段（探索、實現、審查、測試）引導代理完成工作。過渡提示在每個步驟提供自動指導。
• 質量關卡 —— 要求測試通過、代碼提交或審查完成後才能進行過渡。自動執行你的標準。
• 即用型拓撲結構 —— 為單人工作、並行群體、專家接力或分層委派預構建的工作流。立即開始，後續自定義。
• 可配置工作流 —— 定義你自己的狀態、階段、提示和關卡。匹配你的流程，而非我們的。
• 多代理協調 —— 諮詢文件鎖、有向無環圖（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]

選項:
  -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   # 目標狀態（需要在狀態配置中自定義狀態）

狀態配置

任務狀態是可配置的。默認狀態為：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 (默認) | 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 (覆蓋現有元數據)

# 顯式值覆蓋默認值：
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）：代理必須至少擁有其中一個標籤。

{
  "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（硬阻塞）

文件協調

代理可以使用帶有更改跟蹤的諮詢標記來協調文件編輯：

工作者A: connect() -> "worker-a"
工作者A: mark_file("worker-a", "src/main.rs", "refactoring")
工作者B: connect() -> "worker-b"
工作者B: mark_updates("worker-b") -> 看到工作者A的標記
工作者A: unmark_file("worker-a", "src/main.rs", "ready for review")
工作者B: mark_updates("worker-b") -> 看到標記移除及原因
工作者B: mark_file("worker-b", "src/main.rs", "adding tests")

架構

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  代理A      │     │  代理B      │     │  代理C      │
│  (Claude)   │     │  (GPT-4)    │     │  (工作者)   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │ 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代理而構建。