task-graph-mcp

Task Graph MCP 服务

真正有效的 Agent 任务工作流。

让 AI Agent 处理复杂任务时，问题很快就会接踵而至。Agent 会丢失上下文、跳过步骤、忘记协作。Task Graph 通过结构化工作流解决这些问题：用于引导工作的阶段、提供自动指导的提示词、用于确保质量的关卡，以及用于多 Agent 场景的协调原语——这一切都通过 Model Context Protocol 实现。

为什么选择 Task Graph？

问题：你有需要结构化执行的复杂任务。可能是由单个 Agent 分阶段完成，也可能是多个 Agent 并行协作。缺少合适的工作流时，Agent 会失去方向、跳过步骤，产出不一致的结果。

你将获得：

• 结构化工作流 — 阶段（探索、实现、审查、测试）引导 Agent 完成工作。转换提示词会在每个步骤自动提供指导。
• 质量关卡 — 在转换前，要求测试通过、代码提交或审查完成。自动确保符合你的标准。
• 开箱即用的拓扑 — 为单人工作、并行群组、专家接力或分层委派预先构建的工作流。立即开始，之后再自定义。
• 可配置工作流 — 定义自己的状态、阶段、提示词和关卡。适配你的流程，而不是我们的流程。
• 多 Agent 协调 — 建议式文件锁、DAG 依赖关系、原子认领。不再发生冲突或重复工作。
• 节省 Token — 专为大模型上下文限制而设计。查询简洁、往返次数少、输出结构化。
• 内置核算 — 按任务跟踪 Token、成本和时间。准确了解 Agent 的开销。
• 零基础设施 — 使用 WAL 模式的 SQLite。无需运行数据库服务，只需指定一个文件。

功能

功能	描述
任务层级	支持无限嵌套及父子关系
DAG 依赖关系	支持带环检测的类型化边（阻塞、后续、包含）
阶段	对工作类型分类（探索、实现、审查、测试、部署）
工作流	命名的工作流拓扑（单人、群组、接力、分层）
转换提示词	状态／阶段变更时自动为 Agent 提供指导
关卡	状态／阶段转换的退出要求
原子认领	支持限制和基于标签路由的严格锁定
文件协调	提供原因说明和变更轮询的建议式锁
成本跟踪	按任务记录 Token 用量和美元成本
时间跟踪	根据状态转换自动累计时间
实时状态	其他 Agent 可见的实时“当前想法”
全文搜索	通过 FTS5 搜索任务和附件
附件	内联内容、文件引用或媒体存储
Agent 反馈	Agent 间通信，支持分类反馈（取决于配置）
动态叠加层	通过添加／移除叠加层工具，在运行时自定义工作流

快速开始

# Install
cargo install task-graph-mcp

# Add to your MCP client (Claude Code, etc.)

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

# Agent workflow (worker_id auto-generated if omitted)
connect(workflow="swarm", tags=["code"])                 → "bright-lunar-swift-fox"
list_tasks(ready=true, agent="bright-lunar-swift-fox")   → claimable work
claim(worker_id="bright-lunar-swift-fox", task="add-auth")  → you own it
update(..., phase="implement")                           → enter implementation phase
thinking(agent="bright-lunar-swift-fox", thought="Adding JWT...")  → visible to others
update(worker_id="bright-lunar-swift-fox", task="add-auth",
       status="completed",
       attachments=[{type:"commit", content:"abc123"}])  → done

安装

从 crates.io 安装（推荐）

cargo install task-graph-mcp

预构建二进制文件

从 GitHub Releases 下载适用于你平台的最新版本：

平台	下载
Linux（x64）	task-graph-mcp-x86_64-unknown-linux-gnu.tar.gz
macOS（Intel）	task-graph-mcp-x86_64-apple-darwin.tar.gz
macOS（Apple Silicon）	task-graph-mcp-aarch64-apple-darwin.tar.gz
Windows（x64）	task-graph-mcp-x86_64-pc-windows-msvc.zip

解压后将二进制文件放入 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>     Path to configuration file
  -d, --database <FILE>   Path to database file (overrides config)
  -v, --verbose           Enable verbose logging
  -h, --help              Print help
  -V, --version           Print version

配置

完整参考：请参阅 docs/CONFIGURATION.md，了解完整的配置文档，包括工作流、提示词、关卡、角色和标签。

创建 .task-graph/config.yaml：

server:
  db_path: .task-graph/tasks.db
  media_dir: .task-graph/media  # Directory for file attachments
  skills_dir: .task-graph/skills  # Custom skill overrides
  stale_timeout_seconds: 900
  default_format: json  # or markdown

paths:
  style: relative  # or project_prefixed

auto_advance:
  enabled: false        # Auto-transition unblocked tasks
  target_state: ready   # Target state (requires custom state in states config)

状态配置

任务状态可配置。默认状态：pending、working、completed、failed、cancelled。

要添加 ready 状态以实现自动推进：

states:
  initial: pending
  disconnect_state: pending  # State for tasks when owner disconnects (must be untimed)
  blocking_states: [pending, working]
  definitions:
    pending:
      exits: [ready, working, cancelled]
    ready:
      exits: [working, cancelled]
    working:
      exits: [completed, failed, pending]
      timed: true    # Time in this state counts toward 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  # Same-level relationship
      blocks: start        # Blocks claiming the dependent task
    follows:
      display: horizontal
      blocks: start
    contains:
      display: vertical    # Parent-child relationship
      blocks: completion   # Blocks completing the parent
    duplicate:
      display: horizontal
      blocks: none         # Informational only
    see-also:
      display: horizontal
      blocks: none
    relates-to:
      display: horizontal
      blocks: none

属性	值	描述
display	horizontal、vertical	视觉关系（同级与父子级）
blocks	none、start、completion	依赖项阻止的内容

附件配置

预配置的附件键可提供默认 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

属性	值	描述
unknown_key	allow、warn、reject	对未定义附件键的处理方式
definitions.<key>.mime	MIME 类型字符串	此键的默认 MIME 类型
definitions.<key>.mode	append、replace	默认模式（append 保留现有内容，replace 覆盖现有内容）

内置默认值：

键	MIME 类型	模式	用途
commit	text/git.hash	append	Git 提交哈希
checkin	text/p4.changelist	append	Perforce 更改列表
changelist	text/plain	append	已更改的文件
meta	application/json	replace	结构化元数据
note	text/plain	append	常规备注
log	text/plain	append	日志输出
error	text/plain	append	错误消息
output	text/plain	append	命令/工具输出
diff	text/x-diff	append	补丁和差异
plan	text/markdown	replace	计划和规范
result	application/json	replace	结构化结果
context	text/plain	replace	当前上下文/状态

用法：

# MIME and mode auto-filled from config:
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 (overwrites existing meta)

# Explicit values override defaults:
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 工具

Worker 管理

工具	描述
connect(worker_id?, tags?, workflow?, force?, db_path?, media_dir?, log_dir?, config_path?, overlays?: str[])	注册一个 worker。可选的 workflow 用于选择命名工作流（solo、swarm、relay、hierarchical）。返回 worker_id 和活动 paths。
disconnect(worker_id: worker_str, final_status?: status_str = "pending")	注销 worker 并释放所有声明和锁。
list_agents(tags?: str[], file?: filename, task?: task_str, depth?: int, stale_timeout?: int)	按筛选条件列出已连接的 worker。
cleanup_stale(timeout?: int, final_status?: status_str)	清除过期 worker 并释放其声明。
add_overlay(worker_id: str, overlay: str)	为已连接的 worker 添加动态工作流叠加项。
remove_overlay(worker_id: str, overlay: str)	从已连接的 worker 移除工作流叠加项。

任务 CRUD

工具	描述
create(description: str, id?: task_str, parent?: task_str, priority?: int = 5, points?: int, time_estimate_ms?: int, tags?: str[])	创建任务。优先级为 0-10（数值越高越重要）。
create_tree(tree, parent?, child_type?, sibling_type?)	创建嵌套任务树。child_type（默认值："contains"）用于父级→子级依赖，sibling_type 用于同级依赖。
get(task: task_str)	按 ID 获取任务，以及附件元数据和计数。
list_tasks(status?: status_str[], ready?: bool, blocked?: bool, claimed?: bool, owner?: worker_str, parent?: task_str, recursive?: bool, agent?: worker_str, tags_any?: str[], tags_all?: str[], sort_by?: str, sort_order?: str, limit?: int, offset?: int)	按筛选条件查询任务。使用 ready=true 查询可认领的任务。
update(worker_id: worker_str, task: task_str, status?: status_str, phase?: str, assignee?: worker_str, title?: str, description?: str, priority?: int, points?: int, tags?: str[], needed_tags?: str[], wanted_tags?: str[], time_estimate_ms?: int, reason?: str, force?: bool, attachments?: object[])	更新任务。状态或阶段变更会自动管理所有权并触发提示词。添加 attachments 以记录提交或变更列表。
delete(worker_id: worker_str, task: task_str, cascade?: bool, reason?: str, obliterate?: bool, force?: bool)	删除任务。默认软删除；使用 obliterate=true 永久删除。
scan(task: task_str, before?: int, after?: int, above?: int, below?: int)	从多个方向扫描任务图。深度：0=无，N=层级数，-1=全部。
search(query: str, limit?: int = 20, include_attachments?: bool, status_filter?: status_str)	全文搜索（FTS5）。支持短语、prefix*、AND/OR/NOT、title:word。
rename(worker_id: worker_str, task: task_str, new_id: task_str)	在所有引用表中原子性地重命名任务 ID。

任务认领

工具	描述
claim(worker_id: worker_str, task: task_str, force?: bool)	认领任务。如果依赖未满足、已达上限或缺少标签，则会失败。使用 force 强行抢占。

注意：通过 update(status="pending") 释放任务。通过 update(status="completed") 完成任务。状态变更会自动管理所有权。

依赖项

工具	描述
link(from: task_str|task_str[], to: task_str|task_str[], type?: dep_str = "blocks")	创建依赖关系。类型：blocks、follows、contains、duplicate、see-also、relates-to。
unlink(from: task_str|"*", to: task_str|"*", type?: dep_str)	移除依赖关系。使用 * 作为通配符。
relink(prev_from: task_str[], prev_to: task_str[], from: task_str[], to: task_str[], type?: dep_str = "contains")	原子性地移动依赖关系（先取消链接，再建立链接）。

跟踪

工具	描述
thinking(worker_id: worker_str, thought: str, tasks?: task_str[])	广播实时状态。其他工作者可见。刷新心跳。
task_history(task: task_str, states?: status_str[])	获取状态转换历史及时间跟踪信息。
project_history(from?: datetime_str, to?: datetime_str, states?: status_str[], limit?: int = 100)	获取项目范围的历史记录，并按日期范围筛选。
log_metrics(worker_id: worker_str, task: task_str, cost_usd?: float, values?: int[8])	记录指标（聚合）。
get_metrics(task: task_str|task_str[])	获取任务的指标。
give_feedback(message: str, category?: str, sentiment?: str, agent_id?: str, tool_name?: str, task_id?: str)	记录有关工具、工作流或用户体验的反馈。默认启用；超出大小限制（默认：1MB）时会拒绝写入。
list_feedback()	读取反馈 Markdown 文件。

文件协调

工具	描述
mark_file(worker_id: worker_str, file: filename|filename[], task?: task_str, reason?: str)	标记文件，以表明处理意图。仅供参考，不会阻塞操作。
unmark_file(worker_id: worker_str, file?: filename|filename[]|"*", task?: task_str, reason?: str)	移除标记。使用 * 表示全部。
list_marks(files?: filename[], worker_id?: worker_str, task?: task_str)	获取当前文件标记。
mark_updates(worker_id: worker_str)	获取自上次调用以来的标记变更。

附件

工具	描述
attach(task: task_str|task_str[], name: str, content?: str, mime?: mime_str, file?: filename, store_as_file?: bool, mode?: str)	添加附件。使用 file 进行引用，使用 store_as_file 存储媒体文件。
attachments(task: task_str, name?: str, mime?: mime_str)	获取附件元数据。支持名称的 glob 模式。
detach(worker_id: worker_str, task: task_str, name: str, delete_file?: bool)	按名称删除附件。

高级

工具	描述
check_gates(task: task_str)	在状态或阶段转换前检查门槛要求。返回未满足的门槛及其通过／警告／失败状态。
get_advisory(topic?: str, task?: task_str, worker_id?: worker_str)	获取治理建议。未指定主题时：列出所有主题。指定主题时：返回经过模板展开的完整建议内容。
query(sql: str, params?: str[], limit?: int = 100, format?: str)	执行只读 SQL。仅支持 SELECT。需要权限。
get_schema(table?: str, include_sql?: bool)	获取数据库架构。返回表名、列、类型和外键。
get_prompts(status?: str, phase?: str, task?: task_str, worker_id?: worker_str)	获取工作流提示词。不带参数时：列出触发条件。指定状态／阶段时：返回该转换的展开后提示词。
list_workflows()	列出可用的工作流配置（solo、swarm、relay、hierarchical 等）。
list_skills()	列出可用的内置技能及其描述。
get_skill(name: str)	获取内置技能的完整内容。

MCP 资源

URI	描述
query://tasks/all	包含依赖关系的完整任务图
query://tasks/ready	可领取的任务
query://tasks/blocked	因依赖关系而受阻的任务
query://tasks/claimed	所有已领取的任务
query://tasks/agent/{id}	由某个 Agent 负责的任务
query://tasks/tree/{id}	任务及其所有后代任务
query://files/marks	所有文件标记
query://agents/all	已注册的 Agent
query://stats/summary	汇总统计数据
config://current	在一个响应中返回所有配置
config://states	任务状态定义
config://phases	阶段定义
config://dependencies	依赖类型定义
config://tags	标签定义
docs://index	列出所有可用文档文件
docs://search/{query}	对文档进行全文搜索
docs://skills/list	列出可用技能
docs://skills/{name}	获取指定技能的内容
docs://workflows/list	列出可用工作流
docs://workflows/{name}	获取工作流详情
docs://overlays/list	列出可用覆盖层
docs://overlays/{name}	获取覆盖层详情
docs://{path}	指定文档文件的内容

任务树结构

使用 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"
}

树节点字段

字段	描述
title	任务标题（新任务必填）
description	任务描述
id	自定义任务 ID（如果省略，则生成 UUID7）
ref	通过 ID 引用现有任务（设置后会忽略其他字段）
priority	优先级 0-10（默认为 5）
points	故事点数 / 复杂度估算
time_estimate_ms	预计时长（毫秒）
tags	任务分类标签
needed_tags	Agent 必须具备所有这些标签才能认领（AND）
wanted_tags	Agent 必须至少具备其中一个标签才能认领（OR）
children	嵌套的子节点

顶层参数

参数	默认值	描述
tree	必填	任务树的根节点
parent	null	将树根节点附加到现有父任务
child_type	"contains"	父节点到子节点的依赖类型
sibling_type	null	兄弟节点之间的依赖类型（顺序执行为 "follows"，并行执行为 null）

引用现有任务

使用 ref 将现有任务整合到树结构中：

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

基于标签的匹配

Worker 在连接时通过标签声明能力。任务可以要求指定标签，以控制哪些 Worker 可以认领任务。

标签类别示例：

• 模型能力：image-in、audio-out、video-in、code、bulk
• 访问级别：prod-access、admin、external
• 专业领域：rust、python、frontend、database

注意：协调者、审查者、部署者等角色更适合用阶段来表示。

任务要求：

• needed_tags（AND）：Agent 必须具备所有这些标签
• wanted_tags（OR）：Agent 必须至少具备其中一个标签

{
  "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

阶段支持：

• 转换提示词 — 进入或退出阶段时自动提供指导
• 关卡 — 阶段转换前必须满足的要求
• 基于角色的路由 — 在 relay 工作流中，特定专家负责指定阶段

命名工作流

预置的工作流拓扑针对不同的协调模式进行了优化：

工作流	描述	最适合
solo	单个 Agent，完全自主	简单任务、原型开发
swarm	并行通才，基于拉取	高吞吐量、独立任务
relay	顺序协作的专家，交接工作	复杂任务、领域专业知识
hierarchical	负责人 / Worker 委派	大型项目、团队协调
push	基于推送的任务分配拓扑	集中分配、负载均衡
kanban	带有 WIP 限制的看板式任务管理	持续流转、可视化跟踪
sprint	限时迭代规划	Scrum 团队、固定节奏

连接时选择工作流：

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

每种工作流都会提供量身定制的提示词和协调指导。详细模式请参阅 WORKFLOW_TOPOLOGIES.md。

转换提示词

状态或阶段变化时，Agent 会自动收到指导：

# workflows.yaml
states:
  working:
    prompts:
      enter: |
        You are now working on this task.
        From {{current_status}} you can transition to: {{valid_exits}}
      exit: |
        Before leaving:
        - [ ] Attach results
        - [ ] Log costs

提示词支持模板变量：{{current_status}}、{{valid_exits}}、{{current_phase}}、{{valid_phases}}

关卡

关卡是状态或阶段转换前必须满足的要求：

gates:
  status:working:
    - type: gate/tests
      enforcement: warn
      description: "Tests must pass"

附加证据以满足关卡要求：

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

强制级别：allow（提示性）、warn（除非 force=true，否则会阻止操作）、reject（强制阻止）

文件协作

Agent 可以使用带有变更跟踪功能的提示性标记来协调文件编辑：

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") -> sees worker-a's mark
Worker A: unmark_file("worker-a", "src/main.rs", "ready for review")
Worker B: mark_updates("worker-b") -> sees removal with reason
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 — 每个工作进程都会启动自己的服务进程
• 数据库：SQLite，使用 WAL 模式以支持跨进程并发访问
• 部署：单一二进制文件，无外部依赖，可离线运行

与其他方案的比较

	任务图	线性任务列表	自定义数据库
工作流阶段	✓ 内置提示词	✗ 手动跟踪	自行实现
质量关卡	✓ 可配置的强制执行	✗	自行实现
支持多 Agent 安全协作	✓ 原子认领、文件锁	✗ 竞态条件	可能支持，需自行实现
依赖关系跟踪	✓ 支持循环检测的有向无环图	✗ 手动排序	自行实现
原生支持 MCP	✓ 一等支持	✗ 需要封装	✗ 需要封装
Token 统计	✓ 内置	✗	自行实现
是否需要设置	无	无	数据库服务

文档

文档	说明
CONFIGURATION.md	完整的配置参考（config.yaml、工作流、提示词、关卡、标签）
SCHEMA.md	数据库架构和状态机文档
DESIGN.md	架构和设计决策
WORKFLOW_TOPOLOGIES.md	多 Agent 工作流模式（单人、群集、接力、层级）
EXPORT_IMPORT.md	数据导出和导入功能
PROCESSES.md	发布流程、变更日志维护
GATES.md	工作流关卡条件和强制执行
METRICS.md	实验指标定义和 SQL 示例

许可证

Apache 2.0

---

为需要结构化工作流和可靠协作的 AI Agent 而构建。