Cortadel Doctor
종단 간 설치 진단. 아래의 모든 검사를 실행하고 모두 보고하십시오 — 첫 번째 실패에서 멈추지 마십시오.
이 작업에 cortadel-plugin/scripts/lib.mjs의 api() 헬퍼를 절대 사용하지 마십시오: 이 헬퍼는 모든 오류(2xx 외 응답, 타임아웃, 네트워크 오류)를 null로 삼켜버리기 때문에, 401과 결과 없음을 구분해야 하는 진단에는 완전히 부적합합니다. 실제 상태 코드와 오류 본문을 확인할 수 있도록 원시 curl(또는 MCP 도구 직접 사용)을 사용하십시오.
실행
검사 1 — 설정 확인
플러그인 자체 훅이 해석하는 동일한 필수 값(base_url, user_id, api_key)을 확인합니다. CLAUDE_PLUGIN_OPTION_<KEY> 계층을 먼저, CORTADEL_* 환경 변수 계층을 다음으로 확인합니다 — 이는 cortadel-plugin/scripts/lib.mjs의 cfg()/readOption() 우선순위를 반영합니다:
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: resolved"; else echo "$fallback: NOT SET"; fi
done
세 값 모두 비어 있지 않은 값으로 확인되면 PASS, 하나라도 비어 있으면 FAIL — 나머지 검사는 "설정 없음, 건너뜀"으로 보고하십시오. API 키의 실제 값을 절대 출력하지 말고, 해석되었는지 여부만 보고하십시오.
주의 사항(해당되는 경우 사용자에게 명확히 설명): CLAUDE_PLUGIN_OPTION_*는 후크 서브프로세스에 특별히 주입되는 것으로 문서화되어 있습니다. 이 값이 스킬 자체의 셸 실행 내에서도 볼 수 있는지 여부는 이 저장소에서 확인되지 않았습니다 — 두 계층을 모두 확인하고 마켓플레이스 계층에 도달할 수 있다고 가정하지 말고, 실제로 각 값을 해석한 계층을 보고하십시오.
검사 2 — 서버 상태(인증 없음)
GET /api/health는 자격 증명이 전혀 필요하지 않습니다 — 자신의 API 키가 유효한지 여부와 관계없이 첫 번째 네트워크 프로브로 적합합니다:
curl -s "$CORTADEL_URL/api/health"
최상위 status(ok 또는 degraded)와, 존재하는 경우 checks 맵(예: checks.memgraph.ok, checks.embeddings.ok)을 보고하십시오. degraded/503 응답은 보고해야 하는 정상적인 비예외 결과입니다 — 나머지 검사를 중단할 이유가 아닙니다.
검사 3 — 인증
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→ PASS.401→ FAIL — API 키가 없거나 유효하지 않음.403→ FAIL — 키는 유효하지만user_id와 일치하지 않음.- 그 외 → FAIL — 상태 코드와 응답 본문을 보고하십시오.
검사 4 — 라이브 읽기
검사 3이 200을 반환한 경우, /tmp/cortadel-doctor-auth.json을 읽으십시오: JSON으로 파싱되고 items 배열과 total 개수(MemoryListPagedResponse 형태)가 있는지 확인하십시오. total을 설치의 메모리 개수로 보고하십시오 — 이것이 서버가 노출하는 유일한 집계 수치이며, 별도의 통계 엔드포인트는 없으므로 이것이 사용 가능한 "통계"의 전부입니다.
이 세션에 cortadel MCP 서버도 연결되어 있다면, 추가로 mcp__cortadel__search_memory({ topK: 1 })를 호출하십시오(query 없음 — 찾아보기 모드). 이는 REST가 아닌 MCP 표면을 통한 두 번째 독립적인 라이브 읽기 경로입니다. 별도로 보고하십시오: REST 성공과 MCP 실패(또는 그 반대)는 설치의 어느 절반이 실제로 고장인지 좁혀줍니다. 현재 세션에서 MCP 도구를 사용할 수 없는 경우 이 하위 검사를 건너뛰고 실패로 처리하지 마십시오.
표시
네 가지 검사를 모두 함께 보고하십시오. 각 검사별 PASS/FAIL/WARN, 예:
설정 확인 PASS base_url, user_id, api_key 모두 해석됨(CORTADEL_* 계층)
서버 상태 PASS status=ok
인증 PASS HTTP 200
라이브 읽기 PASS total=142 memories; MCP search_memory: PASS
어느 검사가 실패하면, docs/plugin.md의 문제 해결 섹션을 반영한 구체적인 다음 단계를 추가하십시오: 401 → CORTADEL_API_KEY 확인; 403 → CORTADEL_USER_ID가 키의 사용자와 일치하는지 확인; 상태 저하 → 실패한 checks.* 항목을 가리키십시오.