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

Quick Start

# Installcargo 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 workclaim(worker_id="bright-lunar-swift-fox", task="add-auth")  → you own itupdate(..., phase="implement")                           → enter implementation phasethinking(agent="bright-lunar-swift-fox", thought="Adding JWT...")  → visible to othersupdate(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:

Extract and place the binary in your PATH.

From Source

git clone https://github.com/Oortonaut/task-graph-mcp.gitcd task-graph-mcpcargo 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 <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

Configuration

Full reference: See 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 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

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

Built-in defaults:

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

Task CRUD

Task Claiming

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

Dependencies

Tracking

File Coordination

Attachments

Advanced

MCP Resources

Task Tree Structure

Create hierarchical tasks with 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"}

Tree Node Fields

Top-Level Parameters

Referencing Existing Tasks

Use ref to integrate existing tasks into a tree structure:

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

Tag-Based Affinity

Workers declare capabilities via tags when connecting. Tasks can require specific tags to control which workers can claim them.

Example tag categories:

• Model capabilities: image-in, audio-out, video-in, code, bulk
• Access levels: prod-access, admin, external
• Specializations: rust, python, frontend, database

Note: Roles like coordinator/reviewer/deployer are better represented using phases.

Task requirements:

• needed_tags (AND): Agent must have ALL of these
• wanted_tags (OR): Agent must have AT LEAST ONE

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

Workflows and Phases

Phases

Tasks can have a phase to categorize the type of work being performed:

{  "title": "Add authentication",  "phase": "implement"}

Built-in phases: explore, implement, review, test, security, deploy, triage, diagnose, design, plan, doc, integrate, monitor, optimize

Phases enable:

• Transition prompts — Automatic guidance when entering/exiting phases
• Gates — Requirements that must be satisfied before phase transitions
• Role-based routing — In relay workflows, specialists own specific phases

Named Workflows

Pre-built workflow topologies optimize for different coordination patterns:

Select a workflow on connect:

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

Each workflow provides tailored prompts and coordination guidance. See WORKFLOW_TOPOLOGIES.md for detailed patterns.

Transition Prompts

Agents receive automatic guidance when status or phase changes:

# workflows.yamlstates:  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

Prompts support template variables: {{current_status}}, {{valid_exits}}, {{current_phase}}, {{valid_phases}}

Gates

Gates are requirements that must be satisfied before status or phase transitions:

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

Satisfy a gate by attaching evidence:

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

Enforcement levels: allow (advisory), warn (blocks unless force=true), reject (hard block)

File Coordination

Agents can coordinate file edits using advisory marks with change tracking:

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 markWorker A: unmark_file("worker-a", "src/main.rs", "ready for review")Worker B: mark_updates("worker-b") -> sees removal with reasonWorker B: mark_file("worker-b", "src/main.rs", "adding tests")

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐│  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     │                  └─────────────────┘

• Transport: Stdio — each worker spawns its own server process
• Database: SQLite with WAL mode for concurrent access across processes
• Deployment: Single binary, no external dependencies, works offline

Compared to Alternatives

Documentation

License

Apache 2.0

Built for AI agents that need structured workflows and reliable coordination.