task-queue-mcp

Un servidor FastMCP que expone la cola de tareas de orquestación de agentes como una interfaz de herramientas MCP. Los agentes envían tareas, consultan su estado y registran finalizaciones mediante herramientas tipadas y validadas, en lugar de escrituras directas en archivos YAML.

Se ejecuta como un contenedor Docker en el puerto 8485. Se integra globalmente en ~/.claude.json para que todas las sesiones de Claude Code tengan acceso.

Herramientas

Los agentes usan la vía estricta de update_task; los operadores (mediante la API de control HTTP) usan set_task_status / cancel_task / park_task / unpark_task. Los agentes no pueden cancelar ni pausar: ambas acciones son exclusivas de operadores. amend_task es la excepción: el agente origen de la tarea puede modificarla, pero el agente destino no.

submit_task

submit_task(
    source_agent="research",
    target_agent="deploy-agent",  # agent name or "auto" for dispatcher routing
    # build | deploy | fix | research | review | audit | notify | docs |
    # ticket_audit | ticket_audit_complete
    task_type="build",
    summary="Deploy qmd update",
    description="Apply the qmd stack update from build plan...",
    risk_level="low",  # low | medium | high (default: low)
    requires_approval=False,  # explicit override of approval gate
    priority="normal",  # normal | high | urgent (default: normal)
    context_refs=["/srv/agents/build-plans/qmd/plan.md"],  # absolute paths only
    ttl_days=30,
    workflow_mode="semi-auto",  # semi-auto | auto (default: semi-auto)
    originating_task_id=None,  # UUID of the parent task, if this is a return task
)
# → {"ok": true, "task_id": "<uuid>", "filename": "<timestamp>-<slug>.yml"}

context_refs deben ser rutas absolutas. risk_level y priority se validan contra listas permitidas. workflow_mode controla el comportamiento del despachador: semi-auto (por defecto) pone la tarea en cola para que un operador la recoja, con notificación vía Matrix, mientras que auto hace que el despachador lance al agente destino sin intervención humana. El servidor genera el UUID, establece created e inicializa el stub de retry_policy.

Cierre automático de la tarea originante (desde v0.6.0)

Pasa originating_task_id y la tarea padre se cierra como completed — enviar la tarea de retorno es lo que cierra la solicitud. La respuesta incorpora auto_closed_task_id cuando se produce el cierre.

Se produce solo si se cumplen todas estas condiciones:

Por qué ambas mitades (desde v0.6.1). originating_task_id está sobrecargado: en una tarea de retorno significa "esto responde a aquella solicitud", pero en una solicitud reenviada significa "heredar workflow_mode de esta tarea padre" — que es lo que un agente de build pasa cuando registra una auditoría para su propio build en curso. Comprobar solo la primera condición no permite distinguirlos, porque la tarea de build tiene como destino al agente de build y el agente de build es quien la envía. La v0.6.0 solo incluía la primera comprobación y cerró un build en curso dentro de la misma hora.

Un retorno genuino es simétrico; una solicitud reenviada no lo es:

Una tarea padre en approved se recorre pasando por in-progress primero, de modo que su historial refleja reclamada-y-luego-cerrada, en lugar de un salto directo.

Esto es a prueba de fallos, no la vía principal. Se espera que los agentes cierren sus propias tareas explícitamente — eso deja constancia en el historial de que el agente la cerró. El cierre automático solo escribe auto-closed: return task <id> submitted en el historial. Cualquier fallo durante el cierre automático se registra como advertencia y el envío se completa con normalidad; un fallo en el cierre automático nunca puede hacer fallar el envío del que es efecto secundario.

list_tasks

list_tasks(
    target_agent="deploy-agent",  # optional
    source_agent="research",  # optional
    status="approved,in-progress",  # comma-separated, optional
    task_type="build",  # optional
    include_archived=False,  # include archive/ subdirectory
    limit=20,  # max 200
)
# → list of task dicts, sorted by created descending

Un status no reconocido es un error, no un resultado vacío (desde v0.6.0). Antes se filtraba silenciosamente, por lo que una búsqueda de status="pending" — que nunca ha sido un estado válido — devolvía [] durante meses, sin distinguirse de "no hay trabajo para ti". Una lista vacía es una respuesta legítima a una consulta bien formada, así que la única forma de distinguir un error tipográfico de una cola vacía es rechazar el error tipográfico. Se siguen tolerando espacios al inicio o final y comas finales; una cadena vacía sigue significando "sin filtro".

Las tareas en estado terminal que han superado su ttl_days se excluyen. El despachador es la autoridad en el archivado por TTL, pero list_tasks también excluye los registros finalizados de forma proactiva para que los agentes no actúen sobre elementos obsoletos.

Las tareas en estado no terminal nunca se excluyen por TTL (desde v0.8.1). Antes, el trabajo abierto desaparecía de los listados tras ttl_days aunque siguiera pendiente en disco — un punto ciego que provocó que una limpieza de cola eliminara 17 tareas varadas que la herramienta reportaba como inexistentes. Nada que siga siendo responsabilidad de alguien debería quedar oculto por un temporizador: un agente que recibe una tarea abierta obsoleta puede evaluarla y decidir, mientras que nadie puede actuar sobre una tarea que no puede ver.

Las tareas en pausa están exentas del filtro TTL. Pausar es un "pausa esto, volveré a ello" deliberado — una tarea en pausa que expirara silenciosamente del listado invalidaría el propósito mismo del estado.

get_task

get_task(task_id="a7f3d2c1-1234-5678-abcd-000000000000")
# → full task dict, or {"ok": false, "error": "not found"}

Busca primero en la cola principal y, si no la encuentra, en archive/. Requiere un UUID completo — no se admiten prefijos parciales.

update_task

update_task(
    task_id="a7f3d2c1-1234-5678-abcd-000000000000",
    status="in-progress",  # see transition table below
    actor="deploy-agent",
    note="Claimed task, starting build.",
    output=None,  # written to result.output on completed/failed
)
# → {"ok": true, "task_id": "<uuid>"} or {"ok": false, "error": "..."}

Comprobación de propiedad (desde v0.5.0): actor debe coincidir con el target_agent de la tarea, o ser "operator" — cualquier otro actor es rechazado. Esto cierra la brecha por la que un agente distinto al que tenía asignada la tarea podía reclamarla o completarla.

Transiciones válidas:

No terminales: submitted, pending-approval, approved, in-progress, parked, routing-failed. Terminales: completed, failed, cancelled.

routing-failed lo escribe el despachador y se excluye deliberadamente de la fila Cualquier no terminal → failed anterior — un agente no debe poder fallar de forma terminal una tarea que el despachador aún está reintentando. Sí es un origen normal para las transiciones de operador que se indican más abajo (cancelled, parked, anulación).

retry_policy pertenece al despachador — update_task nunca lo modifica.

Transiciones de operador (set_task_status)

Más amplio que update_task, pero igualmente auditado y acotado:

Las tareas terminales son inmutables incluso para operadores. Cada cambio de operador añade una entrada al historial con actor + note.

La vía de reparación existe porque el directorio de la cola tiene más de un escritor. Un registro cuyo estado está fuera del vocabulario de este servidor por completo — un error histórico de complete, o un estado futuro del despachador aún no admitido aquí — es inalcanzable por cualquier otra rama y quedaría permanentemente atascado. La reparación solo mueve una tarea desde un estado inválido; el destino debe seguir siendo válido, y la entrada del historial registra repaired_from. routing-failed ya no necesita esta vía — es un estado no terminal de primera clase ahora (ver arriba), alcanzable mediante las filas estándar de cancelled/parked o mediante la fila de anulación simple.

park_task / unpark_task

park_task(task_id="...", actor="operator", note="waiting on upstream fix")
# → {"ok": true, "task_id": "<uuid>"}

unpark_task(task_id="...", actor="operator", status=None)
# → returns the task to the status it was parked from

Pausar cambia únicamente el estado — el YAML nunca se mueve. La tarea sigue apareciendo en list_tasks, está exenta de la expiración por TTL y nadie la recoge, porque los bucles de recogida del despachador solo coinciden con submitted y routing-failed. El estado anterior se registra en parked_from y se limpia al salir, de modo que nunca puede quedar obsoleto. Pasa status a unpark_task para enviar la tarea a un destino distinto del que provenía — necesario para una tarea pausada por un escritor YAML directo, que no lleva parked_from.

Pausar es para "ahora no, pero no pierdas esto". Una tarea mucho tiempo inactiva no es necesariamente abandono, y parked es el vocabulario que distingue un marcador deliberado de algo genuinamente olvidado.

amend_task

amend_task(
    task_id="...",
    amendment="Preflight answered the open question — FastMCP mount() is live-linked.",
    actor="research",  # the task's source_agent, or "operator"
    reason="preflight ran after queuing",
)
# → {"ok": true, "task_id": "...", "amendment_count": 1, "agent_may_have_started": false}

Una vez que una tarea está en cola, su descripción es inmutable. Cuando algo cambia entre la puesta en cola y el inicio — un preflight responde una pregunta abierta, una dependencia se resuelve, un revisor detecta un error, el alcance se reduce — la corrección no tiene dónde ir, y un agente que confía en la descripción de su tarea hará lo incorrecto.

amend_task cierra esa brecha solo de añadidura. payload.description nunca se muta; las correcciones se acumulan bajo payload.amendments como {timestamp, actor, reason, text} y los lectores las renderizan después de la descripción. Lo que la tarea pedía originalmente permanece en el registro.

Directriz sobre ampliación del alcance: más de una o dos modificaciones en una tarea es señal de que hay que cancelar y volver a poner en cola en lugar de acumular. Los límites son una red de seguridad, no un presupuesto.

Related MCP server: task-manager-mcp

Ciclo de vida de los estados

submitted → [pending-approval] → approved → in-progress → completed
                                                 ↓
                                              failed

routing-failed  # dispatcher-written on a failed dispatch attempt; non-terminal

Any non-terminal ──(operator)──> cancelled     # graceful dismissal, record kept
Any non-terminal <──(operator)──> parked       # pause; stays listed, TTL-exempt

El despachador es el dueño de las transiciones submitted → approved/pending-approval, y también escribe routing-failed cuando falla un intento de despacho (reintenta según su propio calendario; los operadores también pueden cancelar, aparcar o forzarlo a otro estado mediante set_task_status). Los agentes son dueños de approved → in-progress → completed (o failed) — routing-failed no es alcanzable a través de update_task. Los operadores son dueños de cancelled, parked y las sobrescrituras de estado auditadas. El control de aprobación se rige por los manifiestos de los agentes y el campo requires_approval.

Toda tarea es cerrada por su propio agente destinatario. Esto se deriva de la comprobación de propiedad de update_task, y es la única regla que hay que tener en cuenta al conectar un nuevo flujo de trabajo entre agentes: el agente que envía una solicitud no puede cerrarla, porque la solicitud va dirigida a otra persona. Un par solicitud/devolución por tanto necesita que el agente receptor reclame y cierre su propia entrada — dos llamadas, ya que completed solo es alcanzable desde in-progress. El cierre automático es el mecanismo a prueba de fallos para cuando no ocurre, no un sustituto.

API de control HTTP

Los clientes que no son MCP (el plugin CloudCLI y el bot de Matrix) no pueden importar el núcleo de Python, por lo que todas sus mutaciones pasan por una API de control HTTP ligera montada como rutas personalizadas de FastMCP en el mismo puerto 8485. Cada endpoint delega en los manejadores de herramientas anteriores, heredando la validación de transiciones, el bloqueo fcntl y las escrituras atómicas — de modo que existe exactamente una ruta de escritura validada para todo el sistema.

Campos del cuerpo: note, más status / allow_override para la ruta de estado, amendment / reason para amend, status / output / on_behalf_of para update. Las respuestas reflejan el resultado canónico: 200 correcto, 404 no encontrado, 400 error de validación/transición.

actor está fijado a operator en todas estas rutas y no se lee del cuerpo (desde v0.8.0). Antes era body.get("actor", "operator") — correcto en la práctica, pero hacía que la identidad del operador fuera algo que un llamador heredaba por omisión en lugar de algo que alguien elegía. Fijarlo significa que un futuro cliente no operador aquí no puede adquirir silenciosamente la identidad que toda comprobación de propiedad exime.

El barrido del operador — POST /tasks/{id}/update

La única vía hacia una transición terminal en la tarea de otro agente. Existe porque v0.8.0 cerró la versión deshonesta: los agentes solían ordenar una tarea varada pasando el nombre de ese agente como actor, algo que vincular actor a un token portador elimina. Nada más llega a ello — set_task_status no puede hacer transiciones terminales y la herramienta update_task ahora exige la identidad resuelta — así que sin esto cada tarea extraviada requeriría la intervención manual del operador.

Pasa on_behalf_of nombrando al agente cuya tarea es. El manejador lo verifica contra el target_agent real de la tarea (una discrepancia es un 400, porque a un operador que cierra una tarea que ha identificado mal se le debe informar, no registrar el error como deliberado) y escribe ambos nombres en el historial:

history:
  - timestamp: ...
    status: completed
    actor: operator
    on_behalf_of: developer
    note: "stranded; swept during queue cleanup"

Un barrido debe leerse como un barrido años después, no como si el agente hubiera cerrado silenciosamente su propio trabajo. on_behalf_of es opcional — omitirlo es el operador actuando en su propio nombre — y se rechaza rotundamente para cualquier actor que no sea operator.

GET /queue/summary devuelve {"ok": true, "counts": {...}, "active": N, "total": N}, donde active es el total no terminal (ahora incluyendo routing-failed, contado por nombre). Los estados completamente fuera del vocabulario del servidor se agrupan bajo "unknown" en lugar de descartarse, de modo que los registros escritos por otros escritores directos de YAML permanecen visibles en el recuento.

Autenticación: las rutas personalizadas omiten la autenticación de portador del transporte, por lo que un encabezado de secreto compartido es la puerta — y estas rutas están deliberadamente fuera de ella, porque son la superficie del operador:

• Envía X-Task-Queue-Secret: $TASK_QUEUE_API_SECRET en cada mutación.

• El servidor lo compara en tiempo constante (hmac.compare_digest) y falla cerrado (401) cuando el secreto falta, es incorrecto o no está configurado.

• El secreto reside en un archivo de entorno gestionado por el operador fuera del repositorio, inyectado mediante env_file en el contenedor y en el entorno de cada cliente — nunca se confirma en el código fuente.

Despliegue

Docker (producción)

services:
  task-queue-mcp:
    image: task-queue-mcp:latest
    container_name: task-queue-mcp
    ports:
      # The loopback bind is load-bearing, not cosmetic. The MCP transport on this port
      # is unauthenticated (see Trust model below), so publishing it as "8485:8485"
      # would expose an unauthenticated queue-mutation endpoint to your whole LAN.
      - "127.0.0.1:8485:8485"
    volumes:
      - ~/.claude/task-queue:/task-queue   # host queue directory
    environment:
      - TASK_QUEUE_DIR=/task-queue
      # 0.0.0.0 here is the *container-internal* bind and must stay wide, or the port
      # mapping above has nothing to forward to. The host-side bind is what limits reach.
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8485
    cap_drop: [ALL]
    security_opt: [no-new-privileges:true]
    read_only: true
    tmpfs: [/tmp]
    user: "1000:1000"
    restart: unless-stopped
    networks:
      - agent-net

El contenedor monta solo el directorio de la cola de tareas en lectura-escritura. El resto del sistema de archivos es de solo lectura. /tmp es un tmpfs para espacio temporal transitorio.

Configuración de Claude Code settings.json

{
  "mcpServers": {
    "task-queue-mcp": {
      "type": "url",
      "url": "http://localhost:8485/mcp"
    }
  }
}

Variables de entorno

Cada agente necesita su propio token — el token es lo que identifica al llamador, así que compartir uno entre dos agentes hace que la atribución carezca de sentido. El servidor se niega a arrancar con un token compartido, un valor vacío, un token de menos de 16 caracteres, o un token acuñado para la identidad reservada de operator. Genera con:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Los llamadores lo presentan como un encabezado de portador estándar:

headers:
  Authorization: "Bearer ${TASK_QUEUE_TOKEN}"

Compilación

docker build -t task-queue-mcp:latest .

Desarrollo

Requiere Python 3.11+.

pip install -e ".[dev]"

# Lint + format (Baseline gate)
ruff check .
ruff format --check .

# Tests with coverage (gate: >=80%)
python -m pytest --cov=src --cov-report=term-missing

# Run server locally against a local task-queue directory
TASK_QUEUE_DIR=~/.claude/task-queue python -m src.server

La suite de pruebas cubre todas las herramientas y la API de control HTTP — casos límite de validación, cadenas YAML adversarias, transiciones ilegales, el ciclo de ida y vuelta park/unpark, la autorización de amend_task (incluido el agente destinatario rechazado), la auditoría de sobrescritura del operador, la reparación de estados fuera de vocabulario y la puerta del secreto compartido (secreto ausente/incorrecto → 401). Todas las escrituras usan yaml.dump — nunca interpolación de cadenas — para prevenir la inyección YAML.

Seguridad

Ambas superficies en el puerto 8485 requieren una credencial:

• Ruta de herramientas MCP (/mcp) — un token de portador por agente, verificado por el StaticTokenVerifier de FastMCP. Token ausente o desconocido → 401. El transporte se niega a arrancar sin tokens configurados, por lo que esto no puede fallar silenciosamente en abierto.

• Rutas de control HTTP (/tasks/..., /queue/summary) — un encabezado de secreto compartido (X-Task-Queue-Secret, comparación en tiempo constante, fallo cerrado). Ver API de control HTTP.

El contenedor se ejecuta como UID 1000 con cap_drop: ALL, no-new-privileges y un rootfs de solo lectura (solo /task-queue es escribible).

Modelo de confianza

Hasta v0.7.0 la ruta de herramientas MCP no estaba autenticada y el README argumentaba que loopback era una frontera de confianza suficiente. No lo era: el puerto está publicado y el contenedor se une a una red Docker compartida, por lo que todos los contenedores de esa red podían alcanzar también la ruta de herramientas. Cualquiera de ellos podía llamar a set_task_status, cancel_task, park_task, unpark_task o amend_task afirmando cualquier actor — incluido operator, que las comprobaciones de propiedad eximen explícitamente. Eso convertía completed_by y history[].actor en afirmaciones en lugar de evidencia. (vikunja#387)

v0.7.0 cierra esa vía. Cada agente posee un token distinto, por lo que el token tanto autentica al llamador como lo identifica. Deliberadamente no hay un encabezado de identidad separado: una vez que un agente posee un token puede establecer cualquier encabezado que desee en una solicitud directa, por lo que una identidad derivada del encabezado sería un segundo canal estrictamente más débil compitiendo con el derivado del token. Una sola fuente de identidad, no dos.

Qué aporta y qué no aporta. Contiene un agente equivocado o inyectado por prompt que actúa a través de su propia superficie de herramientas, y hace que el registro de auditoría signifique lo que dice. Deliberadamente no es una barrera contra un agente que busca credenciales: cuando los agentes tienen una herramienta de shell y se ejecutan como el mismo usuario del sistema operativo que posee los archivos secretos, cualquier token en el host es legible por cualquiera de ellos. Cerrar eso requiere usuarios de SO por agente o un intermediario de credenciales, y está fuera del alcance de este servidor.

La identidad operator es accesible solo desde las rutas de control HTTP. Un TASK_QUEUE_TOKEN_OPERATOR se rechaza al inicio, porque operator está exento de todas las comprobaciones de propiedad y un token que lo acuñe en el transporte orientado al agente entregaría a su titular toda la cola.

Vinculación de identidad (desde v0.8.0)

actor se deriva del token de portador, no se toma del llamante. Pasar un nombre que no coincide con la identidad autenticada se rechaza en lugar de corregirse silenciosamente: el nombre incorrecto en una llamada es un error que vale la pena señalar. Omitirlo está bien; se completa desde el token.

Esto también cubre source_agent en submit_task, que es una afirmación de identidad y no solo una etiqueta: el cierre automático en el momento del envío decide si disparar desde source_agent/target_agent, por lo que falsificarlo cerraría terminalmente la tarea de otro agente sin siquiera llamar a update_task.

set_task_status es solo para operadores porque su ruta allow_override mueve una tarea entre dos estados no terminales cualesquiera, que es como una tarea se evade una regla de transición en lugar de cumplirla. cancel_task es un juicio terminal e irreversible sobre el trabajo de otro; un agente que abandona su propia tarea la marca como failed con una razón mediante update_task.

Esquema del archivo de tareas

Las tareas son archivos YAML en ~/.claude/task-queue/, nombrados YYYYMMDD-HHMMSS-<uuid-prefix>.yml. Todas las escrituras son atómicas (escribir a .tmp, luego os.rename()). Los bloqueos de archivo por tarea mediante fcntl.flock evitan condiciones de carrera entre llamadas MCP concurrentes y el despachador.

Para la documentación completa del esquema y el ciclo de vida, consulte el documento de componente homelab-agent.

Relacionados

• homelab-agent — documentación de orquestación de agentes

• task-dispatcher — el despachador que enruta y controla las tareas