DEVS-LOOP MCP

Pacote distribuivel do devs-loop para uso pessoal via MCP e CLI.

Release 0.5.1

Principais mudancas desta release:

• microtasks mais seguras: a consolidacao agora considera tipo, tamanho, semantica e impacto estrutural, em vez de depender so do tempo real

• subtasks estruturais preservadas: frentes de infra/runtime/deploy/banco deixam de ser consolidadas automaticamente quando representam bloco executivo proprio

• fix critico: corrige boot do servidor MCP via CLI — devs-loop server agora conecta o transport stdio corretamente, resolvendo MCP error -32000: Connection closed em Cursor, Codex, Windsurf, Antigravity e Claude

• elimina falhas silenciosas: startTimer, markTaskInProgress, updateTaskStatus, completeTask e funcoes de sessao agora logam warnings e retornam resultados em vez de engolir erros

• auto-init de sessao: create_task inicializa sessao local automaticamente se nao existir, e erros de timer nao abortam mais a criacao

• telemetria real: resposta de create_task agora inclui lifecycle (timerStartedRemote, statusChanged, sessionTracking) e warnings para o agente comunicar ao usuario

• protocolo atualizado: server instructions e devs-loop.md agora documentam init_session como passo 0 obrigatorio e orientam verificacao de lifecycle

Publish

Fonte de verdade operacional desta release: C:\Users\User\.devs-loop\package-local.

Para empacotar ou publicar, execute os comandos com workdir em C:\Users\User\.devs-loop\package-local. Rodar npm --prefix ... pack a partir de outro projeto pode empacotar o diretório errado.

Modos de uso

• CLI local: devs-loop ...
• MCP pessoal local: devs-loop-mcp

Servidor MCP

O servidor MCP expoe o core do devs-loop por stdio, reaproveitando as regras de:

• resolucao de lista
• criacao de tasks
• controle de timer
• resumo de sessao
• progresso entre sessoes, confirmado no log local e no ClickUp

Instalar dependencias

npm install

Estrutura de configuracao

Este pacote foi preparado para funcionar em qualquer maquina sem depender do diretorio do projeto original.

Ordem de resolucao:

1. ./.devs-loop/ no projeto atual
2. ~/.devs-loop/ no usuario atual
3. defaults do pacote publicado

Arquivos pessoais recomendados:

• ~/.devs-loop/.env
• ~/.devs-loop/auth.json
• ~/.devs-loop/config.json
• ~/.devs-loop/learnings.json

Importante para agentes e usuarios:

• ~/.devs-loop/.env e ~/.devs-loop/auth.json representam a configuracao global do usuario
• ./.devs-loop/.env representa configuracao especifica do projeto
• devs-loop-progress.md, devs-loop-session-history.md e .devs-loop/.session.json representam estado e historico da sessao, nao a existencia de credencial
• portanto, ausencia de arquivos de sessao na raiz do projeto nao significa ausencia de configuracao do ClickUp
• antes de afirmar que "nao ha configuracao", e preciso checar global e projeto separadamente
• se a verificacao continuar ambigua, a resposta correta e perguntar ao usuario em vez de assumir

Exemplo de ~/.devs-loop/.env:

CLICKUP_API_TOKEN=pk_xxx
[email protected]

Modos de autenticacao

O pacote agora aceita tres formas de autenticacao, nesta ordem de prioridade:

1. auth local por usuario salvo pelo proprio devs-loop
2. variavel CLICKUP_OAUTH_ACCESS_TOKEN
3. fallback legado por CLICKUP_API_TOKEN

Isso permite que cada usuario use sua propria credencial individual sem quebrar o modo antigo.

Se o .env tiver apenas CLICKUP_API_TOKEN e o CLI estiver rodando em terminal interativo, o pacote agora pergunta qual modo o usuario quer usar naquele ambiente:

• API oficial com token pessoal
• session_http via requests privados da sessao web
• OAuth

A escolha fica persistida em auth.json para evitar perguntas repetidas a cada comando.

Tambem existe o modo opcional session_http, nao oficial:

• abre navegador local
• o usuario faz login na propria conta ClickUp
• o pacote captura os headers da sessao autenticada
• as requests HTTP passam a reutilizar essa sessao localmente

Esse modo e mais autonomo para o usuario, mas depende do comportamento atual do frontend do ClickUp e pode exigir manutencao quando a sessao web mudar.

Regra explicita:

• session_http nao pode usar a API oficial /api/v2
• se esse modo estiver ativo, o cliente oficial do pacote bloqueia a chamada com erro
• esse modo so deve operar com transporte HTTP privado da sessao web do ClickUp

Session HTTP privado

O pacote agora tem:

• abstracao de cliente ClickUp que escolhe o transporte conforme o modo de auth
• capturador guiado de requests privadas do frontend do ClickUp
• cliente session_http com cobertura do fluxo principal do devs-loop:
  • current user
  • task
  • list
  • listagem remota de tasks da lista
  • create task
  • comment
  • assign task
  • create checklist
  • create checklist item
  • update checklist item
  • update task metadata
    • priority
    • custom_type
    • parent
  • update status
  • timer start/stop
  • create time entry
  • delete task
  • attachment
  • criacao de hierarquia pai + subtarefas no fluxo de alto nivel

As operacoes acima agora priorizam rotas privadas embutidas e fallback por inferencia conservadora. No fluxo principal do pacote, a captura de templates deixou de ser pre-requisito e passa a ser contingencia para diagnostico, drift do frontend ou recuperacao de compatibilidade.

Sem misturar com /api/v2, o pacote agora consegue no modo session_http:

• criar task com tipo, prioridade e checklist nativa
• criar subtarefa real vinculada a task pai
• concluir task com resolucao de checklist nativa
• validar status, time_spent e assignee pelo proprio cliente abstrato

Regra forte para API oficial

Quando o fluxo usar a API oficial do ClickUp:

• primeiro consultar GET /api/v2/list/{list_id}/field
• depois enviar apenas os custom fields realmente expostos naquela lista
• e separar obrigatoriamente:
  • custom_item_id para tipo visual/icone da task
  • custom fields de negocio para classificacao interna

Isso evita dois erros comuns:

• mandar payload de custom field no formato errado para a lista
• acreditar que preencher tipos_tarefas ja muda o icone da task, quando isso depende de custom_item_id

Regra operacional:

• se a API oficial devolver erro de schema como Value must be an array, o agente deve revisar o type do campo e parar de insistir no payload errado
• se houver divergencia entre config.json e os campos expostos pela lista, o agente deve explicar a divergencia e pedir confirmacao ao usuario antes de seguir

Fluxo sugerido:

1. autenticar a sessao web:

devs-loop auth login --email [email protected]

2. usar normalmente o CLI/MCP.

3. se alguma operacao privada especifica quebrar por mudanca no frontend do ClickUp, capturar templates privados base como contingencia:

devs-loop auth session-capture --operation current_user
devs-loop auth session-capture --operation task --task-id abc123 --workspace-id 90132741067
devs-loop auth session-capture --operation list --list-id 123 --workspace-id 90132741067
devs-loop auth session-capture --operation create_task --list-id 123 --workspace-id 90132741067
devs-loop auth session-capture --operation comment --task-id abc123 --workspace-id 90132741067
devs-loop auth session-capture --operation assign_task --task-id abc123 --workspace-id 90132741067 --assignee-id 111945169
devs-loop auth session-capture --operation update_status --task-id abc123 --workspace-id 90132741067 --status "em andamento"
devs-loop auth session-capture --operation timer_start --task-id abc123 --workspace-id 90132741067
devs-loop auth session-capture --operation timer_stop --workspace-id 90132741067
devs-loop auth session-capture --operation attachment --task-id abc123 --workspace-id 90132741067

As operacoes abaixo ja tem rota privada embutida no pacote e nao dependem de template capturado:

• current user
• task
• list
• create task
• comment
• assign task
• update task metadata (priority, custom_type, parent)
• update status
• create checklist
• create checklist item
• update checklist item
• timer start
• timer stop
• create time entry
• attachment
• listagem de tasks da lista
• delete task

4. testar o cliente abstrato:

devs-loop http current-user
devs-loop http list --list-id 123 --workspace-id 90132741067
devs-loop http create-task --list-id 123 --name "Task de teste" --workspace-id 90132741067
devs-loop http comment --task-id abc123 --comment "Teste" --workspace-id 90132741067

Exemplos via CLI:

devs-loop auth personal --token pk_xxx --email [email protected]
devs-loop auth select
devs-loop auth login --email [email protected]
devs-loop auth oauth-token --token access_xxx --email [email protected]
devs-loop auth status
devs-loop auth clear

Fluxo OAuth:

devs-loop auth oauth-url --client-id SEU_CLIENT_ID --redirect-uri https://seu-app/callback
devs-loop auth oauth-exchange --client-id SEU_CLIENT_ID --client-secret SEU_CLIENT_SECRET --code CODIGO --redirect-uri https://seu-app/callback

Bootstrap em uma maquina nova

npx -y @renatocostaguedesdemorais/devs-loop-mcp install

Esse comando:

• cria ou reutiliza ~/.devs-loop/
• copia config.json e .env.example para o diretorio pessoal se ainda nao existirem
• cria learnings.json e devs-loop-progress.md quando necessario
• sincroniza no projeto atual:
  • AGENTS.md
  • CLAUDE.md
  • .cursorrules
  • .windsurfrules
  • .agents/skills/devs-loop/SKILL.md

Depois disso, basta preencher ~/.devs-loop/.env com:

CLICKUP_API_TOKEN=pk_xxx
[email protected]

Iniciar o servidor MCP

npx -y @renatocostaguedesdemorais/devs-loop-mcp server

Ou:

npm run mcp

Exemplo de configuracao MCP local

{
  "mcpServers": {
    "devs-loop": {
      "command": "npx",
      "args": [
        "-y",
        "@renatocostaguedesdemorais/devs-loop-mcp",
        "server"
      ]
    }
  }
}

Configuracao pronta nesta maquina

Os dois editores abaixo ja foram configurados nesta maquina para usar o servidor MCP local do devs-loop:

• C:\Users\User\AppData\Roaming\Antigravity\User\settings.json
• C:\Users\User\AppData\Roaming\Cursor\User\settings.json

Entrada configurada:

{
  "mcpServers": {
    "devs-loop": {
      "command": "npx",
      "args": [
        "-y",
        "@renatocostaguedesdemorais/devs-loop-mcp",
        "server"
      ]
    }
  }
}

Tools disponiveis

• devs_loop_auth_status
• devs_loop_auth_select_mode
• devs_loop_auth_session_login
• devs_loop_auth_session_refresh
• devs_loop_auth_session_capture_private_request
• devs_loop_auth_use_personal_token
• devs_loop_auth_use_oauth_token
• devs_loop_auth_oauth_authorization_url
• devs_loop_auth_oauth_exchange_code
• devs_loop_auth_clear
• devs_loop_attach_file
• devs_loop_find_similar_tasks
• devs_loop_session_http_current_user
• devs_loop_session_http_get_list
• devs_loop_session_http_create_task
• devs_loop_session_http_comment
• devs_loop_session_http_validate_task
• devs_loop_coach_check
• devs_loop_coach
• devs_loop_learn_rule
• devs_loop_learn_preference
• devs_loop_learn_issue
• devs_loop_learn_stats
• devs_loop_learn_context
• devs_loop_projects
• devs_loop_sync
• devs_loop_suggest_list
• devs_loop_recent_progress
• devs_loop_init_session
• devs_loop_preflight_create_task
• devs_loop_preflight_complete_task
• devs_loop_create_task
• devs_loop_complete_task
• devs_loop_timer
• devs_loop_summary
• devs_loop_end_session

Fluxo esperado

1. Consultar listas e progresso recente
2. Iniciar sessao
3. Criar task ativa ou hierarquia pai + subtarefas
4. Trabalhar com timer ativo
5. Concluir task e checklist
6. Encerrar sessao e registrar em devs-loop-progress.md

Historico visual da sessao

Enquanto a sessao estiver ativa, o pacote agora atualiza automaticamente na raiz do projeto:

• devs-loop-session-history.md

Esse arquivo funciona como painel vivo da sessao e mostra:

• visao geral da sessao atual
• tarefas abertas e concluidas
• tempo estimado medio, tempo rastreado final e tempo real em separado
• linha do tempo das alteracoes feitas no ClickUp
• uso revisado do MCP durante a sessao

O historico de longo prazo continua sendo append-only em:

• devs-loop-progress.md

Smoke tests

Rodar a suite minima local:

npm run test:smoke

Cobertura atual:

• sessao, timer e resumo
• create task com checklist nativa
• create task com tipo, prioridade e checklist nativa tambem no modo session_http
• complete task com resolucao de checklist e sincronizacao de tempo
• estimativa contextual de tempo estimado medio para cenarios recorrentes de infraestrutura e deploy
• create/complete completos tambem no modo session_http, incluindo checklist nativa, assignee, time entry complementar e auto-complete da task pai
• hierarquia pai + subtarefas via core e MCP
• validacao final via cliente abstrato para status, time_spent e assignee
• anexos automaticos com comentario de confirmacao
• progresso recente combinando log local e contexto remoto do ClickUp
• revisao de pendencias apos done, com pausa automatica de timer remanescente

Hierarquia de tasks

O fluxo de alto nivel agora aceita criar pai + subtarefas em uma unica chamada:

• no MCP: devs_loop_create_task com subtasks
• no CLI: devs-loop task --subtasks-file caminho.json

Regras atuais:

• a task raiz e normalizada para tamanho G
• subtarefas sao ordenadas automaticamente em ordem pratica: Spike -> Infra -> Feature/Bug -> Refactor -> Doc -> QA
• quando ha subtarefas, o timer sobe na primeira subtarefa criada
• o suporte pai/filho continua sujeito a consolidacao de microtask quando uma subtarefa fecha abaixo do limite configurado

Exemplo de arquivo JSON para --subtasks-file:

[
  {
    "name": "Investigar dependencias do fluxo",
    "type": "Spike",
    "size": "P",
    "checklist": ["Dependencias mapeadas"]
  },
  {
    "name": "Implementar fluxo principal",
    "type": "Feature",
    "size": "M",
    "checklist": ["Fluxo principal implementado"]
  },
  {
    "name": "Validar fluxo final",
    "type": "QA",
    "size": "P",
    "checklist": ["Validacao final concluida"]
  }
]

Os smoke tests usam mocks do ClickUp para serem repetiveis e baratos de rodar antes do publish.

Regras operacionais adicionais

• Antes de afirmar que nao existe contexto recente, o pacote cruza devs-loop-progress.md com tasks recentes do projeto no ClickUp para reduzir inconsistencias entre log local e estado remoto.
• Observacoes deve sempre sair preenchido com contexto util. Se nada especifico for informado, o core gera um texto padrao com projeto, iniciativa e orientacao de atualizacao.
• Toda task deve ficar atribuida ao dev. O create agora falha se o assignee nao puder ser resolvido, e o start/complete revalidam a atribuicao.
• Subtarefas continuam podendo ser tratadas como microtasks abaixo de 10min, mas a consolidacao nao depende mais so do tempo real: tipo, tamanho, semantica e impacto estrutural tambem entram na decisao.
• Subtasks estruturais, especialmente de Infra, Feature ou Bug, com sinais de runtime, deploy, banco, secrets, cron, VPS ou producao deixam de ser consolidadas automaticamente mesmo quando o tempo real foi baixo.
• Quando uma microtask fecha, o registro e consolidado na task pai no resumo da sessao e no log de progresso, em vez de contar como entrega separada.
• Quando uma microtask e consolidada, o pacote limpa o rastro operacional dela no ClickUp removendo a subtarefa consolidada da arvore para evitar ambiguidade visual.
• Ao consolidar, o pacote preserva as informacoes individuais da microtask na task pai em comentario estruturado, incluindo nome, tipo, descricao, observacoes, checklist e tempo.
• Ao concluir uma task, o pacote diferencia tempo real do timer e tempo rastreado, que passa a representar um total simulado/estimado para a entrega.
• Quando nao existe tempo real medido, o tempo estimado medio agora tambem usa heuristica contextual baseada em nome, descricao e observacoes da task para evitar estimativas uniformes em cenarios tecnicamente diferentes.
• As regras contextuais atuais priorizam alguns grupos recorrentes:
  • hardening de VPS -> 1h
  • operacao conservadora do Coolify -> 1h
  • provisionamento de Postgres/Redis -> 30m
  • deploy de frontend via Git + Dockerfile -> 45m
  • compatibilizacao de backend para Coolify -> 1h 30m
• Se o tempo rastreado for maior que o tempo real, o pacote cria uma time entry complementar no ClickUp e registra os dois valores no comentario final da task.
• Se o tempo nativo mostrado pelo ClickUp ficar abaixo do tempo final rastreado da entrega, o pacote complementa automaticamente a diferenca para alinhar o badge visual ao comentario final.
• Quando anexa arquivos automaticamente, o comentario de confirmacao no ClickUp lista os caminhos relativos dos anexos efetivamente enviados, evitando confirmacoes ambiguas por basename duplicado.
• Quando o comando manual attach encontra anexos da mesma familia, o pacote verifica automaticamente o tamanho do arquivo: se ja existir um anexo da mesma familia com o mesmo tamanho, ignora o envio para evitar duplicata; se o arquivo mudou, envia uma nova copia com sufixo versionado como -v2, -v3 e registra isso em comentario.
• Comentarios e logs de tempo usam formato compacto legivel, por exemplo 3m 48s, 20m 17s e 1h 5m.
• Quando a ultima subtarefa e concluida e nao resta checklist pendente na task pai, o pacote fecha a task pai automaticamente no ClickUp e registra esse fechamento em comentario.
• Toda alteracao aplicada no ClickUp passa a ser anunciada explicitamente no terminal/log e tambem entra na linha do tempo de devs-loop-session-history.md.
• As descricoes das tasks agora priorizam linguagem mais amigavel e legivel para qualquer pessoa do time, evitando depender de jargao tecnico quando isso nao for necessario.
• O pacote agora separa explicitamente tres tempos:
  • tempo estimado medio: quanto a entrega costuma levar em media
  • tempo rastreado final: quanto fica registrado no ClickUp ao final
  • tempo real: quanto a execucao levou de verdade na sessao
• Checklist nativa tem prioridade sobre qualquer checklist em markdown_description; se o transporte suporta checklist nativa, os criterios nao devem aparecer no corpo da descricao.
• Anexos automaticos ficaram mais conservadores:
  • referencias explicitas de arquivo ainda podem ser anexadas automaticamente
  • candidatos heurísticos agora exigem confirmacao do usuario antes do envio
  • contexto de reuniao/alinhamento/sync nao gera sugestao automatica de documentacao generica
  • o pacote nao usa mais markdown generico da propria raiz do pacote como candidato heurístico para tasks do usuario
• Ao criar uma task nova, o pacote busca tasks semelhantes do mesmo projeto/lista, salva o contexto em memoria temporaria local e usa esse historico para reduzir redundancia e sugerir versionamento quando houver colisao forte de nome.
• Quando encontra um match forte, o pacote pode reaproveitar a task existente como continuacao, incremento ou correcao, comentando o reuso em vez de abrir uma task redundante.
• Se ja existir uma task pai de iniciativa na sessao atual, novas tasks correlatas criadas sem --parent passam a ser agrupadas automaticamente como subtasks para evitar muitas tasks soltas no mesmo assunto; quando houver mais de uma raiz aberta, o agrupamento so acontece se houver sinal claro de parentesco para evitar associacao incorreta.
• Ao concluir uma task, o CLI e o MCP revisam a sessao atual: se ainda houver pendencias, informam explicitamente quais tasks continuam abertas; se nao houver mais pendencias, qualquer timer remanescente e pausado automaticamente.

Compatibilidade

O CLI continua funcionando normalmente. O MCP eh um adaptador adicional em cima do mesmo core.

Clientes MCP

Exemplos prontos por editor/cliente em:

• MCP-CLIENTS.md

Publicacao distribuivel

Este pacote esta preparado para publish distribuivel:

• estado fora do pacote
• .env nao deve ser publicado
• files limita o conteudo publicado
• binarios:
  • devs-loop
  • devs-loop-mcp