convez.ai
MCP ServerAutomaçãoAvançado
TadMSTR

Task Queue MCP

TadMSTR/task-queue-mcp

Fila de tarefas estruturada para orquestração de agentes Claude

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP baseado em FastMCP que expõe uma fila de tarefas para orquestração de agentes como interface de ferramentas tipadas. Agentes enviam, consultam status e registram conclusões de tarefas através de tools validados em vez de escritas brutas em YAML.

Instalação

$npx convez-ai TadMSTR/task-queue-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 2 semanas
Versão
v0.16.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Orquestração de fluxos multi-agente com rastreamento de estado
  • Submissão e monitoramento de tarefas assíncronas entre agentes
  • Gerenciamento de aprovações e prioridades em pipelines de automação

Veredito

Solução robusta e tipada para orquestração de agentes em arquiteturas multi-agente. Bem adequado para fluxos complexos que precisam de controle de estado, aprovações e rastreamento de histórico; requer setup Docker e integração em ~./claude.json.

README

A tradução para o português deste README ainda está na fila.

task-queue-mcp

A FastMCP server that exposes the agent orchestration task queue as an MCP tool interface. Agents submit tasks, check status, and record completions through typed, validated tools instead of raw YAML file writes.

Runs as a Docker container on port 8485. Wired globally into ~/.claude.json so all Claude Code agent sessions have access.

Tools

ToolDescription
submit_taskCreate a new task with status: submitted
list_tasksList tasks with optional filters; TTL-expired tasks excluded
get_taskRetrieve a single task by UUID
update_taskTransition status and append a history entry

submit_task

submit_task(
    source_agent="research",
    target_agent="claudebox",       # agent name or "auto" for dispatcher routing
    task_type="build",              # build | deploy | fix | research | review | audit | notify
    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=["/home/ted/.claude/projects/research/build-plans/qmd/plan.md"],
    ttl_days=30,
    workflow_mode="semi-auto",          # semi-auto | auto (default: semi-auto)
)
# → {"ok": true, "task_id": "<uuid>", "filename": "<timestamp>-<slug>.yml"}

context_refs must be absolute paths. risk_level and priority are validated against allowlists. workflow_mode controls dispatcher behavior: semi-auto (default) queues the task for operator pickup with a Matrix notification, while auto triggers the dispatcher to launch the target agent headlessly. The server generates the UUID, sets created, and initializes alert_state and retry_policy stubs.

list_tasks

list_tasks(
    target_agent="claudebox",       # 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

Tasks past their ttl_days are excluded. The dispatcher is authoritative for TTL archiving, but list_tasks filters them out proactively so agents don't act on stale items.

get_task

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

Searches the main queue first, then archive/. Requires a full UUID — no prefix matching.

update_task

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

Valid transitions:

FromTo
approvedin-progress
in-progresscompleted
Any non-terminalfailed

Non-terminal: submitted, pending-approval, approved, in-progress. Terminal: completed, failed.

alert_state and retry_policy are dispatcher-owned — update_task never touches them.

Status Lifecycle

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

The dispatcher owns the submitted → approved/pending-approval transitions. Agents own approved → in-progress → completed (or failed). Approval gating is controlled by agent manifests and the requires_approval field.

Deployment

Docker (production)

services:
  task-queue-mcp:
    image: task-queue-mcp:latest
    container_name: task-queue-mcp
    ports:
      - "8485:8485"
    volumes:
      - /home/ted/.claude/task-queue:/task-queue
    environment:
      - TASK_QUEUE_DIR=/task-queue
      - 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:
      - claudebox-net

The container mounts only the task-queue directory read-write. The rest of the filesystem is read-only. /tmp is a tmpfs for transient scratch space.

Claude Code settings.json

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

Environment Variables

VariableDefaultDescription
TASK_QUEUE_DIR/task-queuePath to the task queue directory inside the container
MCP_HOST0.0.0.0Bind host for the HTTP server
MCP_PORT8485Port for the HTTP server

Building

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

Development

pip install -r requirements.txt

# Run tests
pytest

# Run server locally (against a local task-queue directory)
TASK_QUEUE_DIR=/home/ted/.claude/task-queue python -m src.server

The test suite (21 tests) covers all four tools including validation edge cases and adversarial YAML strings. All writes use yaml.dump — never string interpolation — to prevent YAML injection.

Security

Port 8485 is unauthenticated. Access is limited to LAN only — the port is not proxied externally via SWAG and the host firewall blocks external access. The container runs as UID 1000 with cap_drop: ALL and no-new-privileges.

Task File Schema

Tasks are YAML files in ~/.claude/task-queue/, named YYYYMMDD-HHMMSS-<uuid-prefix>.yml. All writes are atomic (write to .tmp, then os.rename()). Per-task file locks via fcntl.flock prevent races between concurrent MCP calls and the dispatcher.

For the full schema and lifecycle documentation, see the homelab-agent component doc.

Related

Ver o original no GitHub

Bom para

Relacionados