# Kiwoom API MCP Server

키움 REST API 문서를 검색하고 조회할 수 있는 MCP (Model Context Protocol) 서버입니다.

## 기능

- **API 검색**: API ID, 이름, 카테고리 등으로 키움 REST API 검색
- **API 상세 조회**: 특정 API의 요청/응답 파라미터, 예제 코드 확인
- **카테고리 목록**: 전체 API 카테고리 및 중분류 조회
- **요청 예제 생성**: Python, JavaScript, cURL 형식의 요청 예제 코드 생성

## Docker로 실행하기

### 1. Docker 이미지 빌드

```bash
docker build -t kiwoom-api-server:latest .
```

### 2. Docker 컨테이너 실행

```bash
docker run -d --name kiwoom-api-server \
  -p 8082:8082 \
  -e KIWOOM_DOCS_PATH=/app/kiwoom_api_docs.txt \
  -v "$(pwd)/kiwoom_api_docs.txt:/app/kiwoom_api_docs.txt:ro" \
  kiwoom-api-server:latest
```

### 3. 실행 확인

```bash
# 헬스 체크
curl http://localhost:8082/health

# 서버 정보 확인
curl http://localhost:8082/
```

### 4. 컨테이너 중지 및 삭제

```bash
# 컨테이너 중지
docker stop kiwoom-api-server

# 컨테이너 삭제
docker rm kiwoom-api-server
```

## Docker Compose로 실행하기

저장소에 포함된 `docker-compose.yml`을 그대로 사용하면 현재 폴더의 `kiwoom_api_docs.txt`를 컨테이너에 읽기 전용으로 마운트합니다.

실행:
```bash
docker-compose up -d
```

## 환경 변수

| 변수명 | 기본값 | 설명 |
|--------|--------|------|
| `PORT` | `8082` | 서버 포트 |
| `NODE_ENV` | `production` | 실행 환경 |
| `KIWOOM_DOCS_PATH` | `./kiwoom_api_docs.txt` | API 문서 파일 경로 |

## 엔드포인트

| 엔드포인트 | 메서드 | 설명 |
|-----------|--------|------|
| `/` | GET | 서버 정보 |
| `/sse` | GET | SSE MCP 엔드포인트 |
| `/message` | POST | MCP 메시지 엔드포인트 |
| `/health` | GET | 헬스 체크 |

## MCP 클라이언트 설정

### VS Code Cline (WSL)

Cline MCP 설정은 프로젝트 내부 파일이 아니라 **WSL 쪽 VS Code 확장 전역 설정 파일**에 저장됩니다.

- 설정 파일: `~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- 또는 Cline UI에서 **MCP Servers → Configure tab → Configure MCP Servers**

먼저 컨테이너를 실행한 뒤, 아래처럼 등록합니다.

```json
{
  "mcpServers": {
    "kiwoom-api-server": {
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8082/sse"
    }
  }
}
```

이 저장소 작업에서는 위 WSL 전역 설정 파일도 동일한 값으로 수정했습니다.

### Claude Desktop

Claude Desktop의 설정 파일에 다음을 추가:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kiwoom-api": {
      "url": "http://localhost:8082/sse"
    }
  }
}
```

### 다른 PC에서 접속

Docker 컨테이너가 실행 중인 PC의 IP 주소가 `192.168.1.100`이라면:

```json
{
  "mcpServers": {
    "kiwoom-api": {
      "url": "http://192.168.1.100:8082/sse"
    }
  }
}
```

## 제공되는 MCP 도구

1. **search_kiwoom_api**: 키움 REST API 검색
   - `query`: 검색어 (필수)
   - `category`: 카테고리 필터 (선택)
   - `subcategory`: 중분류 필터 (선택)

2. **get_kiwoom_api_detail**: 특정 API 상세 정보 조회
   - `api_id`: API ID (예: ka10001)

3. **list_kiwoom_apis**: API 목록 조회
   - `category`: 카테고리 필터 (선택)
   - `limit`: 결과 개수 제한 (기본값: 50)

4. **get_kiwoom_api_categories**: 카테고리 목록 조회

5. **get_kiwoom_request_example**: 요청 예제 코드 생성
   - `api_id`: API ID
   - `language`: 프로그래밍 언어 (python, javascript, curl)

## 로컬 개발

```bash
# 의존성 설치
npm install

# 빌드
npm run build

# 실행
npm start
```

## 라이선스

MIT