Task Graph MCP

任务图MCP服务器

实际工作的代理任务工作流。

当你让人工智能代理处理复杂的任务时，事情很快就会出错。代理失去上下文，跳过步骤，忘记协调。任务图通过结构化的工作流解决了这个问题：指导工作的阶段、自动指导的提示、强制质量的门以及多代理场景的协调原语——所有这些都通过模型上下文协议实现。

为什么是任务图？

问题：你有复杂的任务需要结构化执行。可能是单个代理分阶段工作，也可能是多个代理并行协调。如果没有适当的工作流程，代理会失去跟踪、跳过步骤并产生不一致的结果。

你得到了什么:

• 结构化工作流 --阶段（探索、实施、审查、测试）指导代理完成工作。过渡提示在每个步骤提供自动指导。
• 质量门 --要求在转换之前通过测试、提交代码或完成审查。自动执行您的标准。
• 即用型拓扑 --为单人工作、平行集群、专业中继或分层委托预先构建的工作流程。立即开始，稍后自定义。
• 可配置的工作流 --定义自己的状态、阶段、提示和门。匹配你的流程，而不是我们的。
• 多智能体协调 --咨询文件锁、DAG依赖关系、原子声明。不再有冲突或重复工作。
• 代币高效 --专为LLM上下文限制而设计。紧凑的查询、最少的往返、结构化的输出。
• 内置会计 --跟踪每个任务的令牌、成本和时间。确切地知道你的代理人在花什么。
• 零基础设施 --带WAL模式的SQLite。没有要运行的数据库服务器。只需指向一个文件。

特性

快速开始

# 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

预构建二进制文件

从以下网址下载适用于您平台的最新版本 :

提取二进制文件并将其放置在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      Path to configuration file
  -d, --database    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

附件配置

预配置的附件密钥提供默认的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 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工具

工人管理

任务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 （或）：代理人必须至少有一个

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

每个工作流程都提供量身定制的提示和协调指导。看 工作流程_拓扑.md 查看详细图案。

过渡提示

当状态或阶段发生变化时，代理会收到自动指导：

# 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 （硬块）

文件协调

代理可以使用带有更改跟踪的咨询标记来协调文件编辑：

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模式，可跨进程并发访问
• 部署：单个二进制文件，无外部依赖，脱机工作

与替代方案相比

文档

许可证

Apache 2.0

______________________________________________________________________

专为需要结构化工作流程和可靠协调的AI代理而构建。