Task Graph Mcp

Task Graph MCP Server

Agent task workflows that actually work.

When you have AI agents working on complex tasks, things go wrong fast. Agents lose context, skip steps, forget to coordinate. Task Graph solves this with structured workflows: phases to guide work, prompts for automatic guidance, gates to enforce quality, and coordination primitives for multi-agent scenarios—all through the Model Context Protocol.

Why Task Graph?

The problem: You've got complex tasks that need structured execution. Maybe a single agent working through phases, or multiple agents coordinating in parallel. Without proper workflows, agents lose track, skip steps, and produce inconsistent results.

What you get:

• Structured workflows — Phases (explore, implement, review, test) guide agents through work. Transition prompts provide automatic guidance at each step.
• Quality gates — Require tests to pass, code to be committed, or reviews to complete before transitions. Enforce your standards automatically.
• Ready-to-use topologies — Pre-built workflows for solo work, parallel swarms, specialist relays, or hierarchical delegation. Start immediately, customize later.
• Configurable workflows — Define your own states, phases, prompts, and gates. Match your process, not ours.
• Multi-agent coordination — Advisory file locks, DAG dependencies, atomic claiming. No more conflicts or duplicate work.
• Token-efficient — Designed for LLM context limits. Compact queries, minimal round-trips, structured outputs.
• Built-in accounting — Track tokens, cost, and time per task. Know exactly what your agents are spending.
• Zero infrastructure — SQLite with WAL mode. No database server to run. Just point at a file.

Features

| Feature | Description | |---------|-------------| | Task Hierarchy | Unlimited nesting with parent/child relationships | | DAG Dependencies | Typed edges (blocks, follows, contains) with cycle detection | | Phases | Categorize work type (explore, implement, review, test, deploy) | | Workflows | Named workflow topologies (solo, swarm, relay, hierarchical) | | Transition Prompts | Automatic agent guidance on status/phase changes | | Gates | Exit requirements for status/phase transitions | | Atomic Claiming | Strict locking with limits and tag-based routing | | File Coordination | Advisory locks with reasons and change polling | | Cost Tracking | Token usage and USD cost per task | | Time Tracking | Automatic accumulation from state transitions | | Live Status | Real-time "current thought" visible to other agents | | Full-text Search | FTS5-powered search across tasks and attachments | | Attachments | Inline content, file references, or media storage | | Agent Feedback | Inter-agent communication with categorized feedback (conditional on config) | | Dynamic Overlays | Runtime workflow customization via add/remove overlay tools |

Quick Start

# 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

Installation

From crates.io (Recommended)

cargo install task-graph-mcp

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

| Platform | Download | |----------|----------| | 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 |

Extract and place the binary in your PATH.

From Source

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

The binary will be at target/release/task-graph-mcp.

Usage

As an MCP Server

Add to your MCP client configuration:

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

CLI Options

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

Configuration

> Full reference: See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for complete configuration documentation including workflows, prompts, gates, roles, and tags.

Create .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)

States Configuration

Task states are configurable. Default states: pending, working, completed, failed, cancelled.

To add a ready state for auto-advance:

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

See [SCHEMA.md](SCHEMA.md#states-configuration) for full documentation on state definitions.

Dependencies Configuration

Dependency types define how tasks relate to each other. Default types: 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

| Property | Values | Description | |----------|--------|-------------| | display | horizontal, vertical | Visual relationship (same-level vs parent-child) | | blocks | none, start, completion | What the dependency blocks |

Attachments Configuration

Preconfigured attachment keys provide default MIME types and modes, reducing boilerplate when attaching common content types.

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

| Property | Values | Description | |----------|--------|-------------| | unknown_key | allow, warn, reject | Behavior for undefined attachment keys | | definitions..mime | MIME type string | Default MIME type for this key | | definitions..mode | append, replace | Default mode (append keeps existing, replace overwrites) |

Built-in defaults:

| Key | MIME Type | Mode | Use Case | |-----|-----------|------|----------| | commit | text/git.hash | append | Git commit hashes | | checkin | text/p4.changelist | append | Perforce changelists | | changelist | text/plain | append | Files changed | | meta | application/json | replace | Structured metadata | | note | text/plain | append | General notes | | log | text/plain | append | Log output | | error | text/plain | append | Error messages | | output | text/plain | append | Command/tool output | | diff | text/x-diff | append | Patches and diffs | | plan | text/markdown | replace | Plans and specs | | result | application/json | replace | Structured results | | context | text/plain | replace | Current context/state |

Usage:

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

Environment variables:

• TASK_GRAPH_CONFIG_PATH: Path to configuration file (takes precedence over .task-graph/config.yaml)
• TASK_GRAPH_DB_PATH: Database file path (fallback if no config file)
• TASK_GRAPH_MEDIA_DIR: Media directory for file attachments (fallback if no config file)
• TASK_GRAPH_LOG_DIR: Log directory path (fallback if no config file)

MCP Tools

Worker Management

| Tool | Description | |------|-------------| | connect(worker_id?, tags?, workflow?, force?, db_path?, media_dir?, log_dir?, config_path?, overlays?: str[]) | Register a worker. Optional workflow selects named workflow (solo, swarm, relay, hierarchical). Returns worker_id and active paths. | | disconnect(worker_id: worker_str, final_status?: status_str = "pending") | Unregister worker and release all claims/locks. | | list_agents(tags?: str[], file?: filename, task?: task_str, depth?: int, stale_timeout?: int) | List connected workers with filters. | | cleanup_stale(timeout?: int, final_status?: status_str) | Evict stale workers and release their claims. | | add_overlay(worker_id: str, overlay: str) | Add a dynamic workflow overlay to a connected worker. | | remove_overlay(worker_id: str, overlay: str) | Remove a workflow overlay from a connected worker. |

Task CRUD

| Tool | Description | |------|-------------| | create(description: str, id?: task_str, parent?: task_str, priority?: int = 5, points?: int, time_estimate_ms?: int, tags?: str[]) | Create a task. Priority 0-10 (higher = more important). | | create_tree(tree, parent?, child_type?, sibling_type?) | Create nested task tree. child_type (default: "contains") for parent→child deps, sibling_type for sibling deps. | | get(task: task_str) | Get task by ID with attachment metadata and counts. | | 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) | Query tasks with filters. Use ready=true for claimable tasks. | | 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[]) | Update task. Status/phase changes auto-manage ownership and trigger prompts. Include attachments to record commits/changelists. | | delete(worker_id: worker_str, task: task_str, cascade?: bool, reason?: str, obliterate?: bool, force?: bool) | Delete task. Soft delete by default; obliterate=true for permanent. | | scan(task: task_str, before?: int, after?: int, above?: int, below?: int) | Scan task graph in multiple directions. Depth: 0=none, N=levels, -1=all. | | search(query: str, limit?: int = 20, include_attachments?: bool, status_filter?: status_str) | FTS5 search. Supports phrases, prefix*, AND/OR/NOT, title:word. | | rename(worker_id: worker_str, task: task_str, new_id: task_str) | Atomically rename a task ID across all referencing tables. |

Task Claiming

| Tool | Description | |------|-------------| | claim(worker_id: worker_str, task: task_str, force?: bool) | Claim a task. Fails if deps unsatisfied, at limit, or lacks tags. Use force to steal. |

Note: Release via update(status="pending"). Complete via update(status="completed"). Status changes auto-manage ownership.

Dependencies

| Tool | Description | |------|-------------| | link(from: task_str\|task_str[], to: task_str\|task_str[], type?: dep_str = "blocks") | Create dependencies. Types: blocks, follows, contains, duplicate, see-also, relates-to. | | unlink(from: task_str\|"*", to: task_str\|"*", type?: dep_str) | Remove dependencies. Use * as wildcard. | | relink(prev_from: task_str[], prev_to: task_str[], from: task_str[], to: task_str[], type?: dep_str = "contains") | Atomically move dependencies (unlink then link). |

Tracking

| Tool | Description | |------|-------------| | thinking(worker_id: worker_str, thought: str, tasks?: task_str[]) | Broadcast live status. Visible to other workers. Refreshes heartbeat. | | task_history(task: task_str, states?: status_str[]) | Get status transition history with time tracking. | | project_history(from?: datetime_str, to?: datetime_str, states?: status_str[], limit?: int = 100) | Project-wide history with date range filters. | | log_metrics(worker_id: worker_str, task: task_str, cost_usd?: float, values?: int[8]) | Log metrics (aggregated). | | get_metrics(task: task_str\|task_str[]) | Get metrics for task(s). | | give_feedback(message: str, category?: str, sentiment?: str, agent_id?: str, tool_name?: str, task_id?: str) | Record feedback about tools, workflows, or UX. Enabled by default; rejects writes past size limit (default: 1MB). | | list_feedback() | Read the feedback markdown file. |

File Coordination

| Tool | Description | |------|-------------| | mark_file(worker_id: worker_str, file: filename\|filename[], task?: task_str, reason?: str) | Mark file(s) to signal intent. Advisory, non-blocking. | | unmark_file(worker_id: worker_str, file?: filename\|filename[]\|"*", task?: task_str, reason?: str) | Remove marks. Use * for all. | | list_marks(files?: filename[], worker_id?: worker_str, task?: task_str) | Get current file marks. | | mark_updates(worker_id: worker_str) | Poll for mark changes since last call. |

Attachments

| Tool | Description | |------|-------------| | attach(task: task_str\|task_str[], name: str, content?: str, mime?: mime_str, file?: filename, store_as_file?: bool, mode?: str) | Add attachment. Use file for reference, store_as_file for media storage. | | attachments(task: task_str, name?: str, mime?: mime_str) | Get attachment metadata. Glob patterns supported for name. | | detach(worker_id: worker_str, task: task_str, name: str, delete_file?: bool) | Delete attachment by name. |

Advanced

| Tool | Description | |------|-------------| | check_gates(task: task_str) | Check gate requirements before status/phase transition. Returns unsatisfied gates with pass/warn/fail status. | | get_advisory(topic?: str, task?: task_str, worker_id?: worker_str) | Get governance advisory guidance. Without topic: lists all topics. With topic: return

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Oortonaut
• Source: Oortonaut/task-graph-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.