8. 파일 및 컴포넌트 생성 규칙

신규 파일 생성 위치

생성할 것위치예시
새 도구src/tools/<name>.tssrc/tools/exchange.ts
도구 그룹 re-exportsrc/tools/index.ts기존 파일에 export 추가
새 도메인 모듈src/<domain>/src/exchange/
새 스크레이퍼src/exchange/providers/<name>.tssrc/exchange/providers/daum.ts
공유 키트 기능src/common/kit/<name>.tssrc/common/kit/validator.ts
공유 키트 re-exportsrc/common/kit/index.ts기존 파일에 export 추가
공유 타입src/common/types.ts기존 파일에 타입 추가
공유 상수src/common/constants.ts기존 파일에 상수 추가
빌드 스크립트scripts/<name>.mjs|.tsscripts/readme-docs-plugin.ts
테스트대상 파일 옆 <name>.test.tssrc/exchange/parse.test.ts

새 도구 추가 시 체크리스트

  1. src/tools/<name>.ts — toolDef()로 도구 정의 (description, inputSchema, handler). inputSchema의 모든 필드는 .nullable()이어야 하고 .describe()에 기본값을 적습니다 — 04-coding-rules 참고
  2. src/tools/index.ts — 새 도구를 tools 객체에 병합
  3. src/tools/<name>.test.ts — 핸들러 단위 테스트
  4. src/tools/openai-schema.test.ts — 도구 개수를 올려 새 도구까지 검사에 포함
  5. README.md — 인자 표·기본값·범위·반환 형태·예제를 손으로 추가
  6. skills/mcp-kit-cli/SKILL.md — 같은 인자 표를 손으로 추가
  7. 도구가 노출하는 이름(name 필드)은 MCP 클라이언트 호환성에 직결되므로 신중히 결정

기존 컴포넌트 수정 여부 판단 기준

상황행동
새 도구 추가src/tools/에 새 파일 생성 OR 기존 파일에 도구 추가 (도메인이 같은 경우)
기존 도구 로직 수정해당 도구의 핸들러만 수정 (파일 분할 불필요)
공통 동작 변경src/common/kit/ 수정 + 서버·CLI 두 경로 확인
CLI 출력 포맷 변경src/common/kit/cli.ts 수정
README·SKILL.md 변경파일을 직접 고칩니다 — 생성기는 없습니다

공통 로직 추출 시점

다음 조건 중 하나라도 해당되면 공통 로직으로 추출:

  1. 동일한 코드를 MCP 서버와 CLI가 함께 사용함 → src/common/kit/으로 이동
  2. 동일한 코드가 2개 이상의 도구에서 사용됨 → 해당 도메인 디렉터리의 유틸리티로 추출 (예: src/exchange/parse.ts)
  3. 복잡한 Zod 스키마가 재사용됨 → 공유 Zod 스키마로 분리

공통 네이밍 규칙

항목규칙예시
패키지명@julong/<name>@julong/mcp-kit
MCP 서버 바이너리명<name>mcp-kit
CLI 바이너리명<name>-climcp-kit-cli
도구명 (변수)camelCase + Tool 접미사exchangeRateTool, exchangeRatesTool
도구명 (MCP 노출)snake_caseexchange_rate, exchange_rates
파일명kebab-casereadme-docs-plugin.ts, case-convert.ts
인터페이스PascalCaseToolDefShape, AnyToolDef
타입 (utility)PascalCaseNullable<T>, Optional<T>
비동기 함수async function모든 도구 핸들러
상수UPPER_SNAKE_CASEVERSION