# 🏢 한국 기업정보 조회 MCP 서버

**DART API**를 활용한 MCP (Model Context Protocol) 서버입니다.

AI 에이전트(Claude Desktop, Cursor 등)가 실시간으로 한국 상장기업의 재무제표, 공시정보, 임원정보, 지분구조 등을 조회하고 분석할 수 있도록 합니다.

---

## ✨ 주요 기능

### 📊 기업 정보 조회 (DART API)

| 기능               | 설명                                                |
| ------------------ | --------------------------------------------------- |
| **기업 검색**      | 회사명으로 기업 검색 및 기본정보 조회               |
| **기업 기본정보**  | 회사명, 대표자명, 설립일, 본사주소 등 기본정보 조회 |
| **재무제표 조회**  | 손익계산서, 재무상태표, 현금흐름표                  |
| **재무 추이 분석** | 최근 5-10년 재무제표 추이 분석                      |
| **공시정보 조회**  | 최근 공시 목록 및 상세 내용                         |
| **임원정보 조회**  | 임원명, 직책, 보수 등 임원정보 조회                 |
| **지분보고서**     | 주주명, 보유지분, 비율 등 지분구조 조회             |

### 🚀 성능 최적화

- **전략적 캐싱**: 기업정보 데이터를 24시간 캐싱하여 API 호출 최소화
- **빠른 응답 속도**: 캐시 기반 즉시 응답
- **안정적인 운영**: 에러 핸들링 및 로깅 시스템
- **API 키 우선순위**: 메인 서버에서 받은 키 → .env 파일 (로컬 개발용)

---

## 🛠️ 기술 스택

- **MCP Framework**: FastMCP
- **Data Validation**: Pydantic
- **HTTP Client**: Requests
- **Caching**: cachetools (TTL 캐시)
- **Async Processing**: asyncio
- **Environment**: Python-dotenv

---

## 📦 설치 및 설정

### 1) 의존성 설치

```bash
pip install -r requirements.txt
```

> 💡 `uv`를 사용하는 경우: `uv sync`

### 2) DART API 키 발급 (무료, 즉시)

1. [전자공시시스템 Open DART](https://opendart.fss.or.kr/) 방문
2. 회원가입 및 로그인
3. **인증키 신청/관리** 메뉴에서 인증키 발급
4. **즉시 발급** (무료)

> 💡 **무료**이며, 일일 API 호출 제한이 충분히 넉넉합니다!

### 3) 환경 변수 설정

프로젝트 루트에 `.env` 파일을 생성하고 API 키를 설정합니다:

```bash
cp env.example .env
```

`.env` 파일 내용:

```env
DART_API_KEY=your_dart_api_key_here
LOG_LEVEL=INFO
PORT=8097
```

### 4) 서버 실행

#### MCP 서버 모드 (stdio)

```bash
python -m src.main
```

#### HTTP 서버 모드

```bash
HTTP_MODE=1 python -m src.main
```

HTTP 서버는 기본적으로 `http://localhost:8097`에서 실행됩니다.

---

## 🔌 MCP 클라이언트 설정

### Claude Desktop

`claude_desktop_config.json` 파일에 다음을 추가:

**설정 파일 위치:**

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

**설정 예시:**

```json
{
  "mcpServers": {
    "company-info": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/company-info-mcp",
      "env": {
        "DART_API_KEY": "your_dart_api_key_here"
      }
    }
  }
}
```

> ⚠️ **중요**: `cwd` 경로를 실제 프로젝트 경로로 변경하세요!

### Cursor

Cursor의 MCP 설정에서 위와 동일한 설정을 추가합니다.

---

## 🧰 사용 가능한 MCP 도구

### `search_company_tool`

회사명으로 기업을 검색합니다.

**파라미터:**

- `company_name` (필수): 검색할 회사명

### `get_company_overview_tool`

기업의 기본정보를 조회합니다.

**파라미터:**

- `corp_code` (선택): 기업 고유번호
- `company_name` (선택): 회사명 (corp_code 또는 company_name 중 하나 필수)

### `get_financial_statement_tool`

기업의 재무제표를 조회합니다.

**파라미터:**

- `corp_code` (선택): 기업 고유번호
- `company_name` (선택): 회사명
- `bsns_year` (선택): 사업연도 (YYYY 형식)
- `reprt_code` (선택): 보고서 코드 (기본값: "11011")

### `analyze_financial_trend_tool`

기업의 재무 추이를 분석합니다 (최근 N년).

**파라미터:**

- `corp_code` (필수): 기업 고유번호
- `years` (선택): 분석할 연수 (기본값: 5, 최대: 10)

### `get_public_disclosure_tool`

기업의 공시정보를 조회합니다.

**파라미터:**

- `corp_code` (필수): 기업 고유번호
- `bgn_de` (선택): 시작일 (YYYYMMDD 형식)
- `end_de` (선택): 종료일 (YYYYMMDD 형식)
- `page_no` (선택): 페이지 번호 (기본값: 1)
- `page_count` (선택): 페이지당 건수 (기본값: 10)

### `get_executives_tool`

기업의 임원정보를 조회합니다.

**파라미터:**

- `corp_code` (선택): 기업 고유번호
- `company_name` (선택): 회사명
- `bsns_year` (선택): 사업연도 (YYYY 형식)
- `reprt_code` (선택): 보고서 코드 (기본값: "11011")

### `get_shareholders_tool`

지분보고서를 조회합니다.

**파라미터:**

- `corp_code` (선택): 기업 고유번호
- `company_name` (선택): 회사명
- `bsns_year` (선택): 사업연도 (YYYY 형식)
- `reprt_code` (선택): 보고서 코드 (기본값: "11011")

---

## 📡 HTTP API 엔드포인트

HTTP 모드로 실행 시 다음 엔드포인트를 사용할 수 있습니다:

### Health Check

```bash
GET /health
POST /health
```

### 도구 목록 조회

```bash
GET /tools
```

### 도구 실행

```bash
POST /tools/{tool_name}
Content-Type: application/json

{
  "company_name": "삼성전자",
  "env": {
    "DART_API_KEY": "your_api_key"
  }
}
```

---

## 🐳 Docker 실행

```bash
# 이미지 빌드
docker build -t company-info-mcp:latest .

# 컨테이너 실행
docker run --rm \
  -e DART_API_KEY=your_dart_api_key_here \
  -p 8097:8097 \
  company-info-mcp:latest
```

---

## 🔑 API 키 우선순위

MCP 서버는 다음 순서로 API 키를 찾습니다:

1. **우선순위 1**: `arguments.env.DART_API_KEY` (메인 서버에서 받은 키)
2. **우선순위 2**: `.env` 파일의 `DART_API_KEY` (로컬 개발용)
3. **둘 다 없으면**: Health 체크에서 "등록된 키가 없습니다" 반환

이를 통해:

- **프로덕션**: 메인 서버에서 각 사용자별 키를 전달받아 사용
- **로컬 개발**: `.env` 파일에 키를 설정하여 개발

---

## 🐛 문제 해결

### "API 키가 설정되지 않았습니다" 오류

**해결 방법:**

1. `.env` 파일에 `DART_API_KEY`가 올바르게 설정되어 있는지 확인
2. 환경 변수로 직접 설정: `export DART_API_KEY=your_key`

### MCP 클라이언트 연결 오류

**해결 방법:**

1. 서버가 올바르게 실행되고 있는지 확인
2. Python 경로가 올바른지 확인
3. 의존성이 모두 설치되었는지 확인: `pip install -r requirements.txt`
4. `cwd` 경로를 실제 프로젝트 경로로 변경
5. Claude Desktop 완전 종료 후 재시작

---

## 📄 라이선스

이 프로젝트는 DART API를 사용하며, DART API의 이용약관을 준수합니다.