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代理而构建。