# dart-mcp

[OPEN DART(금융감독원 전자공시)](https://opendart.fss.or.kr/) 를 MCP 서버로 노출합니다.
법무·내부통제 검토에 쓰이는 **1차 공시 원본**(공시서류 원문·지분공시·재무제표)을
도구로 제공합니다.

> 엔드포인트는 모두 OPEN DART 공식 API 경로를 **원문 그대로** 사용합니다(추측 없음).
> 토스 증권 등 다른 자격증명과 무관한 **독립 서버**로, `OPENDART_API_KEY` 만 필요합니다.

## 왜 별도 MCP인가 (법무 활용)

DART 공시는 금감원 **1차 원본**입니다. 매뉴얼·뉴스·해설서와 격이 다른, 인용 가능한
원천 자료입니다. 법무팀 스택과 결합해 검토 파이프라인을 구성합니다:

```
dart-mcp (공시검색 → rcept_no → 원문)
   ↓ get_document
kordoc MCP (HWP/PDF/표 추가 파싱)
   ↓
korean-law MCP (관련 법령·판례 대조)
   ↓
legal-analysis / legal-team (종합 판단 → J-ID 축적)
```

예: "A사 합병 주요사항보고서 검토" → `search_disclosures(kind=B)` → `get_document` 원문
→ 상법·자본시장법 대조 → 판단.

## 제공 도구 (7개)

| 도구 | 엔드포인트 | 용도 |
|------|-----------|------|
| `dart_resolve` | corpCode.xml | 종목코드/회사명/고유번호 해석 |
| `search_disclosures` | list.json | 공시검색(기업·기간·유형) |
| `get_company` | company.json | 기업개황(대표자·설립·업종 등) |
| `get_document` | document.xml | 📌 **공시서류 원문 텍스트** |
| `major_holders` | majorstock.json | 대량보유(5%) 상황보고 |
| `insider_holdings` | elestock.json | 임원·주요주주 소유상황 |
| `financial_statements` | fnlttSinglAcntAll.json | 단일회사 전체 재무제표 |

공시유형(`kind`): A 정기 · B 주요사항 · C 발행 · D 지분 · E 기타 · F 외부감사 ...
보고서(`reprt_code`): 11011 사업(연간) · 11012 반기 · 11013 1Q · 11014 3Q.

## 설치 & 설정

```bash
cd dart_mcp
pip install -e .
cp .env.example .env   # OPENDART_API_KEY 입력 (https://opendart.fss.or.kr 무료 발급)
```

| 환경변수 | 설명 |
|----------|------|
| `OPENDART_API_KEY` | OPEN DART 인증키 (필수) |
| `DART_CACHE_DIR` | corp_code 매핑 캐시 경로 (기본 `data/`) |

## Claude Code 등록

```bash
claude mcp add dart --scope user \
  --env "PYTHONPATH=$(pwd)/src" -- python3 -m dart_mcp.server
```

`OPENDART_API_KEY` 는 `.env`(gitignore)에서 자동 로드되어 claude 설정엔 저장되지 않습니다.

## 구조

```
dart_mcp/
├── pyproject.toml
└── src/dart_mcp/
    ├── config.py            # OPENDART_API_KEY 로딩
    ├── client.py            # 키 주입·status 처리·corp_code 캐시·원문 추출
    ├── server.py            # FastMCP + 도구 등록
    └── tools/
        ├── disclosures.py   # 검색·기업개황·원문
        ├── ownership.py     # 대량보유·임원소유
        └── financials.py    # 재무제표
```

## 비고

- corp_code 매핑(상장사 ~3,970개)은 최초 1회 다운로드 후 주간 캐시.
- DART status `013`(데이터 없음)은 정상 처리(빈 목록 반환), 그 외 오류는 메시지 반환.
- 원문(`get_document`)은 본문 텍스트를 추출하며 `max_chars` 초과 시 `truncated=true`.