cortadel/cortadel

Cortadel Doctor

Diagnóstico de instalação completo. Execute todas as verificações abaixo e relate todas elas — não pare na primeira falha. Nunca use o helper api() de cortadel-plugin/scripts/lib.mjs para nada disso: ele engole todas as falhas (diferente de 2xx, timeout, erro de rede) transformando em null, que é exatamente o errado para um diagnóstico cujo trabalho inteiro é distinguir um 401 de zero resultados. Use curl puro (ou as ferramentas MCP diretamente) para que códigos de status reais e corpos de erro permaneçam visíveis.

Execução

Verificação 1 — Resolução de configuração

Resolva os mesmos valores obrigatórios que os hooks do plugin resolvem (base_url, user_id, api_key), primeiro na camada CLAUDE_PLUGIN_OPTION_<KEY>, depois na camada da variável de ambiente CORTADEL_* — isso espelha a precedência de cfg()/readOption() em cortadel-plugin/scripts/lib.mjs:

for pair in "CLAUDE_PLUGIN_OPTION_BASE_URL:CORTADEL_URL" \
            "CLAUDE_PLUGIN_OPTION_USER_ID:CORTADEL_USER_ID" \
            "CLAUDE_PLUGIN_OPTION_API_KEY:CORTADEL_API_KEY"; do
  opt="${pair%%:*}"; fallback="${pair##*:}"
  val="${!opt:-${!fallback:-}}"
  if [ -n "$val" ]; then echo "$fallback: resolvido"; else echo "$fallback: NÃO DEFINIDO"; fi
done

PASSOU se todos os três resolverem para um valor não vazio; FALHOU — e relate o restante das verificações como "pulado, sem configuração" — se algum estiver vazio. Nunca imprima o valor real da chave API, apenas se foi resolvido.

Ressalva, declarada claramente ao usuário se relevante: CLAUDE_PLUGIN_OPTION_* é documentado como sendo injetado em subprocessos do hook especificamente. Se também é visível dentro da execução de shell de uma habilidade não é confirmado por nada neste repositório — verifique ambas as camadas e relate qual delas realmente resolveu cada valor, em vez de assumir que a camada do marketplace é acessível aqui.

Verificação 2 — Saúde do servidor (não autenticado)

GET /api/health não precisa de nenhuma credencial — é a primeira sonda de rede correta, independente de sua própria chave API ser válida:

curl -s "$CORTADEL_URL/api/health"

Relate o status de nível superior (ok ou degraded) e, se presente, o mapa checks (por exemplo, checks.memgraph.ok, checks.embeddings.ok). Uma resposta degraded/503 é um resultado normal e não excepcional a ser relatado — não é uma razão para parar de executar as verificações restantes.

Verificação 3 — Autenticação

curl -s -o /tmp/cortadel-doctor-auth.json -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $CORTADEL_API_KEY" \
  "$CORTADEL_URL/api/v1/memories?user_id=$CORTADEL_USER_ID&size=1"

• 200 → PASSOU.
• 401 → FALHOU — chave API ausente ou inválida.
• 403 → FALHOU — a chave é válida mas não corresponde a user_id.
• qualquer outro → FALHOU — relate o código de status e o corpo da resposta.

Verificação 4 — Leitura ativa

Se a Verificação 3 retornou 200, leia /tmp/cortadel-doctor-auth.json: confirme que ele é analisável como JSON e tem um array items e uma contagem total (a forma de MemoryListPagedResponse). Relate total como a contagem de memórias da instalação — este é o único valor agregado que o servidor expõe; não há nenhum endpoint de estatísticas separado, então esta é a extensão completa de "estatísticas" disponível em qualquer lugar.

Se o servidor MCP cortadel também estiver conectado nesta sessão, adicionalmente chame mcp__cortadel__search_memory({ topK: 1 }) (sem query — modo navegação) como um segundo caminho de leitura ativa independente através da superfície MCP em vez de REST. Relate-o separadamente: uma passagem REST com uma falha MCP (ou o inverso) restringe qual metade da instalação está realmente quebrada. Pule esta sub-verificação — não a falhe — se a ferramenta MCP não estiver disponível na sessão atual.

Exibição

Relate todas as quatro verificações juntas, PASS/FAIL/WARN por verificação, por exemplo:

Resolução de config   PASSOU  base_url, user_id, api_key todos resolvidos (camada CORTADEL_*)
Saúde do servidor     PASSOU  status=ok
Autenticação          PASSOU  HTTP 200
Leitura ativa         PASSOU  total=142 memórias; MCP search_memory: PASSOU

Se alguma verificação falhar, adicione próximos passos concretos espelhando a seção de Solução de Problemas de docs/plugin.md: 401 → verifique CORTADEL_API_KEY; 403 → verifique se CORTADEL_USER_ID corresponde ao usuário da chave; saúde degradedada → aponte para qual entrada checks.* falhou.