---
name: cache-management
description: 캐시 데이터 관리 및 사용 방법
---
# 캐시 관리 가이드
## 개요
이 skill은 MCP OpenDART 프로젝트의 캐시 데이터 관리 방법을 설명합니다. 프로젝트는 두 가지 주요 캐시를 사용합니다: CORPCODE.xml (기업 코드 목록)과 disclosure_cache (공시서류 캐시).
## 사용 시나리오
- CORPCODE.xml 파일 관리 및 업데이트
- 공시서류 캐시 저장 및 로드
- Docker 환경에서 캐시 데이터 처리
- 캐시 데이터 구조 이해
## 캐시 구조
### 1. CORPCODE.xml
**위치**: `src/mcp_opendart/utils/data/CORPCODE.xml`
**용도**: 기업 코드 목록 (기업명 -> 고유번호 매핑)
**특징**:
- OpenDART에서 제공하는 전체 기업 목록
- 약 28MB 크기
- Docker 이미지에 포함되어야 함 (필수)
- `get_corporation_code_by_name`에서 사용
**업데이트 방법**:
```python
# OpenDART API로 최신 버전 다운로드
# get_corporation_code() tool 사용
```
### 2. disclosure_cache/
**위치**: `src/mcp_opendart/utils/data/disclosure_cache/`
**용도**: 공시서류 및 재무제표 주석 캐시
**구조**:
```
disclosure_cache/
├── financial_notes_{rcp_no}/
│ ├── metadata.json
│ ├── consolidated_notes/ # 연결재무제표 주석
│ │ ├── metadata.json
│ │ ├── tables/
│ │ └── paragraphs/
│ ├── separate_notes/ # 재무제표 주석
│ │ ├── metadata.json
│ │ ├── tables/
│ │ └── paragraphs/
│ ├── business_content/ # 사업의 내용
│ │ └── subsections/
│ └── company_overview/ # 회사의 개요
│ └── subsections/
```
**특징**:
- 런타임에 자동 생성
- `get_disclosure_document` 실행 시 생성
- 재사용을 위해 영구 저장
- Docker에서 볼륨 마운트 권장
## 구현 가이드
### 1. 캐시 저장
```python
from mcp_opendart.utils.ctx_helper import save_disclosure_cache
# 공시서류 데이터 저장
cache_path = save_disclosure_cache(rcp_no="20240101000001", data=disclosure_data)
```
### 2. 캐시 로드
```python
from mcp_opendart.utils.ctx_helper import load_disclosure_cache
# 공시서류 캐시 로드
cached_data = load_disclosure_cache(rcp_no="20240101000001")
if cached_data:
# 캐시된 데이터 사용
pass
else:
# API 호출 필요
pass
```
### 3. 재무제표 주석 캐시
재무제표 주석은 별도 구조로 저장:
```python
from pathlib import Path
# 캐시 경로
project_root = Path(__file__).parent.parent.parent
cache_path = project_root / 'mcp_opendart' / 'utils' / 'data' / 'disclosure_cache' / f'financial_notes_{rcp_no}'
# 캐시 확인
if cache_path.exists():
# 캐시된 데이터 사용
pass
```
### 4. CORPCODE.xml 읽기
```python
from mcp_opendart.utils.corp_code_search import read_local_xml, parse_corp_code_xml
# XML 파일 읽기
xml_content = read_local_xml() # utils/data/CORPCODE.xml
corporations = parse_corp_code_xml(xml_content)
```
## Docker 환경에서의 캐시
### 1. CORPCODE.xml 포함
`.dockerignore`에서 예외 처리:
```dockerignore
*.xml
!src/mcp_opendart/utils/data/CORPCODE.xml
```
### 2. disclosure_cache 볼륨 마운트
컨테이너 재시작 시에도 캐시 유지:
```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
```
### 3. 캐시 경로 확인
컨테이너 내부에서 캐시 경로 확인:
```bash
docker exec -it mcp-opendart ls -la /app/src/mcp_opendart/utils/data/
```
## 예제
### 예제 1: 캐시 확인 후 API 호출
```python
def get_disclosure_with_cache(self, rcp_no: str) -> Dict[str, Any]:
"""
캐시 확인 후 없으면 API 호출
"""
# 캐시 확인
cached = load_disclosure_cache(rcp_no)
if cached:
return cached
# API 호출
response = self.client._make_request("document.xml", {"rcept_no": rcp_no})
# 캐시 저장
if response.get("status") == "000":
save_disclosure_cache(rcp_no, response)
return response
```
### 예제 2: 재무제표 주석 캐시 확인
```python
from pathlib import Path
def check_financial_notes_cache(rcp_no: str) -> bool:
"""
재무제표 주석 캐시 존재 여부 확인
"""
project_root = Path(__file__).parent.parent.parent
cache_path = project_root / 'mcp_opendart' / 'utils' / 'data' / 'disclosure_cache' / f'financial_notes_{rcp_no}'
return cache_path.exists() and (cache_path / 'consolidated_notes').exists()
```
## 주의사항
1. **CORPCODE.xml 필수**
- Docker 이미지에 반드시 포함
- 없으면 `get_corporation_code_by_name` 실패
2. **캐시 크기 관리**
- `disclosure_cache/`는 계속 증가
- 필요시 오래된 캐시 정리 로직 추가
3. **경로 일관성**
- 모든 캐시 경로는 `Path(__file__).parent.parent.parent` 기준
- 상대 경로 사용으로 이식성 확보
4. **Docker 볼륨 마운트**
- `disclosure_cache/`는 볼륨 마운트 권장
- 컨테이너 재시작 시에도 캐시 유지
5. **캐시 무효화**
- 현재는 수동 삭제만 가능
- 필요시 TTL 기반 자동 삭제 로직 추가 고려
## 관련 파일
- [src/mcp_opendart/utils/ctx_helper.py](src/mcp_opendart/utils/ctx_helper.py) - save_disclosure_cache, load_disclosure_cache
- [src/mcp_opendart/utils/corp_code_search.py](src/mcp_opendart/utils/corp_code_search.py) - CORPCODE.xml 읽기
- [src/mcp_opendart/utils/data/CORPCODE.xml](src/mcp_opendart/utils/data/CORPCODE.xml) - 기업 코드 목록
- [.dockerignore](.dockerignore) - Docker 빌드 제외 설정
