task-orchestrator

The MCP Task Orchestrator provides a schema-driven workflow backbone for AI agents. It maintains a persistent work item graph that items flow through across the phases queue → work → review → terminal, enforcing dependencies and gate checks to ensure required notes or acceptance criteria are completed before progression. This means AI agents can operate with memory of prior decisions and blockers, while you control the exact conditions under which transitions are allowed. The server surfaces concise, phase-specific notes to guide agents, reducing the need to replay long conversations and enabling deterministic workflow progression across sessions and sub-agents. The system supports hierarchical work items (up to four levels), note schemas that gate transitions, and dependency graphs to model complex projects. You can extend its capability with a Claude Code plugin for integrated command access and workflow actions.

To use, run the MCP Task Orchestrator container (as described in installation) and register it with your MCP client. Once connected, you can leverage the available tools and commands to create and manage work items, view progress, and enforce schemas. If you enable per-project schemas, the server will enforce the defined notes before advancing items, otherwise it runs in schema-free mode with all 13 tools available by default. The Claude Code integration exposes commands such as work-summary, create-item, quick-start, and status-progression for interactive orchestration within your coding sessions.

Prerequisites:

• Docker installed and running on your machine or server
• Basic familiarity with MCP clients (e.g., Claude Code, or your own MCP client)

Step 1: Pull the image (one-time)

# Optional: pull the latest image to ensure local cache
docker pull ghcr.io/jpicklyk/task-orchestrator:latest

Step 2: Run the MCP server container

# Start the server in detached mode (example; adjust volume/name as needed)
docker run --rm -i \
  -v mcp-task-data:/app/data \
  ghcr.io/jpicklyk/task-orchestrator:latest

Step 3: Register with your MCP client

• Option A (CLI integration): provide the same JSON payload as your MCP client expects, e.g.,

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

• Option B (project configuration): add the following to your project’s .mcp.json:

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

Step 4: Optional per-project config (schemas)

• To enable per-project note schemas, mount your project config and set AGENT_CONFIG_DIR:

# Example run with per-project config mounted
docker run --rm -i \
  -v mcp-task-data:/app/data \
  -v /path/to/your/project/.taskorchestrator:/project/.taskorchestrator:ro \
  -e AGENT_CONFIG_DIR=/project \
  ghcr.io/jpicklyk/task-orchestrator:latest

Step 5: Verification

• Connect your MCP client and verify the server is registered and reachable.
• If using Claude Code, install the plugin and use the available task orchestration commands to manage items and schemas.

Tips and common considerations:

• If you want per-project data isolation, use a unique Docker volume name per project (e.g., my-project-data:/app/data) so items and notes do not mix across projects.
• The AGENT_CONFIG_DIR environment variable can be used to point the server at a project-wide config directory for note schemas and workflow definitions.
• The server defaults to schema-free operation; to enforce gating, supply a .taskorchestrator/config.yaml via the mounted project path as described in the per-project config section.
• The container stores its database in the mcp-task-data Docker volume; ensure proper volume persistence when upgrading or migrating environments.
• If you plan to use Claude Code plugin features, ensure the plugin is installed and connected after the server is registered.