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

Feature	Description
Task Hierarchy	Unlimited nesting with parent/child relationships
DAG Dependencies	Typed edges (blocks, follows, contains) with cycle detection
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

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:

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

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.<key>.mime`	MIME type string	Default MIME type for this key
`definitions.<key>.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?, force?, db_path?, media_dir?, log_dir?, config_path?)`	Register a worker. Returns `worker_id` and active `paths`. Path args are informational (set via env/CLI before server starts).
`disconnect(worker_id: worker_str, final_status?: status_str = "pending")`	Unregister worker and release all claims/locks.
`list_workers(tags?: str[], file?: filename, task?: task_str, depth?: int)`	List connected workers with filters.

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, worker_id?: worker_str, tags_any?: str[], tags_all?: str[], sort_by?: str, sort_order?: str, limit?: int)`	Query tasks with filters. Use `ready=true` for claimable tasks.
`update(worker_id: worker_str, task: task_str, status?: status_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 changes auto-manage ownership. 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.

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

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
`query(sql: str, params?: str[], limit?: int = 100, format?: str)`	Execute read-only SQL. SELECT only. Requires permission.

MCP Resources

URI	Description
`tasks://all`	Full task graph with dependencies
`tasks://ready`	Tasks ready to claim
`tasks://blocked`	Tasks blocked by dependencies
`tasks://claimed`	All claimed tasks
`tasks://worker/{id}`	Tasks owned by a worker
`tasks://tree/{id}`	Task with all descendants
`files://marks`	All file marks
`workers://all`	Registered workers
`plan://acp`	ACP-compatible plan export
`stats://summary`	Aggregate statistics

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

Field	Description
`title`	Task title (required for new tasks)
`description`	Task description
`id`	Custom task ID (UUID7 generated if omitted)
`ref`	Reference existing task by ID (other fields ignored when set)
`priority`	Priority 0-10 (default 5)
`points`	Story points / complexity estimate
`time_estimate_ms`	Estimated duration in milliseconds
`tags`	Categorization tags for the task
`needed_tags`	Agent must have ALL of these tags to claim (AND)
`wanted_tags`	Agent must have AT LEAST ONE of these tags to claim (OR)
`children`	Nested child nodes

Top-Level Parameters

Parameter	Default	Description
`tree`	required	Root node of the task tree
`parent`	null	Attach tree root to existing parent task
`child_type`	"contains"	Dependency type from parent to children
`sibling_type`	null	Dependency type between siblings ("follows" for sequential, null for parallel)

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

	Task Graph	Linear task lists	Custom databases
Multi-agent safe	✓ Atomic claims, file locks	✗ Race conditions	Maybe, DIY
Dependency tracking	✓ DAG with cycle detection	✗ Manual ordering	DIY
MCP native	✓ First-class	✗ Wrapper needed	✗ Wrapper needed
Token accounting	✓ Built-in	✗	DIY
Setup required	None	None	Database server

License

Apache 2.0

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

task-graph-mcp 0.1.1

Task Graph MCP Server

Why Task Graph?

Features

Quick Start

Installation

From crates.io (Recommended)

Pre-built Binaries

From Source

Usage

As an MCP Server

CLI Options

Configuration

States Configuration

Dependencies Configuration

Attachments Configuration

MCP Tools

Worker Management

Task CRUD

Task Claiming

Dependencies

Tracking

File Coordination

Attachments

Advanced

MCP Resources

Task Tree Structure

Tree Node Fields

Top-Level Parameters

Referencing Existing Tasks

Tag-Based Affinity

File Coordination

Architecture

Compared to Alternatives

License