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 새 저장소에 올립니다.

   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에서 먼저 검증하려면:

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 한도 경고문 대체