MCP Task Orchestrator

Um servidor MCP em Kotlin para gerenciamento abrangente de tarefas, permitindo que assistentes de IA interajam com dados de projetos.

GitHub

209

Documentação

MCP Task Orchestrator

Disciplina de fluxo de trabalho imposta pelo servidor para agentes de IA.

Frameworks baseados em prompts esperam que o LLM siga instruções. Este bloqueia a chamada se ele não seguir.

Task Orchestrator é um servidor MCP que dá aos agentes de codificação de IA um grafo persistente de itens de trabalho com portões de qualidade aplicados pelo servidor, não pelo prompt. Ele é construído para desenvolvedores que executam fluxos de codificação multiagente ou multissessão: um orquestrador despachando subagentes, uma nova sessão retomando o trabalho de ontem, ou um loop autônomo drenando um backlog. Ele é distribuído como uma imagem Docker, funciona com qualquer cliente MCP e tem um plugin opcional para Claude Code que adiciona skills e hooks por cima.

Novo aqui? Comece com o guia ilustrado de campo. Ele explica as ideias desta página em páginas visuais curtas, várias delas interativas: dispare triggers em um portão de fase, clique em uma estrutura de trabalho através de suas dependências e veja um schema ser resolvido.

O Problema

Fluxos de trabalho multiagente precisam de infraestrutura que o modelo não fornece. Quando um orquestrador despacha subagentes entre sessões, não há uma forma nativa de impor qual documentação deve existir antes do trabalho começar, rastrear qual agente fez qual alteração ou garantir a ordenação de dependências em uma estrutura de trabalho. Essas são preocupações estruturais — elas pertencem ao servidor, não aos prompts.

Task Orchestrator as coloca no servidor. Se uma nota de design obrigatória não estiver preenchida, advance_item retorna um erro nomeando a nota ausente. Se uma dependência upstream não estiver completa, a transição é bloqueada. Cada transição e nota registra quem a fez. Uma nova sessão recupera o estado completo em uma única chamada em vez de reproduzir uma conversa. E as regras são configuração YAML, não prompts fixos — altere-as sem mudar o código.

Como Ele Se Parece

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.

Início Rápido

Pré-requisito: Docker instalado e em execução.

1. Registre o servidor

A configuração mais simples é um contêiner STDIO por sessão: sem porta, sem daemon, sem API REST. Adicione-o ao .mcp.json do seu projeto:

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

Usuários do Claude Code podem registrar o mesmo formato pela 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"]
}'

Reinicie seu cliente. O servidor cria seu banco de dados SQLite na primeira execução. Sem um arquivo de configuração, toda ferramenta funciona no modo sem schema: sem portões, sem notas obrigatórias. Adicione schemas quando quiser a aplicação de regras.

2. Ative os schemas de fluxo de trabalho

Crie .taskorchestrator/config.yaml no seu projeto (veja Aplicação de Fluxo de Trabalho para um exemplo, ou use a skill /task-orchestrator:manage-schemas do plugin) e monte essa pasta no contêiner:

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

Use um caminho absoluto do host. O .mcp.json do Claude Code expande apenas variáveis de ambiente (${VAR} e ${VAR:-default}), então placeholders no estilo de editor como ${workspaceFolder} não são substituídos. Apenas a pasta .taskorchestrator/ é exposta; o servidor não tem acesso ao restante do seu projeto.

3. Configuração multiprojeto (HTTP + sincronização de configuração)

Se você trabalha em vários repositórios, execute um servidor persistente com a API REST habilitada. O .taskorchestrator/config.yaml de cada projeto então sincroniza automaticamente através do hook config-sync do plugin: sem contêiner por projeto, sem montagem manual, e alterações de configuração são recarregadas a quente sem reinicialização. A skill /task-orchestrator:configure-server do plugin renderiza essa configuração interativamente; o equivalente manual é:

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

Registre-o no .mcp.json usando o formato HTTP:

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

E exporte a variável do lado do cliente que informa ao config-sync onde o servidor está (sem ela, a sincronização de configuração silenciosamente não faz nada):

export TASK_ORCHESTRATOR_API_URL=http://localhost:3001

Alternativamente, um client.json (somente apiUrl, sem token) fornece a URL. O /task-orchestrator:init em modo projeto a escreve ao lado da configuração do projeto, apenas para um servidor loopback e somente como uma origem simples sem caminho, consulta ou fragmento (adicione .taskorchestrator/client.json ao .gitignore, a URL é específica da máquina); o /task-orchestrator:init --user escreve o arquivo de nível de usuário, que funciona para qualquer host. A ordem é a variável de ambiente, depois o arquivo de nível de projeto, depois o arquivo de nível de usuário. O /task-orchestrator:init configura uma raiz de projeto para o diretório atual, e o /task-orchestrator:init --user cria uma raiz pessoal que atende a todos os diretórios sem configuração própria.

SEGURANÇA: REST não autenticado significa que qualquer pessoa que alcance a porta tem acesso total de leitura/escrita/exclusão. Isso só é seguro porque a porta é publicada somente em loopback (-p 127.0.0.1:3001:3001). Nunca a publique em 0.0.0.0 ou em uma interface mais ampla. Para implantações compartilhadas ou em rede, use tokens bearer ou autenticação JWKS — veja Implantação em Frota.

Prefere executar sem Docker? O CONTRIBUTING.md cobre a construção do fat JAR a partir do código-fonte.

Capacidades Principais

O Modelo de Fases

Cada item de trabalho tem um papel: queue (não iniciado), work (em andamento), review (opcional, opt-in por schema), blocked (uma dependência upstream não atendida) e terminal (concluído ou cancelado). Cada papel mapeia para um ou mais status configuráveis. Agentes movem itens com advance_item(trigger=...) em vez de editar o status diretamente, e é nessa chamada que cada portão é verificado. Schemas anexam requisitos de notas aos papéis: uma nota declarada com role: queue deve existir antes que o item possa sair da fase de fila.

Ilustrado: Portões de Fase desenha os papéis e triggers como uma trilha e inclui um simulador de portões.

Aplicação de Fluxo de Trabalho

Schemas definem o que os agentes devem produzir em cada fase, e o servidor bloqueia a progressão até que isso seja feito. Eles também definem um piso de planejamento: quando um agente entra no modo de planejamento, o schema informa qual documentação deve existir antes que a implementação possa começar, moldando o próprio plano.

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

Com este schema, advance_item(trigger="start") da fila exige que requirements esteja preenchido. O servidor retorna um erro listando exatamente quais notas estão ausentes.

O campo guidance fornece instruções de autoria exibidas no momento certo: quando um agente está prestes a preencher essa nota, a resposta carrega a orientação como um guidancePointer. O campo skill vai além, nomeando uma skill que o agente deve invocar antes de preencher a nota, para que a avaliação siga um framework definido em vez de prosa livre.

Traits Composáveis

Traits adicionam requisitos de notas transversais a qualquer schema sem duplicar definições. Defina um trait uma vez, aplique-o a qualquer tipo de item:

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

Todo item feature-task herda automaticamente o requisito security-assessment. Traits também podem ser aplicados por item via o parâmetro traits em manage_items, então uma tarefa que toca autenticação recebe needs-security-review enquanto uma limpeza de CSS não.

Ilustrado: Schemas e Traits mostra como um tipo, seus traits padrão e traits por item se resolvem em um único portão. Assentos cobre a divisão de uma fase entre vários agentes.

Grafo Persistente de Itens de Trabalho

Tudo é um WorkItem em um grafo hierárquico. Itens se aninham em qualquer profundidade e são conectados por arestas de dependência tipadas. Crie uma estrutura de trabalho inteira atomicamente:

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

Quando schema atinge o estado terminal, api é automaticamente desbloqueado. Quando todos os filhos são concluídos, o pai em cascata atinge o estado terminal. A ordenação de dependências é aplicada pelo servidor, estruturalmente, não por convenção.

Ilustrado: Grafo de Trabalho tem uma versão clicável desta árvore que mostra bloqueio, desbloqueio e cascatas de pais.

Atribuição de Ator

Toda transição advance_item e upsert manage_notes aceita uma declaração de ator opcional, e o servidor a registra na transição ou nota:

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

As respostas de consulta incluem a cadeia completa de delegação: qual orquestrador despachou qual subagente, quem escreveu qual nota, quem fez qual transição. A depuração pós-mortem se torna uma consulta de dados em vez de arqueologia de conversa.

Para tornar a declaração obrigatória, habilite a autenticação de ator na configuração:

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

Com o plugin Claude Code instalado, um hook então rejeita qualquer escrita sem ator antes que a chamada saia do cliente. Outros clientes MCP precisam fornecer a declaração por convenção. A verificação opcional JWKS confirma que a declaração é genuína; veja Implantação em Frota.

Continuidade de Sessão

Sem reconstrução de contexto. Uma chamada recupera o quadro completo:

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

Retorna itens ativos, transições recentes com atribuição de ator, itens bloqueados, itens parados com suas notas ausentes e cadeias completas de ancestrais. Uma nova sessão tem estado completo em uma única resposta.

Ilustrado: Encontrando Trabalho mapeia cada pergunta que uma sessão tem para a chamada de leitura que a responde e mostra como o próximo item é classificado.

Notas como Contexto Estruturado

Notas são documentação específica de fase anexada a itens de trabalho. Um agente de implementação lê uma nota de requisitos concisa, escopada à sua tarefa, em vez de escanear contexto mais amplo do projeto.

Notas são chaveadas, escopadas por papel e consultáveis:

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

Consultas somente de metadados (includeBody=false) permitem que agentes verifiquem o que existe sem pagar o custo de tokens de cada corpo de nota.

Busca em Texto Completo

Busque itens de trabalho e notas por palavra-chave. Os resultados são classificados por relevância, então um agente procurando trabalho relacionado ou retomando após uma longa ausência obtém as melhores correspondências primeiro.

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

A busca pode ser escopada a uma subárvore e filtrada por papel, tag ou prioridade, ou executada em todo o workspace.

API REST

Uma camada HTTP opcional (API_ENABLED=true) expõe itens, notas, dependências, transições, configuração e eventos SSE em tempo real para dashboards, sistemas de CI e operadores. Ela suporta tokens bearer estáticos, autenticação JWT JWKS e o modo loopback não autenticado mostrado no Início Rápido. Ela também alimenta o config-sync, então um servidor pode atender muitos projetos com schemas por projeto. Veja a Referência da API REST.

Ilustrado: Mapa de Runtime cobre as camadas do servidor, ambas as formas de implantação, a API REST, declarações e identidade de ator.

Filosofia de Design

Task Orchestrator aplica estrutura de fluxo de trabalho sem impor metodologia. O servidor é dono das proteções: transições de papel, ordenação de dependências, aplicação de portões e atribuição. Os agentes são donos de todo o resto. Não há cerimônias obrigatórias de planejamento e nenhuma opinião sobre como os agentes abordam a implementação. Schemas, traits e autenticação de ator são camadas opt-in configuradas em .taskorchestrator/config.yaml. À medida que os modelos ganham capacidades, a estrutura fica fora do caminho.

Plugin Claude Code

O plugin adiciona automação de fluxo de trabalho por cima do servidor MCP: skills, hooks e um contexto de orquestração.

Instalação:

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

O que ele adiciona:

Camada	O que faz
Skills	Comandos de barra para fluxos de trabalho comuns, incluindo `/task-orchestrator:quick-start`, `/task-orchestrator:init`, `/task-orchestrator:configure-server`, `/task-orchestrator:manage-schemas` e `/task-orchestrator:create-item`
Hooks	Injeção de contexto no início da sessão, integração com modo de planejamento, transferência de contexto de subagente, sincronização de configuração por projeto e aplicação de atribuição de ator
Contexto de orquestração	Um hook SessionStart entrega o núcleo de orquestração (com a skill `orchestrate` para detalhes de nível e delegação): Claude planeja, delega a subagentes e acompanha o progresso sem escrever código diretamente

O servidor MCP funciona sem o plugin. O plugin o torna perfeito com Claude Code. Mod opcional (acesso antecipado): task-orchestrator-mod é um plugin separado e opcional de hooks de funções em processo: um painel de grafo de trabalho ao vivo, uma faixa de itens em andamento e linha de status, e hooks retrospectivos em processo, de guarda de fase e de formato de chamada. Ele depende de uma API de acesso antecipado do Claude Code e é melhor utilizado em conjunto com o plugin atual do task-orchestrator.

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

Ilustrado: Orquestrando uma Execução acompanha um recurso desde a solicitação até os itens concluídos. Loop de Melhoria mostra como o atrito percebido durante o trabalho se torna uma mudança de configuração revisada.

Ferramentas MCP

Categoria	Ferramentas	Propósito
Grafo	`manage_items`, `query_items`, `create_work_tree`, `complete_tree`	Construir e consultar a hierarquia de itens de trabalho
Notas	`manage_notes`, `query_notes`	Documentação persistente com escopo de fase
Dependências	`manage_dependencies`, `query_dependencies`	Arestas tipadas com atalhos de padrão (linear, fan-out, fan-in) e backlinks
Fluxo de trabalho	`advance_item`, `get_next_status`, `get_context`, `get_next_item`, `get_blocked_items`, `claim_item`	Transições baseadas em gatilhos com aplicação de portões, validação de dependências e busca e reivindicação atômicas para frotas multiagentes
Configuração do projeto	`manage_project_config`, `manage_plan_documents`	Enviar configuração de esquema por projeto e armazenar documentos de planejamento antes da criação de itens de trabalho

IDs de itens aceitam prefixos hexadecimais curtos: itemId="a3f2" funciona no lugar de um UUID completo quando o prefixo é inequívoco. Consulte a Referência da API para os parâmetros e formatos de resposta de cada ferramenta.

Documentação

Recurso	O que contém
Guia de Campo	Passo a passo ilustrado e parcialmente interativo das ideias centrais. A melhor primeira leitura.
Guia de Início Rápido	Passo a passo completo de configuração com o primeiro item de trabalho
Referência da API	Cada ferramenta MCP: parâmetros, formatos de resposta, atribuição de atores
Referência da API REST	Endpoints HTTP REST, DTOs, SSE, autenticação, merge-patch, ETag
Guia de Fluxo de Trabalho	Esquemas, portões de fase, dependências, modos de ciclo de vida
Implantação em Frota	Operadores multiagentes: autenticação da API REST, identidade de atores, verificações de saúde, ajuste de SQLite, planejamento de capacidade
Wiki	Hub completo de documentação
Changelog	Histórico de versões
Contribuindo	Configuração do desenvolvedor e processo de contribuição

Stack Técnica

Kotlin com Coroutines
SQLite + Exposed ORM com pesquisa de texto completo FTS5, zero configuração
Flyway para migrações de esquema versionadas
MCP Kotlin SDK com transportes STDIO e HTTP Streamable
Ktor para a API REST e SSE
Docker para implantação com um comando

Uma arquitetura em camadas (Domínio → Aplicação → Infraestrutura → Interfaces, aplicada por um teste Konsist contra uma linha de base ratcheting de violações pré-existentes) com uma suíte de testes extensa em JUnit 5.

Licença

Licença MIT — Gratuita para uso pessoal e comercial.