cortadel/cortadel

Cortadel Doctor

Diagnóstico integral de instalación. Ejecuta todas las verificaciones a continuación e informa de todas ellas, no te detengas en el primer fallo. Nunca uses el helper api() de cortadel-plugin/scripts/lib.mjs para nada de esto: traga todos los fallos (no-2xx, timeout, error de red) convirtiéndolos en null, que es exactamente lo incorrecto para un diagnóstico cuyo trabajo es distinguir un 401 de cero resultados. Usa curl directamente (o las herramientas MCP directamente) para que los códigos de estado reales y los cuerpos de error permanezcan visibles.

Ejecución

Verificación 1 — Resolución de configuración

Resuelve los mismos valores requeridos que resuelven los hooks del plugin (base_url, user_id, api_key), primero la capa CLAUDE_PLUGIN_OPTION_<KEY>, segundo la capa de variable de entorno CORTADEL_* — esto refleja la precedencia de cfg()/readOption() de 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: resuelto"; else echo "$fallback: NO ESTABLECIDO"; fi
done

PASA si los tres se resuelven a un valor no vacío; FALLA — e informa del resto de verificaciones como "omitido, sin configuración" — si alguno está vacío. Nunca imprimas el valor real de la clave API, solo si se resolvió.

Advertencia, expuesta claramente al usuario si corresponde: CLAUDE_PLUGIN_OPTION_* está documentado como inyectado en los subprocesos del hook específicamente. No está confirmado por nada en este repositorio si también es visible dentro de la ejecución de shell de una skill — verifica ambas capas e informa cuál resolvió realmente cada valor, en lugar de asumir que la capa del marketplace es accesible aquí.

Verificación 2 — Salud del servidor (sin autenticación)

GET /api/health no necesita credenciales en absoluto — es la primera sonda de red correcta, independientemente de si tu propia clave API es válida:

curl -s "$CORTADEL_URL/api/health"

Informa el status de nivel superior (ok o degraded) y, si está presente, el mapa checks (p. ej., checks.memgraph.ok, checks.embeddings.ok). Una respuesta degraded/503 es un resultado normal, no excepcional, que debe informarse — no es una razón para detener la ejecución de las verificaciones restantes.

Verificación 3 — Autenticación

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 → PASA.
• 401 → FALLA — clave API faltante o no válida.
• 403 → FALLA — la clave es válida pero no coincide con user_id.
• cualquier otro → FALLA — informa el código de estado y el cuerpo de la respuesta.

Verificación 4 — Lectura en vivo

Si la Verificación 3 devolvió 200, lee /tmp/cortadel-doctor-auth.json: confirma que se analiza como JSON y tiene un array items y un recuento total (la forma de MemoryListPagedResponse). Informa total como el recuento de memorias de la instalación — esta es la única cifra agregada que expone el servidor; no hay un endpoint de estadísticas separado, por lo que esto es el alcance completo de "estadísticas" disponible en cualquier lugar.

Si el servidor MCP cortadel también está conectado en esta sesión, adicionalmente llama a mcp__cortadel__search_memory({ topK: 1 }) (sin query — modo de navegación) como una segunda ruta de lectura en vivo independiente a través de la superficie MCP en lugar de REST. Infórmalo por separado: un paso REST con un fallo MCP (o viceversa) reduce qué mitad de la instalación está realmente rota. Omite esta subverificación — no la hagas fallar — si la herramienta MCP no está disponible en la sesión actual.

Visualización

Informa las cuatro verificaciones juntas, PASA/FALLA/ADVERTENCIA por verificación, p. ej.:

Resolución de config   PASA  base_url, user_id, api_key todos resueltos (capa CORTADEL_*)
Salud del servidor     PASA  status=ok
Autenticación          PASA  HTTP 200
Lectura en vivo        PASA  total=142 memorias; MCP search_memory: PASA

Si falla alguna verificación, añade pasos concretos siguientes que reflejen la sección de Solución de problemas de docs/plugin.md: 401 → verifica CORTADEL_API_KEY; 403 → verifica que CORTADEL_USER_ID coincida con el usuario de la clave; salud degradada → apunta a la entrada checks.* que falló.