mcp-toolkit: Instructions file for Claude Code

CLAUDE.md

이 파일은 Claude Code가 이 저장소에서 작업할 때 참고하는 컨텍스트입니다.

프로젝트 개요

@us-all/mcp-toolkit — @us-all/* MCP 서버용 공통 빌딩 블록. 6개 production MCP에서 검증된 토큰 효율 패턴을 단일 npm 패키지로 추출.

• 타겟: Node 18+, ESM, TypeScript strict
• Peer deps: @modelcontextprotocol/sdk ^1.27 || ^1.28 || ^1.29, zod ^4
• 목적: 6 production MCP의 코드 중복 제거 + 패턴 진화 시 단일 진실 소스
• 표준 문서: STANDARD.md — 패턴의 why, 이 패키지는 how

디렉토리

src/
├── extract-fields.ts       # applyExtractFields(data, expr?) — 응답 필드 프로젝션
├── registry.ts             # ToolRegistry<TCategory> + createSearchToolsMetaTool + parseEnvList
├── wrap-tool-handler.ts    # createWrapToolHandler — 에러 sanitize + structured 응답 + extractFields auto-apply
├── aggregate.ts            # aggregate(fetchers, caveats) — Promise.allSettled + 라벨링된 caveats 보일러플레이트 통합
├── runtime.ts              # startMcpServer(server, opts?) — stdio + Streamable HTTP (node:http + Bearer auth)
└── index.ts                # re-export 통합 진입점
tests/
├── extract-fields.test.ts      # 9 cases — wildcards, backtick keys, projection 엣지
├── registry.test.ts            # 11 cases — search 매칭, 카테고리 토글, allowlist/denylist
├── wrap-tool-handler.test.ts   # 16 cases — 성공/에러 경로, 커스텀 redaction, errorExtractors
├── aggregate.test.ts           # 11 cases — 성공/거부 mix, 커스텀 formatReason, 동시성 검증
└── runtime.test.ts             # 7 cases — 환경변수/옵션 해석, Bearer 인증, /health, skipAuth
STANDARD.md             # us-all MCP 작성 표준 (패턴 가이드)

Build & Run

pnpm install
pnpm build          # tsc → dist/
pnpm test           # 36 unit tests

설계 원칙

• Pure functions / pure classes: 외부 의존성 없는 도메인-독립 코드만 추출. SDK/auth 등 도메인 특수 로직은 각 repo에 유지.
• Generic categories: ToolRegistry<TCategory> — 각 repo가 자체 CATEGORIES 상수를 typed로 정의해서 사용.
• Always-enabled meta: meta 카테고리는 기본적으로 항상 활성. alwaysEnabled 옵션으로 커스터마이즈 가능.
• Schema opt-in: extractFields는 각 도구 schema가 명시적으로 선언해야 동작 (MCP SDK가 미선언 필드를 validation에서 drop). STANDARD.md에 caveat 명시.