# AGENTS.md - MCP OpenDART 프로젝트 가이드
이 문서는 코드 AI가 MCP OpenDART 프로젝트를 효과적으로 이해하고 유지보수할 수 있도록 작성되었습니다.
## 프로젝트 개요
MCP OpenDART는 OpenDART(금융감독원 전자공시시스템)를 위한 Model Context Protocol(MCP) 서버입니다. FastMCP 프레임워크를 사용하여 OpenDART API를 MCP 도구로 제공합니다.
### 주요 기능
- 공시정보 조회 (DS001)
- 정기보고서 주요정보 및 재무정보 (DS002, DS003)
- 지분공시 종합정보 (DS004)
- 주요사항보고서 주요정보 (DS005)
- 증권신고서 주요정보 (DS006)
- 재무제표 주석 자동 추출 및 검색
- 사업의 내용 및 회사의 개요 파싱
## 개발 환경 설정
### 필수 요구사항
- Python 3.10 이상 (필수)
- uv 패키지 매니저 (권장) 또는 pip
- OpenDART API 키
### 환경 설정
```bash
# Python 버전 확인
python3 --version # 3.10 이상이어야 함
# 가상환경 생성
python3.10 -m venv .venv
source .venv/bin/activate # macOS/Linux
# 또는
.venv\Scripts\activate # Windows
# 패키지 설치
python3 -m pip install --upgrade pip
uv pip install -e . # uv 사용 시
# 또는
pip install -e . # pip 사용 시
```
### 환경 변수 설정
`.env` 파일을 프로젝트 루트에 생성:
```bash
OPENDART_API_KEY=your-api-key-here
OPENDART_BASE_URL=https://opendart.fss.or.kr/api/
HOST=0.0.0.0
PORT=8000
TRANSPORT=http # 또는 stdio
LOG_LEVEL=INFO
MCP_SERVER_NAME=opendart-mcp
```
## 프로젝트 구조
```
src/mcp_opendart/
├── __init__.py # 패키지 초기화
├── server.py # FastMCP 서버 메인 로직
├── config.py # 설정 관리 (OpenDartConfig, MCPConfig)
├── apis/ # OpenDART API 클라이언트
│ ├── client.py # OpenDartClient (기본 클라이언트)
│ ├── ds001.py # 공시정보 API
│ ├── ds002.py # 정기보고서 주요정보 API
│ ├── ds003.py # 정기보고서 재무정보 API
│ ├── ds004.py # 지분공시 종합정보 API
│ ├── ds005.py # 주요사항보고서 주요정보 API
│ └── ds006.py # 증권신고서 주요정보 API
├── tools/ # MCP 도구 정의
│ ├── disclosure_tools.py
│ ├── financial_info_tools.py
│ ├── major_report_tools.py
│ ├── ownership_disclosure_tools.py
│ ├── periodic_report_tools.py
│ └── securities_filing_tools.py
├── utils/ # 유틸리티 함수
│ ├── ctx_helper.py # 컨텍스트 처리 및 데이터 변환
│ ├── corp_code_search.py # 기업 코드 검색
│ ├── financial_notes_extractor.py # 재무제표 주석 추출
│ └── data/ # 캐시 데이터
│ ├── CORPCODE.xml # 기업 코드 목록 (필수)
│ └── disclosure_cache/ # 공시서류 캐시 (런타임 생성)
├── registry/ # 도구 레지스트리
│ ├── tool_registry.py
│ └── initialize_registry.py
└── prompt/ # 프롬프트 파일
└── system.prompt
```
## 주요 아키텍처
### FastMCP 구조
```mermaid
graph TD
A[FastMCP Server] --> B[opendart_lifespan]
B --> C[OpenDartContext 생성]
C --> D[전역 컨텍스트 저장]
C --> E[API 모듈 초기화]
E --> F[ds001~ds006]
A --> G[Tool 등록]
G --> H[tools/*.py 모듈]
H --> I[@mcp.tool 데코레이터]
I --> J[with_context 호출]
J --> K[전역 컨텍스트 fallback]
```
### 전역 컨텍스트 Fallback 메커니즘
- **목적**: streamable-http에서 ctx 주입이 없어도 동작하도록
- **구현**: `server.py`의 `set_global_context()`, `get_global_context()`
- **사용**: `ctx_helper.py`의 `with_context()` 함수에서 자동 fallback
- **참고**: [skills/context-handling.md](skills/context-handling.md)
### 캐시 시스템
- **CORPCODE.xml**: 기업 코드 목록 (필수, Docker 이미지에 포함)
- **disclosure_cache/**: 공시서류 및 재무제표 주석 캐시 (런타임 생성)
- **경로**: `src/mcp_opendart/utils/data/`
- **참고**: [skills/cache-management.md](skills/cache-management.md)
## 테스트 지침
### 테스트 실행
```bash
# 전체 테스트 실행
pytest
# 특정 파일 테스트
pytest tests/test_specific.py
# 커버리지 포함
pytest --cov=src/mcp_opendart
# 특정 테스트만 실행
pytest -k "test_function_name"
```
### Linting 및 타입 체크
```bash
# Ruff로 linting
ruff check src/
# 자동 수정
ruff check --fix src/
# Black으로 포맷팅
black src/
# MyPy 타입 체크
mypy src/
```
### 커밋 전 체크리스트
- [ ] `ruff check src/` 통과
- [ ] `mypy src/` 통과 (타입 에러 없음)
- [ ] `pytest` 통과
- [ ] 새로운 tool 추가 시 `tool_registry`에 등록 확인
## PR 및 커밋 가이드
### 커밋 메시지 형식
```
<type>: <간단한 설명>
<상세 설명 (선택)>
예시:
fix: Add global context fallback for streamable-http support
docs: Improve Docker section with clearer .env usage
feat: Add new tool for financial analysis
```
### PR 제목 형식
```
[<카테고리>] <제목>
예시:
[Fix] streamable-http에서 tools/call 실패 문제 해결
[Docs] Docker 배포 가이드 추가
[Feature] 새로운 재무 분석 도구 추가
```
### PR 전 체크리스트
- [ ] 모든 테스트 통과
- [ ] Linting 통과
- [ ] 타입 체크 통과
- [ ] README.md 업데이트 (필요시)
- [ ] 변경사항 설명 명확히 작성
## Docker 사용
### 이미지 빌드
```bash
docker build -t mcp-opendart:latest .
```
### 컨테이너 실행
```bash
# 환경변수 직접 전달
docker run -d --name mcp-opendart -p 8000:8000 \
-e OPENDART_API_KEY=your-key \
-e TRANSPORT=http \
mcp-opendart:latest
# .env 파일 사용
docker run -d --name mcp-opendart -p 8000:8000 \
--env-file .env \
mcp-opendart:latest
```
### 캐시 데이터 볼륨 마운트 (선택)
```bash
docker run -d --name mcp-opendart -p 8000:8000 \
-v $(pwd)/src/mcp_opendart/utils/data/disclosure_cache:/app/src/mcp_opendart/utils/data/disclosure_cache \
--env-file .env \
mcp-opendart:latest
```
**참고**: [skills/docker-deployment.md](skills/docker-deployment.md)
## 문제 해결
### 일반적인 문제
#### 1. "MCP context is required but not provided" 에러
- **원인**: streamable-http에서 ctx 주입 실패
- **해결**: 전역 컨텍스트 fallback이 자동으로 작동하므로, 서버 재시작 확인
- **참고**: [skills/context-handling.md](skills/context-handling.md)
#### 2. "CORPCODE.xml 파일이 없습니다" 에러
- **원인**: Docker 이미지에 CORPCODE.xml이 포함되지 않음
- **해결**: `.dockerignore`에서 `CORPCODE.xml` 예외 처리 확인
- **참고**: [skills/cache-management.md](skills/cache-management.md)
#### 3. Tools가 0개로 표시됨
- **원인**: Tool 모듈 import 실패
- **해결**: `server.py`에서 tool 모듈 import 확인, 로그에서 ImportError 확인
- **체크**: `docker logs <container> | grep -i "import\|error"`
#### 4. Docker 컨테이너가 시작되지 않음
- **원인**: CMD가 `main()` 함수를 호출하지 않음
- **해결**: Dockerfile의 CMD가 `python -c "from mcp_opendart.server import main; main()"`인지 확인
- **참고**: [skills/docker-deployment.md](skills/docker-deployment.md)
### 디버깅 팁
```bash
# 서버 로그 확인
docker logs mcp-opendart -f
# 컨테이너 내부에서 Python 모듈 확인
docker exec -it mcp-opendart python -c "import mcp_opendart; print(mcp_opendart.__file__)"
# Tool 모듈 import 테스트
docker exec -it mcp-opendart python -c "from mcp_opendart.tools import disclosure_tools; print('OK')"
```
## 주요 개발 워크플로우
### 새로운 Tool 추가
1. `src/mcp_opendart/tools/` 디렉토리에 새 파일 생성 또는 기존 파일 수정
2. `@mcp.tool` 데코레이터 사용
3. `with_context(None, ...)` 패턴 사용 (ctx 파라미터 제거)
4. `tool_registry`에 등록 (필요시)
5. `server.py`에서 모듈 import 확인
**참고**: [skills/tool-development.md](skills/tool-development.md)
### 새로운 API 통합
1. `src/mcp_opendart/apis/` 디렉토리에 새 API 클래스 생성
2. `OpenDartClient` 사용
3. `server.py`의 `OpenDartContext`에 추가
4. Tool에서 사용
**참고**: [skills/api-integration.md](skills/api-integration.md)
### 캐시 데이터 관리
1. `utils/data/` 디렉토리 구조 이해
2. `save_disclosure_cache()`, `load_disclosure_cache()` 사용
3. Docker에서 볼륨 마운트 고려
**참고**: [skills/cache-management.md](skills/cache-management.md)
## Skills 문서
프로젝트의 특정 기능에 대한 상세 가이드는 `skills/` 디렉토리를 참고하세요:
- [tool-development.md](skills/tool-development.md) - 새로운 MCP tool 추가 가이드
- [api-integration.md](skills/api-integration.md) - OpenDART API 통합 가이드
- [cache-management.md](skills/cache-management.md) - 캐시 데이터 관리 가이드
- [context-handling.md](skills/context-handling.md) - 컨텍스트 처리 가이드
- [financial-notes-extraction.md](skills/financial-notes-extraction.md) - 재무제표 주석 추출 가이드
- [docker-deployment.md](skills/docker-deployment.md) - Docker 배포 가이드
## 참고 자료
- [FastMCP 문서](https://gofastmcp.com)
- [MCP 스펙](https://modelcontextprotocol.io)
- [OpenDART API 가이드](https://opendart.fss.or.kr/)
