# ecos-mcp-server

한국은행 ECOS(경제통계시스템) Open API를 위한 MCP(Model Context Protocol) 서버.
`/mnt/skills/user/bok-ecos/SKILL.md`의 원칙(추측 금지, ECOS 원자료만 사용, 오류 시 다른
출처로 대체 금지)을 도구 설명(description)에 그대로 내장해두었습니다 — Claude가 이
서버의 툴을 쓸 때 같은 규칙을 자연히 따르게 됩니다.

## 제공 도구 (5개)

| 도구 | 대응 ECOS 서비스 | 용도 |
|---|---|---|
| `ecos_search_series` | StatisticSearch | 실제 시계열 데이터 조회 |
| `ecos_list_tables` | StatisticTableList | 통계표 코드 탐색 |
| `ecos_list_items` | StatisticItemList | 특정 통계표의 항목코드/주기/단위 확인 |
| `ecos_key_statistics` | KeyStatisticList | 100대 핵심지표 |
| `ecos_search_word` | StatisticWord | 통계 용어 설명 |

모든 도구는 ECOS가 실제로 반환한 JSON을 그대로(`raw`) 포함해서 돌려주고,
실패 시에도 `ok: false`와 함께 ECOS의 실제 오류 코드/메시지를 그대로 전달합니다 —
서버가 임의로 값을 만들어내지 않습니다.

---

## 방법 1 — 로컬 사용 (Claude Code / Claude Desktop)

가장 빠르게 시작하는 방법입니다. 컴퓨터의 인터넷 연결을 그대로 쓰므로
별도 배포 없이 바로 동작합니다.

### 1) 설치

```bash
cd ecos-mcp-server
npm install
cp .env.example .env
# .env 파일을 열어 ECOS_API_KEY=발급받은키  로 채워넣기
```

### 2) 단독 실행 테스트 (선택)

```bash
npm run start:stdio
```
`stdio transport ready` 로그가 뜨면 정상입니다. Ctrl+C로 종료하세요.

### 3) Claude Code에 등록

Claude Code 프로젝트 루트(또는 전역 설정)의 `.mcp.json`에 추가:

```json
{
  "mcpServers": {
    "bok-ecos": {
      "command": "node",
      "args": ["/절대/경로/ecos-mcp-server/src/stdio.js"],
      "env": {
        "ECOS_API_KEY": "발급받은키"
      }
    }
  }
}
```

또는 터미널에서 바로 등록:

```bash
claude mcp add bok-ecos -- node /절대/경로/ecos-mcp-server/src/stdio.js
```

### 4) Claude Desktop에 등록 (Code 탭 포함)

`claude_desktop_config.json` (Mac: `~/Library/Application Support/Claude/`,
Windows: `%APPDATA%\Claude\`)에 동일한 형식으로 추가 후 Claude Desktop 재시작.

등록 후에는 채팅에서 바로 이렇게 요청하면 됩니다:

> "ecos_list_tables로 '잠재' 관련 통계표를 찾아줘"
> "ecos_search_series로 722Y001(기준금리) 최근 10년치를 연도별로 조회해줘"

---

## 방법 2 — 원격 배포 (claude.ai 웹/모바일 커넥터)

claude.ai 채팅창(이 환경)에서 직접 쓰려면, 공인 URL로 접근 가능한 서버가 필요합니다.
아래는 Render.com 무료/저가 플랜 기준 예시입니다 (Railway, Fly.io 등도 동일한 방식).

### 1) GitHub에 푸시

```bash
cd ecos-mcp-server
git init
git add .
git commit -m "ecos mcp server"
git remote add origin <본인의 github 저장소 URL>
git push -u origin main
```

### 2) Render.com에서 배포

1. https://render.com → New → Web Service → 방금 만든 저장소 선택
2. Build Command: `npm install`
3. Start Command: `npm start`
4. Environment → `ECOS_API_KEY` = 발급받은 개인 키 추가
5. 배포 완료 후 발급되는 URL 확인 (예: `https://ecos-mcp-server.onrender.com`)

### 3) claude.ai에 커넥터로 등록

1. claude.ai → 설정(Settings) → Connectors → "Add custom connector"
2. URL에 `https://ecos-mcp-server.onrender.com/mcp` 입력 (경로 끝에 `/mcp` 필수)
3. 저장 후 새 대화에서 도구 목록에 `bok-ecos`가 나타나는지 확인

이후로는 claude.ai 채팅에서 "기준금리 최근 조회해줘"처럼 자연어로 요청하면
Claude가 해당 도구를 호출해 실제 ECOS 응답을 기반으로 답합니다.

> 무료 플랜은 일정 시간 미사용 시 서버가 슬립 상태가 되어 첫 호출이 느릴 수 있습니다.
> 자주 쓰신다면 유료 플랜이나 상시 구동 인스턴스를 권장합니다.

---

## 개인 키 vs 공개(sample) 키

- `ECOS_API_KEY`를 설정하지 않으면 공개 `sample` 키로 동작하며, ECOS 정책상
  **1회 호출당 최대 10행**으로 제한됩니다.
- 개인 키(예: 기존에 쓰시던 `M8JW6WYR9SUATYN29MGE`)를 넣으면 더 큰 범위를
  한 번에 조회할 수 있습니다. 정확한 최대 행 수는 ECOS 공식 문서/마이페이지에서
  확인하시는 것이 가장 정확합니다 (이 서버가 임의로 단정하지 않습니다).

## 안전 설계 원칙

- 코드에 API 키를 하드코딩하지 않고 환경변수로만 주입합니다.
- ECOS가 HTTP 200이면서 내부적으로 오류(`INFO-200`, `ERROR-301`, `ERROR-602` 등)를
  반환하는 경우를 감지해 그대로 `ok:false`로 전달합니다 — 다른 출처로 대체하지 않습니다.
- 모든 응답에 실제 요청 URL(키는 `***`로 마스킹)을 포함해 검증 가능성을 남깁니다.