5. CLI 및 인터페이스 규칙
본 프로젝트는 MCP 서버 키트로, UI/UX 컴포넌트나 시각적 인터페이스를 포함하지 않습니다. 모든 상호작용은 CLI(터미널) 또는 MCP 프로토콜을 통한 AI-기반 인터페이스로 이루어집니다.
CLI 출력 규칙
CLI는 runCli()를 통해 다음과 같은 형식으로 출력됩니다:
-
도구 목록 출력 (인자 없이 실행 시):
- 도구명은 2칸 들여쓰기
- 설명은 도구명 다음 줄
- 파라미터는 4칸 들여쓰기 + 파라미터명 + 설명
-
도구 실행 결과:
console.log()로 일반 텍스트 출력 -
에러 메시지:
console.error()로 stderr에 출력
CLI UX 규칙
- 도구 실행 결과는 순수 텍스트로만 반환 (색상, 포매팅, 이모지 사용 금지)
- 에러 메시지는 사람이 읽을 수 있는 자연어로 출력 (스택 트레이스 금지)
handleCliError()는 ZodError를 파싱하여"fieldName: error message"형식으로 출력- MCP 서버 모드에서는 모든 출력이
CallToolResult.content배열의text항목으로 전달됨
접근성
- CLI는 시각적 요소에 의존하지 않음 (순수 텍스트 기반)
- MCP 프로토콜은 AI 어시스턴트가 결과를 자연어로 가공하여 전달하므로 별도 접근성 처리 불필요
컴포넌트 재사용 주의사항
src/common/kit/의 함수는 MCP 서버와 CLI가 함께 재사용함. 변경 시 두 경로 모두에 영향이 가므로 주의- 모든 필드가 required이고
null이 "기본값을 쓰라"는 뜻입니다.runCli()가 생략된 위치 인자를null로 채우므로 명령줄에서는 선택 인자처럼 동작합니다. 이유는 04-coding-rules에 있습니다 - 빌드 설정(
tsup.config.ts)은 번들과 shebang을 좌우합니다. 이제 문서는 쓰지 않습니다 - 인자 문서는 손으로 씁니다. 인자 표·기본값·범위·반환 형태는
README.md와SKILL.md에 있습니다. 도구 정의에서 생성되는 것은 없습니다