npm package: @renatocostaguedesdemorais/devs-loop-mcp
Description: Distributed MCP and CLI for devs-loop ClickUp automation
Latest version: 0.5.0

# DEVS-LOOP MCP

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

## Release 0.5.0

Principais mudancas desta release:

- **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

```bash
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`:

```env
CLICKUP_API_TOKEN=pk_xxx
DEV_EMAIL=voce@empresa.com
```

### 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:

```bash
devs-loop auth login --email voce@empresa.com
```

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:

```bash
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:

```bash
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:

```bash
devs-loop auth personal --token pk_xxx --email voce@empresa.com
devs-loop auth select
devs-loop auth login --email voce@empresa.com
devs-loop auth oauth-token --token access_xxx --email voce@empresa.com
devs-loop auth status
devs-loop auth clear
```

Fluxo OAuth:

```bash
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

```bash
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:

```env
CLICKUP_API_TOKEN=pk_xxx
DEV_EMAIL=voce@empresa.com
```

### Iniciar o servidor MCP

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

Ou:

```bash
npm run mcp
```

### Exemplo de configuracao MCP local

```json
{
  "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:

```json
{
  "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:

```bash
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`:

```json
[
  {
    "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 com menos de `10min` sao tratadas como microtasks com base no `tempo real` acumulado da task, mesmo que o timer ja tenha sido trocado antes da conclusao.
- 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`