#3. 프로젝트 아키텍처 및 디렉토리 역할

mcp-kit/
├── src/
│   ├── index.ts        # 라이브러리 진입점
│   ├── server.ts       # MCP 서버 진입점 (stdio)
│   ├── cli.ts          # CLI 진입점
│   ├── agent.test.ts   # 실제 LLM 테스트 (기본 test에서 제외)
│   ├── tools/          # MCP 도구 정의
│   ├── exchange/       # 환율 스크레이핑 도메인
│   ├── tmdb/           # TMDB 영화 조회 도메인
│   ├── system/         # 기계 상태 도메인 (배터리 / 메모리 / CPU / 디스크)
│   └── common/         # 공유 키트 (별도 배포 없음, 번들에 인라인)
├── docs/               # Rspress 문서 사이트 콘텐츠
├── scripts/            # Rspress 플러그인
├── skills/             # 손으로 쓴 SKILL.md
├── .github/workflows/  # CI/CD 파이프라인
├── package.json        # 단일 패키지 설정 (@julong/mcp-kit)
├── tsconfig.json       # TypeScript 설정 (@/* → src/*)
├── tsup.config.ts      # 번들 설정
├── rstest.config.ts    # 테스트 설정
├── rslint.config.ts    # 린트 설정
├── rspress.config.ts   # 문서 사이트 설정
├── netlify.toml        # Netlify 배포 설정
├── release-please-config.json      # release-please 설정 (단일 패키지)
├── .release-please-manifest.json   # 현재 버전 추적
└── CLAUDE.md           # AI 어시스턴트용 프로젝트 컨텍스트

src/common/
├── kit/
│   ├── tool.ts     # 도구 정의: toolDef(), defineTool(), AnyToolDef 타입, text() 헬퍼
│   ├── server.ts   # MCP 서버: createMcpServer(), startServer(), installProcessGuards()
│   ├── cli.ts      # CLI 실행: runCli(), handleCliError()
├── agent/
│   ├── llm.ts      # createChatModel() — 환경 변수로 OpenAI 호환 채팅 모델 생성
│   ├── log.ts      # FileLogCallback, appendLog() — taskId별 .log 파일 기록
│   ├── runner.ts   # runMcpAgent(), nodeMcpServer() — MCP 서버 기동 + deep agent 실행
│   └── index.ts    # 에이전트 키트 진입점 (`@/common`이 아닌 `@/common/agent`로 사용)
├── .log/           # 에이전트 실행 로그, taskId별 파일 (gitignore 대상)
├── types.ts        # 공통 타입 (Nullable, Optional, MaybePromise)
├── constants.ts    # 공통 상수 (VERSION)
└── index.ts        # 공개 진입점 (kit/* 전체 re-export)

src/tools/
├── index.ts        # tools re-export + UTILS_ENV_KEYS (생성된 README의 env 블록)
├── exchange.ts     # exchangeRatesTool, exchangeRateTool 정의
├── exchange.test.ts
├── movie.ts        # nowPlayingMoviesTool, upcomingMoviesTool, movieRecommendationsTool 정의
├── movie.test.ts
├── system.ts       # systemBatteryTool, systemMemoryTool, systemCpuTool, systemDiskTool, systemInfoTool 정의
└── system.test.ts

src/exchange/
├── index.ts        # 포털 병렬 수집 오케스트레이션 + 타임아웃 처리
├── types.ts        # Provider / CurrencyCode / ExchangeQuote 정의
├── parse.ts        # 숫자 파싱 · 고시 단위 역산 · ExchangeQuote 생성
├── wait.ts         # 자리표시자가 실제 시세로 바뀔 때까지 대기
├── browser.ts      # Chromium 기동 및 브라우저 컨텍스트 생성
└── providers/      # naver.ts · google.ts · daum.ts 스크레이퍼

src/tmdb/
├── index.ts        # 도메인 진입점 (re-export)
├── types.ts        # TmdbMovie / MovieSummary / MovieListResult 정의와 상수
├── client.ts       # 인증 해석 · URL 조립 · 제한 시간을 둔 GET
├── genres.ts       # 장르 id → 이름 표(언어별 캐시), 장르 이름 해석
├── normalize.ts    # TMDB 원본 영화 → MovieSummary
└── movies.ts       # 상영 중 / 개봉 예정 / 추천 오케스트레이션

src/system/
├── index.ts        # 도메인 진입점 (재노출)
├── types.ts        # SECTIONS, BatteryInfo / MemoryInfo / CpuLoadInfo / DiskUsage / SystemSnapshot, 기본값
├── normalize.ts    # systeminformation 원본 → 위 타입으로 정리, pickPrimaryDisk()
└── collect.ts      # readBattery / readMemory / readCpu / readDisks / readSnapshot, 제한 시간

docs/                        # 정적 마크다운 문서 (01-*.md ~ 10-*.md)
├── index.md                 # 홈 페이지 (Rspress hero layout)
├── 01-project-overview.md
├── ...
├── 10-commands.md
└── ko/                      # 한국어 로케일
scripts/readme-docs-plugin.ts  # README → /api 페이지 변환 플러그인
rspress.config.ts            # Rspress 설정 (sidebar, nav, plugins)
netlify.toml                 # Netlify 배포 설정

도구 정의 (src/tools/*.ts)
  │
  ├──→ src/index.ts        ─→ tsup build ─→ dist/index.js   (라이브러리)
  ├──→ src/server.ts       ─→ tsup build ─→ dist/server.js  (MCP 서버)
  └──→ src/cli.ts          ─→ tsup build ─→ dist/cli.js     (CLI)

문서는 도구에서 생성되지 않습니다. README.md와 skills/<bin>/SKILL.md는 손으로 쓰며,
src/tools/*.ts를 고칠 때 함께 고칩니다.