Task Graph MCP Server

Multi-agent AI coordination that actually works.

When you have multiple AI agents working on the same codebase, things go wrong fast. Agents overwrite each other's changes. They duplicate work. They break dependencies. Task Graph solves this with proper coordination primitives: DAG-based task dependencies, advisory file locks, and atomic claiming—all through the Model Context Protocol.

Why Task Graph?

The problem: You've got a complex task that needs multiple AI agents working in parallel. Maybe a coordinator breaking down work, specialists handling different domains, validators checking results. Without coordination, it's chaos.

What you get:

• No stepping on toes — Advisory file locks let agents see who's editing what and why. No more blind overwrites or merge conflicts.
• Dependency-aware execution — Tasks form a DAG with cycle detection. Agents only claim work when dependencies are satisfied.
• 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.
• Configurable workflows — Define your own states, transitions, and dependency types. Match your process, not ours.

Features

Quick Start

# Install
cargo install task-graph-mcp

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

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

# Worker workflow
connect(worker_id="worker-1", tags=["rust","backend"])  → worker_id
list_tasks(ready=true, worker_id="worker-1")            → claimable work
claim(worker_id="worker-1", task="task-123")            → you own it
thinking(worker_id="worker-1", thought="Implementing...") → visible to others
update(worker_id="worker-1", task="task-123",           → done, deps unblock
       status="completed",
       attachments=[{name:"commit", content:"abc123"}])

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

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, in_progress, 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, in_progress]
  definitions:
    pending:
      exits: [ready, in_progress, cancelled]
    ready:
      exits: [in_progress, cancelled]
    in_progress:
      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.

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

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

Tasks can specify required capabilities with a non-empty list. Use either for one tag:

• agent_tags_all: Agent must have ALL of these (AND)
• agent_tags_any: Agent must have AT LEAST ONE (OR)

{
  "title": "Deploy to production",
  "agent_tags_all": ["deploy", "prod-access"],
  "agent_tags_any": ["aws", "gcp"]
}

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

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

License

Apache 2.0

Built for the era of AI agents that actually need to work together.