MCP Task Orchestrator

A Kotlin MCP server for comprehensive task management, allowing AI assistants to interact with project data.

Server-enforced workflow discipline for AI agents.

Prompt-based frameworks hope the LLM follows instructions. This one blocks the call if it doesn't.

Multi-agent workflows need infrastructure the model doesn't provide. When an orchestrator dispatches sub-agents across sessions, there's no built-in way to enforce what documentation must exist before work starts, track which agent made which change, or guarantee dependency ordering across a work breakdown. These are structural concerns — they belong in the server, not in prompts.

Task Orchestrator is anMCP server— not a prompt layer. It provides 14 tools that give any MCP-compatible AI agent a persistent work item graph withserver-enforced quality gates. The enforcement happens at the tool level: if a required design note isn't filled,advance_itemreturns an error. If a dependency isn't satisfied, the transition is blocked. If actor authentication is enabled and an agent doesn't identify itself, the call is rejected before it reaches the server.

# .taskorchestrator/config.yaml work_item_schemas: feature-task: notes: - key: requirements role: queue required: true description: "Acceptance criteria before starting" guidance: "Cover: problem statement, acceptance criteria, alternatives considered, test strategy." skill: "spec-quality" - key: implementation-notes role: work required: true description: "What was built and why"

traits: needs-security-review: notes: - key: security-assessment role: review required: true description: "Security review of auth, data handling, and access control" skill: "security-review" work_item_schemas: feature-task: default_traits: - needs-security-review notes: # ... base notes

create_work_tree( root={ "title": "User Authentication" }, children=[ { "ref": "schema", "title": "Database schema" }, { "ref": "api", "title": "Login API" }, { "ref": "tests", "title": "Integration tests" } ], deps=[ { "from": "schema", "to": "api" }, { "from": "api", "to": "tests" } ] )

Whenschemareaches terminal,apiis automatically unblocked. When all children complete, the parent cascades to terminal. Dependency ordering is enforced by the server — structurally, not by convention.

Everyadvance_itemtransition andmanage_notesupsert accepts an optional actor claim:

{ "actor": { "id": "impl-agent-42", "kind": "subagent", "parent": "orchestrator-1" } }

Enable actor authentication in config to require it:

When enabled, calls without actor claims are blocked before reaching the server. Query responses include the full delegation chain — which orchestrator dispatched which sub-agent, who wrote which note, who made which transition. Post-mortem debugging becomes a data query, not a conversation archaeology exercise.

No context rebuilding. One call recovers the full picture:

get_context(since="2025-01-15T09:00:00Z", includeAncestors=true)

Returns active items, recent transitions (with actor attribution), blocked items, stalled items with missing notes, and full ancestor chains. A new session has complete state in a single response.

Notes provide targeted, phase-specific documentation attached to work items. An implementation agent reads a concise requirements note scoped to its task rather than scanning broader project context.

Notes are keyed, role-scoped, and queryable:

query_notes(itemId="<uuid>", role="work", includeBody=false)

Metadata-only queries (includeBody=false) let agents check what exists without paying the token cost of reading every note body.

Search across all work items and notes by keyword. Results are relevance-ranked, so agents surfacing related work or picking up after a long gap get the most relevant matches first — not just a flat list.

query_items(operation="search", query="authentication login") query_notes(operation="search", query="password validation")

Search can be scoped to a subtree, filtered by status or tag, or run across the entire workspace. Agents use this to find related work before starting something new, or to locate a specific note without knowing which item it's attached to.

Task Orchestrator enforces workflow structure without imposing methodology. The server owns the guardrails — role transitions, dependency ordering, gate enforcement, and accountability. Agents own everything else. There are no mandatory planning ceremonies, no prescribed development processes, no opinion on how agents approach implementation. Schemas, traits, and actor authentication are opt-in layers that integrate with your team's development policies through.taskorchestrator/config.yaml. As models gain new capabilities, the harness stays out of the way rather than constraining what agents can do.

Prerequisite:Dockerinstalled and running.

docker pull ghcr.io/jpicklyk/task-orchestrator:latest docker run -d --name mcp-task-orchestrator-http --restart unless-stopped \ -v mcp-task-data:/app/data \ -e MCP_TRANSPORT=http -e API_ENABLED=true -e API_AUTH_MODE=none -e API_ALLOW_UNAUTHENTICATED=true \ -p 127.0.0.1:3001:3001 \ ghcr.io/jpicklyk/task-orchestrator:latest

{ "mcpServers": { "mcp-task-orchestrator": { "type": "http", "url": "http://localhost:3001/mcp" } } }

export TASK_ORCHESTRATOR_API_URL=http://localhost:3001

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

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

Restart your client. The server auto-initializes on first run — no setup required.

To activate workflow schema gates on STDIO, mount the project's config directly instead of relying on config-sync:

{ "mcpServers": { "mcp-task-orchestrator": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "-v", "${workspaceFolder}/.taskorchestrator:/project/.taskorchestrator:ro", "-e", "AGENT_CONFIG_DIR=/project", "ghcr.io/jpicklyk/task-orchestrator:latest" ] } } }

Without schemas, all 14 tools work in schema-free mode — no gates, no required notes. Add schemas when you want enforcement.

The plugin adds workflow automation on top of the MCP server — skills, hooks, and an orchestrator output style.

/plugin marketplace add https://github.com/jpicklyk/task-orchestrator /plugin install task-orchestrator@task-orchestrator-marketplace

The MCP server works without the plugin. The plugin makes it seamless with Claude Code.

Every tool supports short hex ID prefixes —advance_item(itemId="a3f2")instead of full UUIDs.

Morning — new session, new agent, zero context: Agent: get_context(since="2025-01-14T17:00:00Z") → 2 items in work, 1 blocked, 1 stalled (missing implementation-notes) → Recent transitions show orchestrator-1 dispatched 3 sub-agents yesterday → Full ancestor chains: "Auth Feature > Login API > Input validation" Agent: advance_item(trigger="start", itemId="a3f2", actor={ id: "morning-agent", kind: "subagent", parent: "orchestrator-1" }) → Error: "Gate check failed: required notes not filled for queue phase: requirements" Agent: manage_notes(upsert, itemId="a3f2", key="requirements", body="Validate email format, enforce password complexity...", actor={ id: "morning-agent", kind: "subagent" }) → Upserted. guidancePointer: null, noteProgress: { filled: 1, remaining: 0, total: 1 } Agent: advance_item(trigger="start", itemId="a3f2", actor={ id: "morning-agent", kind: "subagent" }) → queue → work. No context rebuilding. No conversation replay. → Actor recorded. Traceable. Accountable.

- Kotlin 2.3.21with Coroutines
- SQLite + Exposed ORM— zero-config persistent storage with FTS5 full-text search (bundled automatically)
- Flyway Migrations— versioned schema management
- MCP SDK 0.12.0— STDIO and HTTP transport
- Docker— one-command deployment

Clean Architecture (Domain > Application > Infrastructure > Interface) with comprehensive test coverage.

Key capabilities added in recent versions:

- REST API— an HTTP REST layer (API_ENABLED=true) exposes items, notes, dependencies, transitions, config, and real-time SSE events to dashboards, CI systems, and operators. Supports static bearer tokens, JWKS JWT auth, and an opt-in unauthenticated loopback mode (API_AUTH_MODE=none) for single-developer local setups — seeQuick Startabove and/configure-server. Seecurrent/docs/api-rest.mdfor the full endpoint reference.
- Full-text search— search work items and notes by keyword with ranked results (seeFull-Text Searchabove)
- Unbounded hierarchy depth— item trees are not capped at depth 3; cycle protection is enforced at the database level via a trigger
- Backlinks—query_dependencies(operation="backlinks")finds all items that reference a given item (reverse-direction edge lookup)

MIT License— Free for personal and commercial use.

Comprehensive Trello integration: 46 tools covering boards, cards, lists, labels, checklists, attachments, members, custom fields, and search. Read-only mode, image attachment auto-download. Active fork of kocakli/Trello-Desktop-MCP integrating contributions from across the Trello MCP fork ecosystem