# DART 지분공시 전량수집 MCP 서버 (페이징판)

기존 OpenDART 커넥터의 **"하루 100건까지만"** 한계를 없앤 DART 지분공시 수집 서버입니다.
`page_no`를 끝까지 넘겨 **하루 861건도 전량 스캔**하고, **제출인(flr_nm)** 을 추적 기관 명단과
대조해 국민연금·삼성자산운용 등 기관 신고만 정확히 걸러냅니다.

> 왜 이게 되는가 (한줄): 이 서버는 배포된 호스트(Render)에서 DART에 접속하므로,
> Cowork 샌드박스의 도메인 차단과 무관하게 동작합니다. 남은 문제였던 "100건 캡"만
> 페이징으로 해결하면 끝입니다.

---

## 구성 파일
- `server.py` — MCP 서버 본체 (툴 2개)
- `requirements.txt` — 의존성
- `render.yaml` — Render 배포 설정
- `README.md` — 이 문서

## 제공 툴
1. **`sweep_institutional_disclosures(date, end_date?, institutions?, detail_type?)`**
   특정일 지분공시를 전량 수집 → 제출인이 추적 기관인 건만 반환. **매일 봇이 쓸 핵심 툴.**
   - `institutions` 미지정 시 기본 11개 기관(국민연금공단, 삼성자산운용, 미래에셋자산운용,
     KB자산운용, 한국투자신탁운용, 신한자산운용, NH아문디자산운용, 우정사업본부,
     사학연금공단, 공무원연금공단, 한국투자밸류자산운용) 사용.
   - `detail_type="D001"` 지정 시 대량보유(5%)보고만.
2. **`list_disclosures_paginated(date, end_date?, pblntf_ty?, detail_type?, name_contains?)`**
   필터 없이 전량 원자료 조회. `name_contains`로 제출인/대상회사 부분일치 검색 가능.

---

## 설치 3단계

### 1단계 — DART 인증키 발급 (무료, 5분)
1. https://opendart.fss.or.kr 접속 → 상단 **인증키 신청/관리 → 인증키 신청**
2. 이메일로 본인확인 후 **40자리 인증키** 발급 (즉시 발급, 무료).
3. 하루 20,000건까지 호출 가능 — 이 용도엔 충분합니다.

### 2단계 — Render에 배포 (무료 플랜)
가장 쉬운 경로는 GitHub 저장소를 Render에 연결하는 것입니다.

1. 이 폴더(`dart-mcp-server`) 전체를 GitHub 새 저장소에 올립니다.
   ```bash
   cd dart-mcp-server
   git init && git add . && git commit -m "dart mcp paginated"
   # GitHub에서 빈 저장소 만든 뒤:
   git remote add origin https://github.com/<본인계정>/dart-mcp-paginated.git
   git push -u origin main
   ```
2. https://render.com 로그인 → **New → Blueprint** → 방금 저장소 선택.
   (`render.yaml`을 자동 인식합니다.)
3. 배포 중 **Environment**에서 `DART_API_KEY` 값에 1단계 인증키를 붙여넣고 저장.
4. 배포 완료 후 서비스 URL 확인 (예: `https://dart-mcp-paginated.onrender.com`).
   MCP 엔드포인트는 여기에 **`/mcp`** 를 붙인 주소입니다:
   `https://dart-mcp-paginated.onrender.com/mcp`

> 무료 플랜은 미사용 시 슬립합니다. 첫 호출이 10~30초 느릴 수 있으나 동작엔 문제없습니다.
> 매일 정해진 시간에 확실히 깨우려면 유료(Starter) 플랜이나 외부 핑을 쓰면 됩니다.

### 3단계 — Claude에 커넥터로 연결
1. claude.ai → **Settings → Connectors → Add custom connector**
2. 2단계의 `/mcp` 주소를 붙여넣고 저장.
3. 연결되면 툴 `sweep_institutional_disclosures` / `list_disclosures_paginated`가 나타납니다.
4. 기존 OpenDART 커넥터는 재무·기업검색용으로 그대로 두고, 지분공시 스윕만 이 새 커넥터로
   돌리면 됩니다. (봇 스킬에서 지분공시 단계만 새 툴 호출로 교체)

---

## 로컬 테스트 (선택)
인터넷 되는 PC에서 먼저 검증하려면:
```bash
pip install -r requirements.txt
export DART_API_KEY=<발급키>      # Windows: set DART_API_KEY=<발급키>
python server.py                  # http://localhost:8000/mcp 로 뜸
```
> 참고: 이 Cowork 샌드박스는 opendart.fss.or.kr 도메인을 막고 있어 여기서는 실행 검증이
> 불가합니다. 반드시 인터넷이 열린 환경(로컬 PC 또는 Render)에서 돌리세요.

---

## 봇 연동 메모
매일 브리핑 스킬에서 DART 단계를 이렇게 바꾸면 "861건 중 100건" 누락 경고가 사라집니다:
```
sweep_institutional_disclosures(date="전영업일")
→ 반환된 매칭 건을 그대로 텔레그램 메시지 1에 사용
→ "전체 N건 전량 스캔, 누락 없음" 문구로 기존 API 한도 경고문 대체
```