MCP¶
Nullus 를 AI 어시스턴트에 붙이는 Model Context Protocol 서버입니다.
전송은 stdio 전용입니다.
CLI 가이드는 이 기능을 "미구현" 으로 적고 있습니다
실제로는 구현돼 있습니다 — 도구 9종이 등록됩니다. 문서가 기능을 과소 보고하고 있습니다.
리소스와 프롬프트는 등록하지 않습니다
도구(tool)만 노출합니다.
플랫폼 화면의 AI 어시스턴트도 이 도구를 씁니다
AI 어시스턴트는 API 안에서 이 서버를 in-memory 로 띄워 아래 읽기 도구 6종만 씁니다(변경 도구는 목록에 없음). stdio 밖으로 열리는 전송은 아닙니다.
읽기 도구 6종 (항상)¶
| 도구 | 입력 | 호출하는 API |
|---|---|---|
stack_list |
없음 | GET /api/v1/stacks |
stack_status |
stack_id |
GET /api/v1/stacks/{id}/status |
cluster_list |
없음 | GET /api/v1/admin/clusters |
template_list |
없음 | GET /api/v1/stacks/templates — 응답을 count + 템플릿별 id · name · 용도 · 자원 · 도구(이름 + 버전) 요약으로 줄인다 |
compat_check |
stack_id, tools? |
POST /api/v1/stacks/{id}/validate |
stack_logs_tail |
stack_id, lines?(기본 100) |
GET /api/v1/stacks/{id}/deploy/logs/tail |
cluster_list 응답에서는 민감한 키를 값 가림이 아니라 키 자체를 삭제합니다 —
kubeconfig, kubeconfig_encrypted, token, password, secret.
변경 도구 3종 (--allow-write 일 때만)¶
| 도구 | 입력 | 동작 |
|---|---|---|
stack_deploy |
stack(stack.yaml v1alpha1), acknowledge_warnings? |
스택을 만들고 배포합니다 |
stack_rollback |
stack_id, version_id, reason? |
롤백 요청 |
pipeline_deploy |
pipeline_id |
파이프라인 실행 |
--allow-write 대신 NULLUS_MCP_ALLOW_WRITE=true 도 됩니다. 플래그를 명시하면
환경변수를 이깁니다(--allow-write=false 로 끌 수 있음).
SCM 토큰은 도구 인자로 받지 않습니다
stack_deploy 는 입력에서 비밀성 항목을 제거하고, SCM PAT 는 서버 프로세스의
NULLUS_SCM_TOKEN 에서 읽어 배포 요청에만 넣습니다.
stack_deploy 의 cluster 는 이름이나 ID 입니다
stack.yaml 의 name · cluster 는 필수입니다. cluster 가 ID(UUID)면 그대로 쓰고,
이름이면 GET /api/v1/admin/clusters 로 ID 를 찾습니다 — 이 목록은 admin 전용이라
다른 역할은 ID 를 넣어야 합니다. 같은 이름이 둘 이상이면 거부합니다.
template 은 golden_path_id 로 보냅니다.
생성은 됐는데 배포 요청만 실패하면 오류에 만들어진 스택 ID 를 담아 돌려줍니다.
다시 부르면 스택이 하나 더 생기니 stack_status 로 상태부터 확인하세요.
stack_rollback 은 지금 실패합니다
스택 이력에 적은 것과 같은 이유로 서버의 롤백 경로가 아직 맞물려 있지 않습니다.
기동 조건¶
토큰이 없으면 서버를 띄우지 않고 종료 코드 3 으로 끝납니다.
그때 안내하는 명령이 존재하지 않습니다
오류 메시지가 nullus login 과 nullus auth bootstrap issue 를 안내하지만
둘 다 구현되지 않은 명령입니다. 실제 해법은
NULLUS_TOKEN 환경변수입니다.
기동할 때 버전 차이를 한 번 확인하고, 다르면 표준 오류로 경고만 하고 계속 진행합니다. 시작 배너와 경고는 모두 표준 오류로 나갑니다.