korean-patent-mcp: Instructions file for Claude Code

CLAUDE.md

⚠️ 배포 — 통합 호스트 (2026-07-02부터)

프로덕션 공식 서빙은 gomdori-mcp 통합 호스트(fly 앱 korean-law-mcp 1대, MCP 5종 동거)다.

• 공식 주소: https://mcp.gomdori.app/patent (구 앱 korean-patent-mcp는 통합 완료로 scale 0 처리됨)
• 반영 절차: 이 레포는 npm 미배포 — ①main에 커밋·푸시 → ②**gomdori-mcp/Dockerfile의 ARG PATENT_SHA 를 새 커밋 SHA로 갱신**(⚠️ Dockerfile은 main이 아니라 이 SHA를 checkout 한다 — 안 고치면 구 코드가 그대로 빌드돼 배포가 조용히 무효) → ③cd ~/workspace/gomdori-mcp && fly deploy -c fly.production.toml → ④curl https://mcp.gomdori.app/healthz 확인
• 구 앱은 scale 0이므로 이 레포에서 fly deploy 직접 실행은 무의미 — 통합 반영은 반드시 위 절차로

Korean Patent MCP — KIPRIS Plus 특허·실용신안·상표·디자인 검색 MCP (7툴). korean-law-mcp 패턴 벤치마킹.

Structure

src/
├── index.ts            진입점 (STDIO/HTTP 모드 분기)
├── tool-registry.ts    도구 7개 등록 + toMcpInputSchema (Zod v4 → JSON Schema, apiKey 숨김)
├── lib/
│   ├── api-client.ts       KIPRIS 엔드포인트 래핑 (검색류/항목/상표/디자인/서지상세)
│   ├── fetch-with-retry.ts 30초 타임아웃·3회 재시도·maskSensitiveUrl
│   ├── xml-parser.ts       checkHeader / parsePatentList / parseAdvancedList / parseTrademarkList / parseDesignList / parsePatentDetail / parseTotalCount
│   ├── format.ts           PatentHit/Trademark/Design/Detail → 텍스트
│   ├── errors.ts           KiprisApiError + resultCode 표준화
│   ├── cache.ts            patentCache (TTL+LRU)
│   ├── schemas.ts          truncateResponse (5만 자 — 바이트 아님)
│   ├── session-state.ts    AsyncLocalStorage 요청별 키
│   └── types.ts
├── tools/              search / advanced / applicant / rightholder / detail / trademark / design
└── server/http-server.ts

Tools (7)

search_patents(자유검색) / search_patents_advanced(항목검색 IPC·명칭·초록·청구·출원인·발명자) / search_by_applicant / search_by_rightholder / get_patent_detail(서지상세) / search_trademark / search_design

Commands

npm run build
KIPRIS_API_KEY=키 node build/index.js              # STDIO
KIPRIS_API_KEY=키 node build/index.js --mode http --port 8000

Domain Knowledge — KIPRIS 엔드포인트

두 게이트웨이가 있고 키 필드·페이징 방식이 다르다: