5. CLI 및 인터페이스 규칙

본 프로젝트는 MCP 서버 키트로, UI/UX 컴포넌트나 시각적 인터페이스를 포함하지 않습니다. 모든 상호작용은 CLI(터미널) 또는 MCP 프로토콜을 통한 AI-기반 인터페이스로 이루어집니다.

CLI 출력 규칙

CLI는 runCli()를 통해 다음과 같은 형식으로 출력됩니다:

  • 도구 목록 출력 (인자 없이 실행 시):

    Available skills:
    
      exchangeRateTool
      포털 한 곳에서 통화 하나의 원화 환율을 가져옵니다
        provider    조회할 포털
        currency    조회할 통화
    • 도구명은 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에 있습니다. 도구 정의에서 생성되는 것은 없습니다