task-orchestrator

MCP Task Orchestrator

Schema-driven workflow enforcement for AI agents.

An MCP server that gives AI coding assistants a persistent work item graph with server-enforced quality gates. Define workflow schemas in YAML to do two things: (1) set a planning floor that enforces your minimum specification requirements before work can start, and (2) guide agent workflows through each phase with structured instructions the server surfaces at exactly the right moment. Items flow through queue → work → review → terminal with dependency enforcement and gate-checked transitions — the server blocks progression until required work is done and tells agents precisely what's missing. The result: deterministic workflow progression that doesn't depend on prompt discipline, and persistent state that lets agents pick up where they left off across sessions.

---

Why This Exists

AI agents have no built-in way to manage complex work. Without persistent state, every session starts from zero — no memory of what was planned, what's done, or what's blocked. Multi-step projects fall apart as the agent loses track of decisions, dependencies, and progress.

Task Orchestrator gives agents a structured backbone: a persistent work item graph where items flow through queue → work → review → terminal with dependency enforcement and note-based documentation at every phase. The server — not the AI — enforces what can happen next: gate-checked transitions, dependency ordering, and required documentation create deterministic workflow progression regardless of which model, session, or sub-agent is driving. Agents read concise notes instead of replaying conversation history — implementing context engineering patterns that keep the agent aligned across sessions and sub-agent boundaries.

---

Key Features

• ✅ Persistent Memory — AI remembers project state, completed work, and decisions across sessions
• ✅ Token Efficiency — Agents read concise per-phase notes instead of replaying conversation history; overview queries and metadata-only modes minimize payload size
• ✅ Hierarchical WorkItems — Flexible depth hierarchy (up to 4 levels) with any nesting structure you need
• ✅ Note Schemas — Per-item documentation requirements that gate phase transitions; enforced by the server
• ✅ Role-Based Workflow — queue → work → review → terminal with named triggers and automatic dependency enforcement
• ✅ Dependency Graph — Typed BLOCKS edges with pattern shortcuts (linear chains, fan-out, fan-in) and BFS traversal
• ✅ Sub-Agent Orchestration — Delegated execution for complex work (Claude Code)
• ✅ Skills & Hooks — Workflow coordination skills and event-driven automation (Claude Code plugin)
• ✅ MCP Protocol Support — Core persistence and task management work with any MCP client

---

Quick Start

Prerequisite: Docker must be installed and running.

Step 1: Pull the image

docker pull ghcr.io/jpicklyk/task-orchestrator:latest

This is a one-time step — Docker caches the image locally. Pulling first ensures your MCP client connects instantly rather than waiting silently on first launch.

Step 2: Register with your MCP client

Choose the option that matches your setup:

Option A: Claude Code (CLI — recommended)

Register the server once from your terminal:

claude mcp add-json mcp-task-orchestrator '{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "mcp-task-data:/app/data",
    "ghcr.io/jpicklyk/task-orchestrator:latest"
  ]
}'

Restart Claude Code, then run /mcp to confirm mcp-task-orchestrator is connected.

Option B: Project .mcp.json

Add to .mcp.json in your project root (checked into source control so teammates get it automatically):

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "mcp-task-data:/app/data",
        "ghcr.io/jpicklyk/task-orchestrator:latest"
      ]
    }
  }
}

The mcp-task-data Docker volume persists the SQLite database across container restarts. The server auto-initializes its schema on first run — no additional setup required.

Option C: Other MCP Clients

Configure your client with the same JSON as Option A above. STDIO transport works with any MCP-compatible client.

Advanced: Per-Project Note Schemas