opendart-mcp-server: Instructions file for Claude Code

CLAUDE.md — OpenDART MCP Server

이 파일은 AI 코딩 어시스턴트(Claude Code, Cursor 등)가 프로젝트를 이해하기 위한 마스터 문서입니다. 코드를 작성하기 전에 반드시 이 파일 전체를 읽으세요.

---

🎯 프로젝트 한 줄 요약

한국 금융감독원 DART(전자공시시스템) 데이터를 AI 에이전트가 사용할 수 있게 하는 MCP 서버.

"삼성전자 최근 3년 매출 추이 알려줘", "카카오 최대주주가 누구야?", "오늘 공시 나온 거 있어?" 같은 질문에 AI가 직접 DART API를 호출해 답할 수 있게 만든다.

---

📦 프로젝트 정보

• 이름: opendart-mcp-server
• npm 패키지명: opendart-mcp (추후 배포 시)
• 언어: TypeScript
• 런타임: Node.js 18+
• 프레임워크: FastMCP (TypeScript) — npm i fastmcp
• 라이선스: MIT

---

🏗️ 프로젝트 구조

opendart-mcp-server/
├── src/
│   ├── index.ts              # 진입점 — FastMCP 서버 초기화 + 시작
│   ├── tools/                # MCP Tool 정의 (DART API별 1파일)
│   │   ├── disclosure.ts     # 공시검색, 기업개황, 고유번호
│   │   ├── financial.ts      # 재무제표, 주요계정, 재무지표
│   │   ├── shareholder.ts    # 최대주주, 지분공시, 임원현황
│   │   └── event.ts          # 주요사항보고서 (유상증자, 합병 등)
│   ├── utils/
│   │   ├── dart-client.ts    # DART API HTTP 클라이언트 (인증키 관리, 요청, 에러 처리)
│   │   ├── corp-code.ts      # 회사명/종목코드 → DART 고유번호 변환 유틸리티
│   │   └── formatters.ts     # 숫자 포맷팅, 날짜 변환, 응답 정리 헬퍼
│   └── types/
│       └── dart.ts           # DART API 응답 타입 정의
├── data/
│   └── corp-codes.json       # DART 고유번호 ↔ 회사명/종목코드 매핑 캐시 (빌드 시 생성)
├── scripts/
│   └── update-corp-codes.ts  # DART에서 최신 고유번호 목록 다운로드하는 스크립트
├── package.json
├── tsconfig.json
├── .env.example              # DART_API_KEY=your_key_here
├── .gitignore
├── README.md                 # 사용자 대상 설명서 (한국어 + 영어)
├── CLAUDE.md                 # 이 파일
└── BRAND.md                  # 브랜드 가이드

---

🔧 기술 스택 상세

FastMCP (TypeScript)

• GitHub: https://github.com/punkpeye/fastmcp
• npm: fastmcp (최신 버전 사용)
• 이유: MCP 서버 구축에 가장 적은 보일러플레이트. server.addTool()로 도구 정의가 끝남
• 전송 방식: stdio (Claude Desktop/Cursor 용) + httpStream (원격 접속 용)

DART OpenAPI

• 공식 사이트: https://opendart.fss.or.kr
• 인증: API Key (무료 발급, 일 10,000건 제한)
• 응답 형식: JSON (기본) 또는 XML
• Base URL: https://opendart.fss.or.kr/api/

---

📡 DART OpenAPI 사용할 엔드포인트 목록