{
  "markdown": "# MCP Task Orchestrator\n\n**Server-enforced workflow discipline for AI agents.**\n\nPrompt-based frameworks hope the LLM follows instructions. This one blocks the call if it doesn't.\n\n[![Version](https://img.shields.io/github/v/tag/jpicklyk/task-orchestrator?sort=semver)](https://github.com/jpicklyk/task-orchestrator/releases)\n[![CI](https://github.com/jpicklyk/task-orchestrator/actions/workflows/test.yml/badge.svg)](https://github.com/jpicklyk/task-orchestrator/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple)](https://modelcontextprotocol.io)\n\n---\n\n## The Problem\n\nMulti-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.\n\n## A Different Approach\n\nTask Orchestrator is an [MCP server](https://modelcontextprotocol.io) — not a prompt layer. It provides 14 tools that give any MCP-compatible AI agent a persistent work item graph with **server-enforced quality gates**. The enforcement happens at the tool level: if a required design note isn't filled, `advance_item` returns 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.\n\nThe rules live in the server, not the conversation.\n\n**What this means in practice:**\n\n- An agent can't start implementation without filling the required specification note\n- A sub-agent can't advance a blocked task until its upstream dependency is complete\n- Every transition and note records *who* made the change (actor attribution)\n- Auditing mode blocks any write operation where the agent doesn't identify itself\n- A new session picks up exactly where the last one left off — persistent state, not conversation replay\n- Workflow schemas are YAML config, not hardcoded prompts — change the rules without changing code\n\n---\n\n## How It's Different\n\n|  | Prompt-Based Frameworks | Task Orchestrator |\n|--|------------------------|-------------------|\n| **Enforcement** | Instructions that agents should follow | Server blocks the call if rules aren't met |\n| **Persistence** | File-based state | SQLite database with structured queries |\n| **Accountability** | No concept of which agent did what | Actor attribution with pluggable verification (JWKS) |\n| **Dependency ordering** | Sequenced by prompt convention | Server validates dependency graphs before allowing transitions |\n| **Session continuity** | Conversation history or file reconstruction | `get_context()` returns full state in one call |\n| **Portability** | Tied to one AI client | Works with any MCP-compatible client |\n\n---\n\n## Core Capabilities\n\n### Workflow Enforcement\n\nSchemas define what agents must produce at each phase — and the server blocks progression until it's done. But schemas do more than gate transitions. They set a **planning floor**: when an agent enters plan mode, the schema tells it what documentation must exist before implementation can start, shaping the plan structure itself.\n\n```yaml\n# .taskorchestrator/config.yaml\nwork_item_schemas:\n  feature-task:\n    notes:\n      - key: requirements\n        role: queue\n        required: true\n        description: \"Acceptance criteria before starting\"\n        guidance: \"Cover: problem statement, acceptance criteria, alternatives considered, test strategy.\"\n        skill: \"spec-quality\"\n      - key: implementation-notes\n        role: work\n        required: true\n        description: \"What was built and why\"\n```\n\n`advance_item(trigger=\"start\")` from queue requires `requirements` to be filled. No exceptions, no prompt-dependent compliance — the server returns an error with exactly which notes are missing.\n\nThe `guidance` field provides authoring instructions surfaced at the right moment — when the agent is about to fill that note, `get_context` returns the guidance as a `guidancePointer`. The `skill` field takes this further: it references a specific skill that the agent must invoke before filling the note, providing a deterministic evaluation framework rather than freeform prose. Together, they create structured agent behavior that's configured in YAML, not hardcoded in prompts.\n\n### Composable Traits\n\nTraits add cross-cutting note requirements to any schema without duplicating definitions. Define a trait once, apply it to any item type:\n\n```yaml\ntraits:\n  needs-security-review:\n    notes:\n      - key: security-assessment\n        role: review\n        required: true\n        description: \"Security review of auth, data handling, and access control\"\n        skill: \"security-review\"\n\nwork_item_schemas:\n  feature-task:\n    default_traits:\n      - needs-security-review\n    notes:\n      # ... base notes\n```\n\nEvery `feature-task` item automatically inherits the `security-assessment` note requirement. Traits can also be applied per-item via the `traits` parameter on `manage_items` — a task touching authentication gets `needs-security-review` while a CSS cleanup doesn't.\n\n### Persistent Work Item Graph\n\nEverything is a **WorkItem** in a hierarchical graph. Items nest up to 4 levels deep, connected by typed dependency edges. Create an entire work breakdown atomically:\n\n```\ncreate_work_tree(\n  root={ \"title\": \"User Authentication\" },\n  children=[\n    { \"ref\": \"schema\", \"title\": \"Database schema\" },\n    { \"ref\": \"api\",    \"title\": \"Login API\" },\n    { \"ref\": \"tests\",  \"title\": \"Integration tests\" }\n  ],\n  deps=[\n    { \"from\": \"schema\", \"to\": \"api\" },\n    { \"from\": \"api\",    \"to\": \"tests\" }\n  ]\n)\n```\n\nWhen `schema` reaches terminal, `api` is automatically unblocked. When all children complete, the parent cascades to terminal. Dependency ordering is enforced by the server — structurally, not by convention.\n\n### Actor Attribution & Auditing\n\nEvery `advance_item` transition and `manage_notes` upsert accepts an optional actor claim:\n\n```json\n{\n  \"actor\": {\n    \"id\": \"impl-agent-42\",\n    \"kind\": \"subagent\",\n    \"parent\": \"orchestrator-1\"\n  }\n}\n```\n\nEnable actor authentication in config to require it:\n\n```yaml\nactor_authentication:\n  enabled: true\n```\n\nWhen 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.\n\n### Session Continuity\n\nNo context rebuilding. One call recovers the full picture:\n\n```\nget_context(since=\"2025-01-15T09:00:00Z\", includeAncestors=true)\n```\n\nReturns 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.\n\n### Notes as Structured Context\n\nNotes 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.\n\nNotes are keyed, role-scoped, and queryable:\n\n```\nquery_notes(itemId=\"<uuid>\", role=\"work\", includeBody=false)\n```\n\nMetadata-only queries (`includeBody=false`) let agents check what exists without paying the token cost of reading every note body.\n\n### Full-Text Search\n\nSearch 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.\n\n```\nquery_items(operation=\"search\", query=\"authentication login\")\nquery_notes(operation=\"search\", query=\"password validation\")\n```\n\nSearch 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.\n\n### Design Philosophy\n\nTask 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.\n\n---\n\n## Quick Start\n\n**Prerequisite**: [Docker](https://www.docker.com/products/docker-desktop/) installed and running.\n\nIf you work across multiple projects, **set up once and every project you open just works**: run\none persistent server with the REST API on, and each project's `.taskorchestrator/config.yaml` syncs\ninto it automatically via `config-sync` — no per-project container, no manual config mounting.\n\n### Recommended: HTTP + REST enabled, localhost-only\n\nPull the image, then run the plugin's `/configure-server` skill (or use the equivalent manual setup\nbelow) to stand up a persistent local server:\n\n```bash\ndocker pull ghcr.io/jpicklyk/task-orchestrator:latest\n\ndocker run -d --name mcp-task-orchestrator-http --restart unless-stopped \\\n  -v mcp-task-data:/app/data \\\n  -e MCP_TRANSPORT=http -e API_ENABLED=true -e API_AUTH_MODE=none -e API_ALLOW_UNAUTHENTICATED=true \\\n  -p 127.0.0.1:3001:3001 \\\n  ghcr.io/jpicklyk/task-orchestrator:latest\n```\n\nRegister it in `.mcp.json` (HTTP shape — not an args array):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-task-orchestrator\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:3001/mcp\"\n    }\n  }\n}\n```\n\nAnd export the client-side env so `config-sync` can find the server (without this, config-sync\nsilently no-ops):\n\n```bash\nexport TASK_ORCHESTRATOR_API_URL=http://localhost:3001\n```\n\n> **SECURITY:** unauthenticated REST means anyone who can reach the port has full read/write/delete\n> access. This is only safe because the port is published **loopback-only** (`-p 127.0.0.1:3001:3001`).\n> Never publish it on `0.0.0.0` or a wider interface.\n\nPrefer not to wire this up by hand? Install the plugin and run `/configure-server` — it renders\nall of the above (plus the bearer-token and STDIO alternatives) interactively.\n\n### Simpler alternative: STDIO, no config-sync\n\nIf you don't want a persistent daemon and are fine hand-mounting each project's config, STDIO is the\nsimpler no-setup option — a per-session container, no port, no REST API:\n\n```bash\nclaude mcp add-json mcp-task-orchestrator '{\n  \"command\": \"docker\",\n  \"args\": [\n    \"run\", \"--rm\", \"-i\",\n    \"-v\", \"mcp-task-data:/app/data\",\n    \"ghcr.io/jpicklyk/task-orchestrator:latest\"\n  ]\n}'\n```\n\nOr add the same shape to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-task-orchestrator\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-v\", \"mcp-task-data:/app/data\",\n        \"ghcr.io/jpicklyk/task-orchestrator:latest\"\n      ]\n    }\n  }\n}\n```\n\nRestart your client. The server auto-initializes on first run — no setup required.\n\nTo activate workflow schema gates on STDIO, mount the project's config directly instead of relying on\nconfig-sync:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-task-orchestrator\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-v\", \"mcp-task-data:/app/data\",\n        \"-v\", \"${workspaceFolder}/.taskorchestrator:/project/.taskorchestrator:ro\",\n        \"-e\", \"AGENT_CONFIG_DIR=/project\",\n        \"ghcr.io/jpicklyk/task-orchestrator:latest\"\n      ]\n    }\n  }\n}\n```\n\nWithout schemas, all 14 tools work in schema-free mode — no gates, no required notes. Add schemas when you want enforcement.\n\n---\n\n## Claude Code Plugin\n\nThe plugin adds workflow automation on top of the MCP server — skills, hooks, and an orchestrator output style.\n\n**Install:**\n\n```\n/plugin marketplace add https://github.com/jpicklyk/task-orchestrator\n/plugin install task-orchestrator@task-orchestrator-marketplace\n```\n\n**What it adds:**\n\n| Layer | What it does |\n|-------|-------------|\n| **Skills** | Slash commands for common workflows — `/task-orchestrator:create-item`, `/task-orchestrator:manage-schemas`, `/task-orchestrator:quick-start`, `/task-orchestrator:configure-server` |\n| **Hooks** | Automatic context injection at session start, plan mode integration, sub-agent context handoff, actor attribution enforcement |\n| **Output style** | Workflow Orchestrator mode — Claude plans, delegates to sub-agents, and tracks progress without writing code directly |\n\nThe MCP server works without the plugin. The plugin makes it seamless with Claude Code.\n\n---\n\n## 14 MCP Tools\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| **Graph** | `manage_items`, `query_items`, `create_work_tree`, `complete_tree` | Build and query the work item hierarchy |\n| **Notes** | `manage_notes`, `query_notes` | Persistent phase-scoped documentation |\n| **Dependencies** | `manage_dependencies`, `query_dependencies` | Typed edges with pattern shortcuts (linear, fan-out, fan-in) |\n| **Workflow** | `advance_item`, `get_next_status`, `get_context`, `get_next_item`, `get_blocked_items`, `claim_item` | Trigger-based transitions with gate enforcement, dependency validation, and atomic find-and-claim (selector mode) for multi-agent fleets |\n\nEvery tool supports short hex ID prefixes — `advance_item(itemId=\"a3f2\")` instead of full UUIDs.\n\n---\n\n## What It Looks Like in Practice\n\n```\nMorning — new session, new agent, zero context:\n\nAgent: get_context(since=\"2025-01-14T17:00:00Z\")\n       → 2 items in work, 1 blocked, 1 stalled (missing implementation-notes)\n       → Recent transitions show orchestrator-1 dispatched 3 sub-agents yesterday\n       → Full ancestor chains: \"Auth Feature > Login API > Input validation\"\n\nAgent: advance_item(trigger=\"start\", itemId=\"a3f2\",\n         actor={ id: \"morning-agent\", kind: \"subagent\", parent: \"orchestrator-1\" })\n       → Error: \"Gate check failed: required notes not filled for queue phase: requirements\"\n\nAgent: manage_notes(upsert, itemId=\"a3f2\", key=\"requirements\",\n         body=\"Validate email format, enforce password complexity...\",\n         actor={ id: \"morning-agent\", kind: \"subagent\" })\n       → Upserted. guidancePointer: null, noteProgress: { filled: 1, remaining: 0, total: 1 }\n\nAgent: advance_item(trigger=\"start\", itemId=\"a3f2\",\n         actor={ id: \"morning-agent\", kind: \"subagent\" })\n       → queue → work. No context rebuilding. No conversation replay.\n       → Actor recorded. Traceable. Accountable.\n```\n\n---\n\n## Documentation\n\n| Resource | What's there |\n|----------|-------------|\n| **[Quick Start Guide](https://github.com/jpicklyk/task-orchestrator/wiki/quick-start)** | Full setup walkthrough with first work item |\n| **[API Reference](https://github.com/jpicklyk/task-orchestrator/wiki/api-reference)** | All 14 MCP tools — parameters, response shapes, actor attribution |\n| **[REST API Reference](current/docs/api-rest.md)** | HTTP REST endpoints, DTOs, SSE, auth, merge-patch, ETag |\n| **[Workflow Guide](https://github.com/jpicklyk/task-orchestrator/wiki/workflow-guide)** | Schemas, phase gates, dependencies, lifecycle modes |\n| **[Fleet Deployment](https://github.com/jpicklyk/task-orchestrator/wiki/fleet-deployment)** | Multi-agent operators: REST API auth, MCP actor identity, SQLite tuning, capacity planning |\n| **[Wiki](https://github.com/jpicklyk/task-orchestrator/wiki)** | Full documentation hub |\n| **[Changelog](CHANGELOG.md)** | Release history |\n| **[Contributing](CONTRIBUTING.md)** | Developer setup and contribution process |\n\n---\n\n## Technical Stack\n\n- **Kotlin 2.3.21** with Coroutines\n- **SQLite + Exposed ORM** — zero-config persistent storage with FTS5 full-text search (bundled automatically)\n- **Flyway Migrations** — versioned schema management\n- **MCP SDK 0.12.0** — STDIO and HTTP transport\n- **Docker** — one-command deployment\n\nClean Architecture (Domain > Application > Infrastructure > Interface) with comprehensive test coverage.\n\nKey capabilities added in recent versions:\n- **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 — see [Quick Start](#quick-start) above and `/configure-server`. See [`current/docs/api-rest.md`](current/docs/api-rest.md) for the full endpoint reference.\n- **Full-text search** — search work items and notes by keyword with ranked results (see [Full-Text Search](#full-text-search) above)\n- **Unbounded hierarchy depth** — item trees are not capped at depth 3; cycle protection is enforced at the database level via a trigger\n- **Backlinks** — `query_dependencies(operation=\"backlinks\")` finds all items that reference a given item (reverse-direction edge lookup)\n\n---\n\n## License\n\n[MIT License](LICENSE) — Free for personal and commercial use.\n",
  "bytes": 17405,
  "sha": "ff85fe714473f6da35fd421d42390940d3a8c7bfe8c6cc1877ed7db3a7821c84",
  "repo_slug": "jpicklyk/task-orchestrator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jpicklyk_task_orchestrator_06c80600/readme"
}