kiwoom-mcp-server: Instructions file for Claude Code

CLAUDE.md

키움증권 REST API를 읽기 전용으로 노출하는 MCP 서버. TypeScript(ESM, NodeNext) + @modelcontextprotocol/sdk + zod. 기본 49개 tool, ISA 세금 tool 1개는 opt-in.

명령어

npm run dev        # tsx로 src 직접 실행
npm run typecheck  # tsc --noEmit
npm test           # vitest run (네트워크 없음, 오프라인 통과)
npm run build      # tsc → dist/

npm run check:write # CLAUDE.md 카운트를 실제 값으로 고쳐 씀 (버전은 안 건드림)

python3 scripts/sweep.py          # 전체 tool 실전 스윕 (VIRTUAL 기본, .env 필요)
python3 scripts/sweep.py --real    # REAL 모드 명시 허용
python3 scripts/sweep.py --only get_gold_price --full   # 한 tool만, 출력 전문
python3 scripts/sweep.py --only get_stock_chart,get_stock_lending  # 쉼표로 여럿 — 체이닝 유지

python3 scripts/routing.py                     # 라우팅 감사 — 모델이 옳은 tool을 고르는가 (haiku·sonnet·opus)
python3 scripts/routing.py --models haiku      # 빠른 회귀 — 결함은 보통 여기서 먼저 드러난다
python3 scripts/routing.py --grade-only <dir>  # 저장된 답안 재채점 (모델을 안 부른다)

npm run check && npm run typecheck && npm test && npm run build 네 가지가 로컬 게이트이자 CI(Node 22/24 매트릭스, .github/workflows/ci.yml)에서 도는 전부 — CI에는 npm audit --omit=dev --audit-level=high 한 단계가 더 붙는다(프로덕션 의존성만, 새 advisory가 뜨면 관련 없는 PR도 빨개진다). typecheck는 tsconfig.test.json으로 돈다 — 베이스 tsconfig.json의 include는 ["src"]뿐이라 빌드 산출물 레이아웃을 지키려면 tests를 거기 넣으면 안 되고, 그러면 테스트가 타입체크에서 통째로 빠진다(실제로 픽스처가 필수 필드를 빠뜨린 채 통과했다). 설정이 갈리므로 한쪽만 빨개질 수 있다 — TS 7.0.2로 올렸을 때 build만 23개 에러였고(process·Buffer·node:path 미발견) typecheck·test는 초록이었다. 베이스가 rootDir:"src"라 rootDir 바깥의 node_modules/@types를 프로그램에 안 넣은 탓이고, rootDir:"."인 테스트 설정은 그대로 통과했다(처방은 types:["node"] 명시, #104). 게이트 넷을 다 돌리는 이유가 이것이다. 같은 결로 타입 패키지는 engines 바닥에 맞춘다 — @types/node가 24인데 engines가 ">=22"면 Node 24+ API를 써도 tsc가 안 막아 바닥 런타임에서만 터진다(#105). dependabot.yml이 그 major를 무시하는 이유이고, 바닥을 올릴 때 타입도 사람이 같이 올린다. check는 버전 5곳 동기화, 아래 실측 카운트, README 2종의 tool 문서화, src/tools/가 export한 register*Tool이 server.ts에서 다 불리는지, 레이어 불변식, description의 tool 상호참조가 실존하는지, 라우팅 정답표가 실제 tool·파라미터를 가리키는지 일곱을 본다 — 네 번째가 없으면 파일만 만들고 등록을 빠뜨렸을 때 카운트가 그 누락을 포함한 채 계산돼 조용히 통과하고 --write가 숫자를 맞춰 은폐한다. 다섯 번째는 순환 의존 0건 · kiwoom/·utils/가 상위(tools/·isa/·server·http·oauth·context)를 import하지 않음 · .call(이 kiwoom/api.ts 안에만 있음 셋인데, 전부 typecheck와 테스트가 원리상 못 잡는 자리다(포맷터 테스트는 받은 값을 렌더할 뿐이고 순환 import는 런타임에야 터진다). 여섯 번째도 같은 이유다 — 모델은 description을 읽고 tool을 고르는데, 거기 적힌 tool 이름이 오타나 개명으로 실존하지 않아도 typecheck는 문자열 안을 안 보고 포맷터 테스트는 description을 렌더조차 하지 않는다(2026-08-19 라우팅 감사에서 승격). 일곱 번째는 그 라우팅 감사 자체가 낡는 걸 막는다 — scripts/routing/key.json은 tool·파라미터 이름을 문자열로 들고 있는데 시험은 모델을 부르므로 CI에 없다. tool 이름이 낡으면 전 문항이 MISS로 쏟아져 라우팅 회귀로 오독되고, param_check의 이름이 낡으면 __ABSENT__ 검사가 영원히 통과한다(넘길 리 없는 이름이니까 — q20의 to_date가 그 자리이고 v0.52.3이 고친 회귀를 지키는 검사다). 질문만 늘리고 정답을 안 적는 것도 같은 부류다. 여기엔 카운트를 CLAUDE.md와 대조하지 않는다 — 건수를 문서에 박으면 그 숫자가 또 낡는다. 카운트 검사 셋은 조용히 드리프트하므로 **카운트가 어긋나면 손으로 세지 말고 npm run check:write**로 고친다(실제 값은 스크립트가 이미 세고 있다 — 버전은 정답을 모르므로 건드리지 않는다). git config core.hooksPath .githooks를 한 번 걸어 두면 pre-commit에서도 돈다(카운트는 경고, 버전은 차단). sweep은 라이브 크리덴셜이 필요해 CI에 없고, tool을 추가·변경한 뒤 수동으로 돌린다 (npm run build 후 dist/index.js를 띄움). tool을 새로 붙였으면 --only <tool> --full로 표·각주·가드 문구까지 눈으로 확인한다 — 기본 스윕은 첫 줄만 찍어 렌더 오류를 못 잡는다. 스윕이 종목코드를 고정하면 그 종목에 데이터가 없는 날 가짜 감시가 된다 — ka10054 종목 지정은 005930으로 감시했는데, VI가 없는 날에는 회귀(rc=0 + 0행)와 정상이 글자까지 같은 화면이었다(2026-08-14 실패 주입으로 확인). 처방은 앞 호출의 응답에서 코드를 물려받고(ctx) 물려받은 코드가 빈손이면 회귀로 세우는 것이다 — 빈 결과 렌더 경로는 데이터가 없을 종목을 따로 골라 유지한다. 시각에 따라 렌더 경로가 갈리는 호출도 같은 부류다 — get_stock_lending(view=balance_rank)는 날짜를 안 주는 기본 호출이라 당일 집계가 열리기 전이면 후퇴 경로(전 거래일 + 각주), 열린 뒤면 당일 직행인데 둘 다 rc=0 + 50행이라 화면이 사실상 같다. v0.52.2가 고친 후퇴 각주가 21:15 검증 스윕에서 한 번도 안 보인 게 그래서이고, to_date를 주면 후퇴 자체가 꺼져(allowPreviousDay=false) 날짜를 박아 강제할 수도 없다. 처방은 기준일·각주·시각을 서로 대조해 세우는 것(check_lending_base_date)이다 — 오늘이 거래일인지는 일봉 마지막 행에서 물려받고(휴장일 저녁엔 후퇴가 정상이다), 열림 관측이 없는 19~21시 구간은 판정하지 않는다(스윕이 틀린 이유로 빨개지면 아무도 안 본다). 기대값: unexpected_errors=0, 모의투자에서는 get_transactions(kt00015)·get_account_trend(kt00002)·get_account_today(kt00017) 세 개만 err(exp)(전부 RC9000).