MCP Task Orchestrator

Un servidor MCP en Kotlin para la gestión integral de tareas, que permite a los asistentes de IA interactuar con datos de proyectos.

GitHub

209

Documentación

MCP Task Orchestrator

Disciplina de flujo de trabajo impuesta por el servidor para agentes de IA.

Los frameworks basados en prompts esperan que el LLM siga las instrucciones. Este bloquea la llamada si no lo hace.

Task Orchestrator es un servidor MCP que brinda a los agentes de codificación de IA un grafo persistente de elementos de trabajo con puertas de calidad impuestas por el servidor, no por el prompt. Está diseñado para desarrolladores que ejecutan flujos de codificación multiagente o multisessión: un orquestador que despacha subagentes, una sesión nueva que retoma el trabajo de ayer, o un bucle autónomo que drena un backlog. Se distribuye como imagen de Docker, funciona con cualquier cliente MCP y tiene un plugin opcional para Claude Code que añade skills y hooks encima.

¿Nuevo aquí? Comienza con la guía ilustrada de campo. Explica las ideas de esta página en páginas visuales breves, varias de ellas interactivas: dispara triggers en un phase gate, haz clic a través de un work breakdown por sus dependencias y observa cómo se resuelve un esquema.

El Problema

Los flujos de trabajo multiagente necesitan infraestructura que el modelo no proporciona. Cuando un orquestador despacha subagentes entre sesiones, no hay una forma integrada de imponer qué documentación debe existir antes de que comience el trabajo, rastrear qué agente hizo qué cambio o garantizar el orden de dependencias en un work breakdown. Estas son preocupaciones estructurales: pertenecen al servidor, no a los prompts.

Task Orchestrator las coloca en el servidor. Si una nota de diseño requerida no está completada, advance_item devuelve un error que nombra la nota faltante. Si una dependencia upstream no está completa, la transición se bloquea. Cada transición y nota registra quién la hizo. Una sesión nueva recupera el estado completo en una sola llamada en lugar de reproducir una conversación. Y las reglas son configuración YAML, no prompts codificados: cámbialas sin cambiar código.

Cómo Se Ve

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(transitions=[{ itemId: "a3f2", trigger: "start",
         actor: { id: "morning-agent", kind: "subagent", parent: "orchestrator-1" } }])
       → Error: "Gate check failed: required notes not filled for queue phase: requirements"

Agent: manage_notes(operation="upsert", notes=[{ itemId: "a3f2", key: "requirements",
         body: "Validate email format, enforce password complexity...",
         actor: { id: "morning-agent", kind: "subagent" } }])
       → Upserted. noteProgress: { filled: 1, remaining: 0, total: 1 }

Agent: advance_item(transitions=[{ itemId: "a3f2", trigger: "start",
         actor: { id: "morning-agent", kind: "subagent" } }])
       → queue → work. Actor recorded. No context rebuilding.

Inicio Rápido

Requisito previo: Docker instalado y en ejecución.

1. Registra el servidor

La configuración más simple es un contenedor STDIO por sesión: sin puerto, sin daemon, sin API REST. Añádelo al .mcp.json de tu proyecto:

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

Los usuarios de Claude Code pueden registrar la misma forma desde la CLI:

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

Reinicia tu cliente. El servidor crea su base de datos SQLite en la primera ejecución. Sin un archivo de configuración, cada herramienta funciona en modo sin esquema: sin puertas, sin notas requeridas. Añade esquemas cuando quieras imposición.

2. Habilita los esquemas de flujo de trabajo

Crea .taskorchestrator/config.yaml en tu proyecto (consulta Workflow Enforcement para un ejemplo, o usa la skill /task-orchestrator:manage-schemas del plugin) y monta esa carpeta en el contenedor:

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

Usa una ruta absoluta del host. El .mcp.json de Claude Code expande solo variables de entorno (${VAR} y ${VAR:-default}), por lo que los placeholders estilo editor como ${workspaceFolder} no se sustituyen. Solo se expone la carpeta .taskorchestrator/; el servidor no tiene acceso al resto de tu proyecto.

3. Configuración multiproyecto (HTTP + config-sync)

Si trabajas en varios repositorios, ejecuta un servidor persistente con la API REST habilitada. El .taskorchestrator/config.yaml de cada proyecto se sincroniza automáticamente a través del hook config-sync del plugin: sin contenedor por proyecto, sin montaje manual, y los cambios de configuración se recargan en caliente sin reiniciar. La skill /task-orchestrator:configure-server del plugin renderiza esta configuración de forma interactiva; el equivalente manual es:

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

Regístralo en .mcp.json usando la forma HTTP:

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

Y exporta la variable del lado del cliente que le dice a config-sync dónde está el servidor (sin ella, config-sync no hace nada silenciosamente):

export TASK_ORCHESTRATOR_API_URL=http://localhost:3001

Alternativamente, un client.json (solo apiUrl, sin token) proporciona la URL. El /task-orchestrator:init en modo proyecto lo escribe junto a la configuración del proyecto, solo para un servidor loopback y solo como origen desnudo sin ruta, consulta o fragmento (añade .taskorchestrator/client.json a .gitignore, la URL es específica de la máquina); /task-orchestrator:init --user escribe el archivo a nivel de usuario, que funciona para cualquier host. El orden es la variable de entorno, luego el archivo a nivel de proyecto, luego el archivo a nivel de usuario. /task-orchestrator:init configura una raíz de proyecto para el directorio actual, y /task-orchestrator:init --user crea una raíz personal que sirve a cada directorio sin su propia configuración.

SEGURIDAD: REST sin autenticación significa que cualquiera que pueda alcanzar el puerto tiene acceso completo de lectura/escritura/eliminación. Esto solo es seguro porque el puerto se publica solo-loopback (-p 127.0.0.1:3001:3001). Nunca lo publiques en 0.0.0.0 o en una interfaz más amplia. Para implementaciones compartidas o en red, usa tokens bearer o autenticación JWKS — consulta Fleet Deployment.

¿Prefieres ejecutar sin Docker? CONTRIBUTING.md cubre la construcción del fat JAR desde el código fuente.

Capacidades Principales

El Modelo de Fases

Cada elemento de trabajo tiene un rol: queue (no iniciado), work (en progreso), review (opcional, opt-in por esquema), blocked (una dependencia upstream no está cumplida) y terminal (hecho o cancelado). Cada rol se asigna a uno o más estados configurables. Los agentes mueven elementos con advance_item(trigger=...) en lugar de editar el estado directamente, y esa llamada es donde se verifica cada puerta. Los esquemas adjuntan requisitos de notas a los roles: una nota declarada con role: queue debe existir antes de que el elemento pueda salir de la fase de cola.

Ilustrado: Phase Gates dibuja los roles y triggers como una pista e incluye un simulador de puertas.

Workflow Enforcement

Los esquemas definen qué deben producir los agentes en cada fase, y el servidor bloquea la progresión hasta que esté hecho. También establecen un piso de planificación: cuando un agente entra en modo plan, el esquema le dice qué documentación debe existir antes de que la implementación pueda comenzar, dando forma al propio plan.

# .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"

Con este esquema, advance_item(trigger="start") desde la cola requiere que requirements esté completada. El servidor devuelve un error que enumera exactamente qué notas faltan.

El campo guidance proporciona instrucciones de autoría que se muestran en el momento adecuado: cuando un agente está a punto de completar esa nota, la respuesta lleva la guía como un guidancePointer. El campo skill va más allá, nombrando una skill que el agente debe invocar antes de completar la nota para que la evaluación siga un framework definido en lugar de prosa libre.

Traits Componibles

Los traits añaden requisitos de notas transversales a cualquier esquema sin duplicar definiciones. Define un trait una vez, aplícalo a cualquier tipo de elemento:

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

Cada elemento feature-task hereda automáticamente el requisito security-assessment. Los traits también se pueden aplicar por elemento mediante el parámetro traits en manage_items, de modo que una tarea que toca autenticación obtiene needs-security-review mientras que una limpieza de CSS no.

Ilustrado: Schemas and Traits muestra cómo un tipo, sus traits predeterminados y los traits por elemento se resuelven en una sola puerta. Seats cubre la división de una fase entre varios agentes.

Grafo Persistente de Elementos de Trabajo

Todo es un WorkItem en un grafo jerárquico. Los elementos se anidan a cualquier profundidad y se conectan mediante aristas de dependencia tipadas. Crea un work breakdown completo atómicamente:

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

Cuando schema alcanza el estado terminal, api se desbloquea automáticamente. Cuando todos los hijos se completan, el padre se desbloquea en cascada al estado terminal. El orden de dependencias se impone por el servidor, estructuralmente, no por convención.

Ilustrado: Work Graph tiene una versión clicable de este árbol que muestra bloqueo, desbloqueo y cascadas de padres.

Atribución de Actor

Cada transición advance_item y upsert manage_notes acepta una declaración de actor opcional, y el servidor la registra en la transición o nota:

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

Las respuestas de consulta incluyen la cadena completa de delegación: qué orquestador despachó a qué subagente, quién escribió qué nota, quién hizo qué transición. La depuración post-mortem se convierte en una consulta de datos en lugar de arqueología de conversación.

Para hacer la declaración obligatoria, habilita la autenticación de actor en la configuración:

actor_authentication:
  enabled: true   # read by the plugin hook (workspace/user config), not the server

Con el plugin de Claude Code instalado, un hook rechaza cualquier escritura que carezca de actor antes de que la llamada salga del cliente. Otros clientes MCP deben proporcionar la declaración por convención. La verificación JWKS opcional comprueba que la declaración sea genuina; consulta Fleet Deployment.

Continuidad de Sesión

Sin reconstrucción de contexto. Una llamada recupera el panorama completo:

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

Devuelve elementos activos, transiciones recientes con atribución de actor, elementos bloqueados, elementos estancados con sus notas faltantes y cadenas completas de ancestros. Una sesión nueva tiene el estado completo en una sola respuesta.

Ilustrado: Finding Work mapea cada pregunta que una sesión tiene a la llamada de lectura que la responde, y muestra cómo se clasifica el siguiente elemento.

Notas como Contexto Estructurado

Las notas son documentación específica de fase adjunta a los elementos de trabajo. Un agente de implementación lee una nota de requisitos concisa y limitada a su tarea en lugar de escanear un contexto de proyecto más amplio.

Las notas están claveadas, limitadas por rol y son consultables:

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

Las consultas solo de metadatos (includeBody=false) permiten a los agentes verificar qué existe sin pagar el costo de tokens de cada cuerpo de nota.

Búsqueda de Texto Completo

Busca elementos de trabajo y notas por palabra clave. Los resultados se clasifican por relevancia, de modo que un agente que busca trabajo relacionado o retoma después de una larga ausencia obtiene las mejores coincidencias primero.

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

La búsqueda se puede limitar a un subárbol y filtrar por rol, etiqueta o prioridad, o ejecutarse en todo el espacio de trabajo.

API REST

Una capa HTTP opcional (API_ENABLED=true) expone elementos, notas, dependencias, transiciones, configuración y eventos SSE en tiempo real a paneles, sistemas de CI y operadores. Admite tokens bearer estáticos, autenticación JWT JWKS y el modo loopback sin autenticación que se muestra en el Inicio Rápido. También impulsa config-sync, de modo que un servidor puede servir muchos proyectos con esquemas por proyecto. Consulta la Referencia de la API REST.

Ilustrado: Runtime Map cubre las capas del servidor, ambas formas de implementación, la API REST, las declaraciones y la identidad de actor.

Filosofía de Diseño

Task Orchestrator impone la estructura del flujo de trabajo sin imponer metodología. El servidor posee las barreras de seguridad: transiciones de rol, orden de dependencias, imposición de puertas y atribución. Los agentes poseen todo lo demás. No hay ceremonias de planificación obligatorias ni opinión sobre cómo los agentes abordan la implementación. Los esquemas, traits y la autenticación de actor son capas opt-in configuradas en .taskorchestrator/config.yaml. A medida que los modelos ganan capacidades, el arnés se mantiene fuera del camino.

Plugin de Claude Code

El plugin añade automatización de flujo de trabajo sobre el servidor MCP: skills, hooks y un contexto de orquestación.

Instalación:

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

Qué añade:

Capa	Qué hace
Skills	Comandos de barra para flujos de trabajo comunes, incluyendo `/task-orchestrator:quick-start`, `/task-orchestrator:init`, `/task-orchestrator:configure-server`, `/task-orchestrator:manage-schemas` y `/task-orchestrator:create-item`
Hooks	Inyección de contexto al inicio de sesión, integración con modo plan, traspaso de contexto a subagentes, sincronización de configuración por proyecto e imposición de atribución de actor
Contexto de orquestación	Un hook de SessionStart entrega el núcleo de orquestación (con la skill `orchestrate` para detalle de nivel y delegación): Claude planifica, delega a subagentes y rastrea el progreso sin escribir código directamente

El servidor MCP funciona sin el plugin. El plugin lo hace fluido con Claude Code. Mod opcional (acceso anticipado): task-orchestrator-mod es un plugin independiente y opcional de hooks de funciones dentro del proceso: un panel de grafo de trabajo en vivo, una banda de trabajo en curso y línea de estado, y hooks retrospectivos dentro del proceso, de guardia de fase y de forma de llamada. Depende de una API de acceso anticipado de Claude Code y se combina mejor con un plugin actual de task-orchestrator.

/plugin install task-orchestrator-mod@task-orchestrator-marketplace

Ilustrado: Orquestando una ejecución sigue una característica desde la solicitud hasta los elementos terminados. Bucle de mejora muestra cómo la fricción notada durante el trabajo se convierte en un cambio de configuración revisado.

Herramientas MCP

Categoría	Herramientas	Propósito
Grafo	`manage_items`, `query_items`, `create_work_tree`, `complete_tree`	Construir y consultar la jerarquía de elementos de trabajo
Notas	`manage_notes`, `query_notes`	Documentación persistente con ámbito de fase
Dependencias	`manage_dependencies`, `query_dependencies`	Aristas tipadas con atajos de patrones (lineal, abanico de salida, abanico de entrada) y enlaces inversos
Flujo de trabajo	`advance_item`, `get_next_status`, `get_context`, `get_next_item`, `get_blocked_items`, `claim_item`	Transiciones basadas en disparadores con aplicación de compuertas, validación de dependencias y búsqueda y reclamación atómica para flotas de múltiples agentes
Configuración del proyecto	`manage_project_config`, `manage_plan_documents`	Enviar configuración de esquema por proyecto y guardar documentos de planificación antes de la creación de elementos de trabajo

Los IDs de elementos aceptan prefijos hexadecimales cortos: itemId="a3f2" funciona en lugar de un UUID completo una vez que el prefijo es inequívoco. Consulta la Referencia de API para los parámetros y formas de respuesta de cada herramienta.

Documentación

Recurso	Qué contiene
Guía de campo	Recorrido ilustrado y parcialmente interactivo de las ideas centrales. La mejor primera lectura.
Guía de inicio rápido	Recorrido completo de configuración con el primer elemento de trabajo
Referencia de API	Cada herramienta MCP: parámetros, formas de respuesta, atribución de actores
Referencia de API REST	Endpoints HTTP REST, DTOs, SSE, autenticación, merge-patch, ETag
Guía de flujo de trabajo	Esquemas, compuertas de fase, dependencias, modos de ciclo de vida
Despliegue en flota	Operadores de múltiples agentes: autenticación de API REST, identidad de actores, comprobaciones de salud, ajuste de SQLite, planificación de capacidad
Wiki	Centro de documentación completo
Registro de cambios	Historial de versiones
Contribución	Configuración del desarrollador y proceso de contribución

Pila técnica

Kotlin con Coroutines
SQLite + Exposed ORM con búsqueda de texto completo FTS5, cero configuración
Flyway migraciones de esquema versionadas
MCP Kotlin SDK con transportes STDIO y HTTP Streamable
Ktor para la API REST y SSE
Docker para despliegue con un solo comando

Una arquitectura en capas (Dominio → Aplicación → Infraestructura → Interfaces, aplicada por una prueba de Konsist contra una línea base de violaciones preexistentes con ajuste progresivo) con una amplia suite de pruebas JUnit 5.

Licencia

Licencia MIT — Gratuita para uso personal y comercial.