# 🇰🇷 Korea Stats MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
[![Deploy](https://img.shields.io/badge/Vercel-Deployed-black)](https://korea-stats-mcp.vercel.app/)
[![npm](https://img.shields.io/npm/v/@kimdayoun/korea-stats-mcp)](https://www.npmjs.com/package/@kimdayoun/korea-stats-mcp)

> **이 저장소가 원본입니다.** 정본: https://github.com/Dayoooun/korea-stats-mcp
> npm 배포본은 **`@kimdayoun/korea-stats-mcp`** 하나뿐입니다.
> `kosis-mcp` 등 스코프 없는 동명 패키지는 이 프로젝트와 무관한 제3자 배포본입니다.

> **자연어로 KOSIS 통계를 조회하는 MCP 서버**

통계청 KOSIS OpenAPI 기반의 MCP(Model Context Protocol) 서버입니다.
Claude Code와 Codex에서 **자연어로 한국 통계 데이터**를 검색하고 분석할 수 있습니다.

**원격 서버 URL:** `https://korea-stats-mcp.vercel.app/mcp`

**📦 로컬 설치:**

```bash
npx -y @kimdayoun/korea-stats-mcp
```

MCP 클라이언트 설정:

```json
{
  "mcpServers": {
    "korea-stats": {
      "command": "npx",
      "args": ["-y", "@kimdayoun/korea-stats-mcp"]
    }
  }
}
```

---

## 🎯 왜 만들었나요?

AI에게 **"한국 인구가 몇 명이야?"** 라고 물으면, AI는 학습 데이터의 오래된 정보를 답합니다.
Korea Stats MCP를 연결하면 **실시간 공식 통계**를 조회해서 정확한 답변을 제공합니다.

| Before (MCP 없이)                      | After (Korea Stats MCP 연결)                     |
| -------------------------------------- | ------------------------------------------------ |
| Q: 한국 인구가 몇 명이야?              | Q: 한국 인구가 몇 명이야?                        |
| A: 2023년 기준 약 5,100만 명입니다. ❌ | A: 2024년 한국의 총인구는 51,712,619명입니다. ✅ |

---

## ✨ 주요 기능

| 기능             | 설명                                                          |
| ---------------- | ------------------------------------------------------------- |
| **빠른 조회**    | "실업률", "GDP", "출산율", "미세먼지" 등 사전설정 키워드 조회 |
| 📈 **추세 분석** | 최근 N년간 데이터 추이 및 변화율 분석                         |
| **통계 검색**    | KOSIS OpenAPI 공개 통계표에서 키워드 검색                     |
| 📊 **비교 분석** | 연도별, 지역별, 항목별 통계 비교                              |
| **지역별 조회**  | 공식 분류에 따른 시도·시군구 조회, 통계표별 지원 범위 확인    |

---

## 🚀 사용 방법

### 방법 1: 원격 서버 사용 (설치 없이 바로 사용) ⭐ 권장

설치 없이 원격 MCP 서버에 바로 연결할 수 있습니다.

#### Claude Code

```bash
claude mcp add --scope user --transport http korea-stats https://korea-stats-mcp.vercel.app/mcp
claude mcp get korea-stats
```

#### Codex

```bash
codex mcp add korea-stats --url https://korea-stats-mcp.vercel.app/mcp
codex mcp get korea-stats
```

두 클라이언트 모두 네이티브 HTTP 연결을 사용하므로 `mcp-remote`나 사용자 KOSIS 키가 필요하지 않습니다. 등록 후 새 Claude Code 또는 Codex 세션에서 MCP 도구를 호출하세요. 이미 같은 이름의 서버가 등록돼 있다면 기존 설정을 먼저 확인하고 덮어쓰지 마세요.

같은 URL을 이미 사용 중이라면 삭제·재등록은 필수가 아닙니다. 도구 목록이 갱신되지 않는 클라이언트에서는 새로고침 또는 재연결하세요.

#### 현재 확인된 제한 (2026-09-10)

- 공개 서버의 구·군 조회와 지역 구분은 실제 호출로 확인했지만, 모든 통계표가 모든 시군구를 제공하는 것은 아닙니다.
- 독립 검증에서 `get_indicator`의 지표 정의 조회가 KOSIS 오류 `30`으로 실패했습니다. 지표 검색 성공이 모든 지표 상세·값 조회의 성공을 의미하지 않습니다.
- `get_indicator`, `search_businesses`, `get_microdata_info`의 공개 `tools/list`에서 입력 스키마의 `properties`가 비어 있는 문제가 확인됐습니다. 인자를 직접 지정한 호출이 성공하더라도 AI의 자동 도구 선택·인자 구성까지 보장하지 않습니다.
- MDIS는 공개 카탈로그·메타데이터 조회 범위이며, 연구용 원자료 다운로드·로그인·별도 접근 승인을 대신하지 않습니다.
- 공개 서버 배포, GitHub 소스, npm 게시 버전은 별개입니다. 이 소스의 개선 사항이 npm 최신 배포본에도 모두 포함됐다고 가정하지 마세요.

---

### 방법 2: 로컬 설치

직접 서버를 실행하고 싶다면 로컬에 설치할 수 있습니다.

#### 1단계: 설치

```bash
# 저장소 클론
git clone https://github.com/Dayoooun/korea-stats-mcp.git
cd korea-stats-mcp

# 의존성 설치 (pnpm 권장)
pnpm install

# 빌드
pnpm run build
```

#### 2단계: AI 도구에 연결

**Claude Code**:

```bash
claude mcp add --scope user --transport stdio korea-stats-local -- node /절대경로/korea-stats-mcp/dist/index.js
```

**Codex**:

```bash
codex mcp add korea-stats-local -- node /절대경로/korea-stats-mcp/dist/index.js
```

실제 빌드 파일의 절대경로를 사용하세요. 원격 연결만 필요하면 로컬 등록은 하지 않습니다. npm 게시본과 이 저장소의 빌드·운영 배포 버전은 별개이므로, 새 버전을 npm에 게시했다고 가정하지 마세요.

---

### 방법 3: Kakao PlayMCP

[Kakao PlayMCP](https://playmcp.com/)에서도 사용할 수 있습니다.

1. PlayMCP 사이트 접속
2. **korea-stats-mcp** 검색
3. 클릭 한 번으로 연결 완료!

---

## 💬 사용 예시

연결 후 AI에게 자연어로 질문하세요:

```
"한국 인구가 몇 명이야?"
"서울 실업률 알려줘"
"최근 10년 출산율 추이 보여줘"
"GDP 성장률은?"
"부산과 대구 인구 비교해줘"
"서울 아파트가격 알려줘"
"경기도 GRDP 얼마야?"
"평균 임금 알려줘"
"2024년 10월 출생아수 알려줘"   # 월별 데이터
"서울 전세가격"                # 🆕 전세
"경기 자동차 등록대수"          # 🆕 자동차
"부산 범죄율"                  # 🆕 범죄
"외래관광객 몇 명이야?"
"교통사고 발생건수"            # 🆕 교통사고
"서울 의사수 알려줘"           # 🆕 의료
```

**실제 응답 예시:**

```
✅ "2025년 한국의 주민등록 총인구는 51,117,378명입니다."
✅ "2024년 서울의 실업률은 3%입니다."
✅ "2025년 3월 서울의 아파트매매가격지수는 99.687 (2021.6=100)입니다."
✅ "2025년 한국의 상용근로자 월평균 임금은 4,094,615원입니다."
✅ "2024년 경기의 지역내총생산(명목)은 651,417,234백만원입니다."
✅ "2025년 3월 서울의 주택전세가격지수는 94.134 (2021.6=100)입니다."
✅ "2024년 서울의 자동차 등록대수는 3,176,933대입니다."
✅ "2024년 부산의 인구 천명당 범죄발생건수는 34.4건입니다."
✅ "2025년 11월 한국의 외래관광객수는 1,596,939명입니다."
✅ "2024년 한국의 교통사고 발생건수는 168,585건입니다."
✅ "2024년 서울의 의료기관 종사 의사수는 43,547명입니다."
```

---

## 빠른 조회 키워드

현재 사전설정은 동의어를 포함해 91개 키워드입니다. 아래 목록은 빠른 조회 예시이며 전체 지원 통계표의 상한이 아닙니다. 다른 통계는 `search_statistics`와 공식 분류 메타데이터로 탐색하세요.

### 인구/출산/사망

| 키워드                                     | 설명       | 주기       |
| ------------------------------------------ | ---------- | ---------- |
| `인구`, `총인구`                           | 총인구수   | 연         |
| `출산율`, `합계출산율`                     | 합계출산율 | 연         |
| `출생아수`, `출생아`, `조출생률`           | 출생 통계  | 연/분기/월 |
| `사망자수`, `사망자`, `조사망률`, `사망률` | 사망 통계  | 연/분기/월 |
| `자연증가`, `자연증가율`                   | 자연증감   | 연/분기/월 |
| `기대수명`, `기대여명`, `평균수명`         | 기대수명   | 연         |

### 혼인/이혼

| 키워드                           | 설명      | 주기       |
| -------------------------------- | --------- | ---------- |
| `혼인율`, `혼인건수`, `조혼인율` | 혼인 통계 | 연/분기/월 |
| `이혼율`, `이혼건수`, `조이혼율` | 이혼 통계 | 연/분기/월 |

### 고용/노동

| 키워드                                   | 설명                            | 주기 |
| ---------------------------------------- | ------------------------------- | ---- |
| `실업률`                                 | 실업률 (시도별 지원)            | 연   |
| `고용률`                                 | 고용률 (시도별 지원)            | 연   |
| `취업자수`, `취업자`                     | 취업자 수                       | 연   |
| `실업자수`, `실업자`                     | 실업자 수                       | 연   |
| `경제활동인구`, `비경제활동인구`         | 경제활동인구                    | 연   |
| `임금`, `월평균임금`, `월급`, `평균임금` | 상용근로자 월평균 임금 (시도별) | 연   |

### 경제

| 키워드                                 | 설명                  | 주기  |
| -------------------------------------- | --------------------- | ----- |
| `GDP`, `국내총생산`                    | GDP (국내총생산)      | 연    |
| `GRDP`, `지역내총생산`                 | 지역내총생산 (시도별) | 연    |
| `경제성장률`, `성장률`, `GDP성장률`    | 경제성장률            | 연    |
| `물가`, `소비자물가`, `소비자물가지수` | 소비자물가 (시도별)   | 연/월 |

### 무역

| 키워드           | 설명     | 주기 |
| ---------------- | -------- | ---- |
| `수출액`, `수출` | 수출액   | 연   |
| `수입액`, `수입` | 수입액   | 연   |
| `무역수지`       | 무역수지 | 연   |

### 부동산

| 키워드                                                     | 설명                        | 주기 |
| ---------------------------------------------------------- | --------------------------- | ---- |
| `주택가격`, `주택매매가격`, `주택가격지수`                 | 주택매매가격지수 (시도별)   | 월   |
| `아파트`, `아파트가격`, `아파트매매가격`, `아파트가격지수` | 아파트매매가격지수 (시도별) | 월   |
| `전세`, `전세가격`, `전세가격지수`, `주택전세`             | 주택전세가격지수 (시도별)   | 월   |
| `아파트전세`, `아파트전세가격`                             | 아파트전세가격지수 (시도별) | 월   |

### 자동차/교통 🆕

| 키워드                               | 설명                     | 주기 |
| ------------------------------------ | ------------------------ | ---- |
| `자동차`, `자동차등록`, `자동차대수` | 자동차 등록대수 (시도별) | 연   |

### 범죄/치안 🆕

| 키워드                       | 설명                              | 주기 |
| ---------------------------- | --------------------------------- | ---- |
| `범죄`, `범죄율`, `범죄발생` | 인구 천명당 범죄발생건수 (시도별) | 연   |

### 관광

| 키워드                           | 설명                | 주기 |
| -------------------------------- | ------------------- | ---- |
| `관광객`, `외래관광객`, `입국자` | 외래관광객 입국자수 | 월   |

### 교통/안전 🆕

| 키워드                                 | 설명                       | 주기 |
| -------------------------------------- | -------------------------- | ---- |
| `교통사고`, `교통사고발생`, `사고건수` | 교통사고 발생건수 (시도별) | 연   |

### 의료/건강

| 키워드                       | 설명                          | 주기 |
| ---------------------------- | ----------------------------- | ---- |
| `의사`, `의사수`, `의료인력` | 의료기관 종사 의사수 (시도별) | 연   |

### 대기환경 🆕

| 키워드                                        | 설명                            | 주기 |
| --------------------------------------------- | ------------------------------- | ---- |
| `미세먼지`, `PM2.5`, `초미세먼지`, `대기오염` | 초미세먼지(PM2.5) 농도 (시도별) | 월   |
| `PM10`                                        | 미세먼지(PM10) 농도 (시도별)    | 월   |

---

## 🗺️ 지역별 조회

지역 지원 범위는 선택한 통계표의 공식 분류에 따라 결정됩니다. 시군구는 ITM 메타데이터와 실제 응답의 분류축을 확인해 조회하며, 코드 길이로 지역을 추측하지 않습니다. 동명이거나 요청한 하위 지역을 확인할 수 없으면 상위 지역·전국 값으로 대신 답하지 않습니다.

KOSIS에 중간 시 이름이 빠진 `수원시 영통구` 같은 요청은, 실제 KOSIS 분류축·코드가 확인된 단일 후보에 한해 공식 상권정보의 시군구 전체 이름을 한 번 대조합니다. 시군구 코드·시도 코드·공식 시도명·전체 이름이 정확히 맞아야 답합니다. 확인 자료나 운영자 키가 없으면 검증을 보류하며, 현재 명칭의 소속을 확인한 것이 과거 행정경계의 동일성을 입증하지는 않습니다. 이 한계는 응답의 `caveats`에도 남깁니다.

**시도 입력 예시(지원 범위의 상한이 아닙니다):**
전국, 서울, 부산, 대구, 인천, 광주, 대전, 울산, 세종, 경기, 강원, 충북, 충남, 전북, 전남, 경북, 경남, 제주

**예시:**

```
"서울 인구"
"부산 실업률"
"제주 출산율"
"경기도 고용률"
"서울 아파트가격"
"경기 GRDP"
"울산 임금"
"서울 전세가격"
"경기 자동차"
"부산 범죄율"
"서울 교통사고"           # 🆕 교통사고
"부산 의사수"             # 🆕 의료
```

---

## 📅 월별/분기별 조회 🆕

일부 통계는 월별 또는 분기별 조회가 가능합니다:

**예시:**

```
"2024년 10월 출생아수"    # 월별 조회
"2024년 3분기 사망자수"   # 분기별 조회
"2025년 1월 주택가격"     # 월별 조회
```

**지원 통계:** 출생아수, 사망자수, 혼인건수, 이혼건수, 자연증가, 물가, 주택가격, 아파트가격, 전세가격, 관광객

---

## 제공 도구 (개발본 14개)

이 목록은 현재 소스 기준입니다. 공개 원격 서버와 npm 배포본의 실제 도구는 해당 배포 버전의 `tools/list`로 확인하세요. 키 없는 로컬 실행은 공개 원격 배포본을 이용하므로 아직 배포하지 않은 로컬 변경을 제공하지 않습니다.

### 핵심 도구 ⭐

| 도구          | 설명                      | 예시                                              |
| ------------- | ------------------------- | ------------------------------------------------- |
| `quick_stats` | 사전설정 키워드 빠른 조회 | "실업률", "GDP", "미세먼지", "교통사고", "의사수" |
| `quick_trend` | 시계열 추세 분석          | "출산율 10년 추이"                                |

### 고급 도구

| 도구                         | 설명                                                                          |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `search_statistics`          | KOSIS 통계표 키워드 검색                                                      |
| `get_statistics_list`        | 주제별/기관별 통계 목록 탐색                                                  |
| `get_statistics_data`        | 특정 통계표 데이터 조회                                                       |
| `compare_statistics`         | 시점별/항목별 비교 분석                                                       |
| `analyze_time_series`        | 상세 시계열 분석                                                              |
| `get_recommended_statistics` | 분야별 추천 통계                                                              |
| `get_table_info`             | 공식 분류·항목 메타데이터와 근거를 바이트 제한 내에서 페이지별 조회           |
| `search_indicators`          | 공식 지표 이름·ID·수록주기 검색                                               |
| `get_indicator`              | 검색한 지표의 공식 정의 또는 원자료 값 조회                                   |
| `search_businesses`          | 공공 상권정보의 지역·업종별 사업체 원자료를 페이지별 취득                     |
| `search_microdata`           | MDIS 공개 조사 카탈로그 검색                                                  |
| `get_microdata_info`         | 일반 조사 상세 또는 서비스 유형별 공개 변수·코드북 확인과 공식 이용 경로 안내 |

### 자료 해석과 이용 경계

- KOSIS 분류코드와 상권 API의 행정구역 코드는 서로 다를 수 있습니다. 공급자별 공식 코드를 구분하세요.
- 출처·조회 시각·원래 기간·단위·식별자와 검증 범위를 함께 확인하세요. 누락된 근거는 `unknown`, `partial`, `unverified` 등의 표시로 구분하며 단위·결측값·범주 의미를 임의로 채우지 않습니다.
- 연·월·분기 범위 조회는 항목·분류 조합별 시작·종료 시점과 내부 누락을 검사합니다. 기간 근거가 불완전하면 `response_incomplete`로 실패하며 반환 가능한 원본은 `data[].raw`에 남깁니다. 일정한 주기를 입증할 수 없는 주기는 미검증으로 표시합니다.
- 기간을 지정하지 않거나 `recentCount`만 사용한 응답은 최신성·전체성을 입증하지 못하므로 미검증입니다. 요청한 최근 관측 수보다 적거나 관측 식별자가 중복되면 실패합니다.
- `get_statistics_data`의 양끝이 명시된 연·월·분기 범위는 `pageSize`(기본 50, 최대 200)와 `cursor`로 이어받습니다. 공급자 응답 4 MiB 초과 시 기간을 분할하며, 단일 기간도 초과하면 선택 조건을 좁혀야 합니다. MCP 응답은 32 KiB 이내이며 원시 관측 하나를 임의로 자르지 않습니다.
- 공식 코드의 `+` 다중 선택식도 공급자에 그대로 전달하며 단일 코드로 오인하지 않습니다. 다중 선택 응답은 `unverified`로 표시하며, 페이지 순회 완료와 공급자 전체성 검증은 별개입니다.
- `hasMore`가 참이면 원래 조건 그대로 `nextCursor`를 넘기세요. `partition_split` 진행 페이지는 0행일 수 있습니다. 마지막 페이지의 `completion: "complete"`도 요청 기간 순회 완료이지 공급자 전체 자료·전체 시점의 동일 스냅샷을 입증한 것은 아닙니다. 앞 페이지들을 합쳐야 전체 반환 관측을 얻습니다.
- 운영 HTTP 서버는 2.0.0으로 배포·검증됐습니다. npm 게시본은 별개이며 새 버전 게시가 완료됐다는 뜻은 아닙니다. 기존 통계자료 `totalCount` 대신 `returnedCount`·`emittedCount`·`aggregateRowCount`를 구분합니다.
- 분석·비교의 출처 목록은 요청한 논리 조회이며 실제 네트워크 호출 이력이나 캐시 최신성 증명이 아닙니다. 조회 시각·미제공 메타·출처 진단의 절단 여부와 계산 성공 여부를 구분해 반환합니다.
- 시점 비교에는 서로 다른 시점이 최소 2개 필요합니다. 기준값 0의 변화율은 0%가 아니라 미정이며 절대 변화량을 함께 제공합니다. 단위가 섞이거나 누락되면 단일 상위 `unit`을 만들지 않고 관측별 단위를 유지합니다.
- 페이지 응답은 전체 자료 취득 완료가 아닙니다. 반환 건수와 공급자 총건수를 구분하고, `hasMore`와 다음 페이지를 확인하세요.
- MDIS는 공식 공개 웹 페이지를 읽는 `adapter`(공개 웹 응답을 MCP 도구 형식으로 연결하는 모듈)입니다. 공개 조사·변수·코드북 탐색에는 연구자 로그인이 필요하지 않습니다. 일반 원자료 이용·인가자료 신청·분석은 본인 환경에서 공식 절차로 진행하며, 이 서버는 연구자 비밀번호·쿠키를 받거나 저장하지 않습니다.
- 코드북의 `validation.level: "header-only"`는 파일 형식과 CFB(옛 XLS를 담는 복합 파일 형식) 헤더만 검사했다는 뜻입니다. 워크시트 본문 검증·원자료 다운로드·이용 승인 완료를 뜻하지 않습니다.

---

## 🔧 개발자 가이드

### 로컬 개발

```bash
# 개발 모드 (watch)
pnpm run dev

# MCP Inspector로 테스트
pnpm run inspector

# E2E 테스트
node e2e-test.js
```

### 프로젝트 구조

```
korea-stats-mcp/
├── src/
│   ├── index.ts              # 진입점 (stdio 트랜스포트)
│   ├── server.ts             # MCP 서버 설정
│   ├── tools/                # 8개 도구 구현
│   │   ├── quickStats.ts     # 빠른 조회
│   │   ├── quickTrend.ts     # 추세 분석
│   │   └── ...
│   ├── data/
│   │   └── quickStatsParams.ts  # 통계표·항목 기본 설정
│   └── api/
│       └── client.ts         # KOSIS API 클라이언트
├── api/
│   └── mcp.ts                # Vercel 서버리스 (원격 MCP)
└── tests/                    # Playwright 테스트
```

### 새 키워드 추가하기

`src/data/quickStatsParams.ts`에 새 키워드를 추가할 수 있습니다:

```typescript
'새키워드': {
  orgId: '101',           // 기관 코드 (101 = 통계청)
  tableId: 'DT_XXXXX',    // 통계표 ID
  tableName: '통계표명',
  description: '설명',
  objL1: '00',            // 분류값 코드
  itemId: 'T10',          // 항목 코드
  unit: '단위',
}
```

---

## 📋 API 키

**원격 서버는 사용자 KOSIS 키 없이 이용할 수 있습니다.** MCP 클라이언트에 위의 원격 URL을 등록하세요. KOSIS 인증은 운영자가 서버 환경변수로 설정한 키로 처리합니다.

로컬 npm/stdio 실행도 **키 없이 시작할 수 있습니다.** 키가 없으면 공개 원격 MCP 서버로 연결되며 질문과 조회 조건이 원격 서버로 전달됩니다. 이 경우 제공되는 도구·버전은 현재 원격 배포본을 따릅니다.

공개 서버를 거치지 않고 KOSIS를 직접 조회하려면 [KOSIS OpenAPI](https://kosis.kr/openapi/)에서 발급받은 본인 키를 `KOSIS_API_KEY` 환경변수로 설정합니다. 소스 코드를 수정하거나 키를 패키지에 넣지 않습니다.

원격 서버 운영자는 Vercel의 해당 배포 환경에 `KOSIS_API_KEY`를 설정하고 새 배포에서 실제 조회를 확인해야 합니다. 키를 프런트엔드 공개 환경변수, 저장소, 로그에 넣지 마세요. 과거 공개 키는 새 키로 정상 동작을 확인한 뒤 폐기해야 하며, 소스에서 삭제한 것만으로 과거 배포본과 Git 이력에서 사라지지는 않습니다.

상권정보 제공과 위의 중첩 시군구 명칭 확인을 지원하는 운영자는 같은 배포 환경에 `DATA_GO_KR_SERVICE_KEY`도 설정해야 합니다. 이 키는 공공데이터포털의 해당 상권정보 서비스 활용 승인을 받은 운영자용 키입니다. 이용자에게 각자 발급받도록 요구하지 않습니다. MDIS 공개 메타데이터 adapter에는 이 두 API 키가 필요하지 않습니다.

Vercel Functions는 `vercel.json`의 `regions: ["icn1"]`에 따라 서울에 배치합니다. MDIS 공개 카탈로그의 본문 전송 지연을 줄이기 위한 설정이며, 요청 8초·응답 4 MiB 제한은 유지합니다. 다른 리전의 동작을 로컬 성공만으로 가정하지 말고 실제 배포에서 확인하세요. 이 설정 자체가 기존 공개 서버의 배포 완료를 뜻하지는 않습니다.

출시 전 단계별 검증, 공개 대상의 사후 확인과 안전한 롤백은 [사용자 가이드의 운영자 절차](docs/USER_GUIDE.md)를 따릅니다. 보호된 preview 검증과 실제 공개 서비스의 배포 완료를 구분합니다.

### 공개 시군구·상세 조회 벤치마크

질문·채점·합격선의 정본은 [고정 벤치마크 기준](tests/public-benchmark.json)입니다. 운영자가 독립 공식 원문과 공개 MCP 응답을 대조할 때 실행합니다.

```bash
node --env-file=/보호된경로/provider.env tests/public-benchmark.mjs --output /절대경로/새검증폴더
```

`provider.env`에는 독립 원문 대조용 운영자 `KOSIS_API_KEY`와 `DATA_GO_KR_SERVICE_KEY`를 둡니다. 공개 MCP 연결에는 이 키나 인증 우회 헤더를 보내지 않습니다. 일반 이용자가 이 벤치마크를 실행하거나 키를 발급받을 필요는 없습니다.

매 실행은 새 결과 폴더와 기준 파일 해시를 남깁니다. 미실행·외부 장애·원자료 미제공을 통과로 바꾸거나 분모에서 빼지 않습니다. 이 벤치마크는 기존 단계별 출시 검사나 전국 모든 통계의 제공 범위를 대신하지 않습니다.

---

## 🤝 기여하기

기여를 환영합니다!

1. 이 저장소를 Fork 합니다
2. 새 브랜치를 생성합니다 (`git checkout -b feature/새기능`)
3. 변경사항을 커밋합니다 (`git commit -m 'feat: 새 기능 추가'`)
4. 브랜치에 Push 합니다 (`git push origin feature/새기능`)
5. Pull Request를 생성합니다

### 기여 아이디어

- [ ] 새로운 통계 키워드 추가
- [ ] 영문 키워드 지원 (population, unemployment 등)
- [ ] 지역명 풀네임 지원 (서울특별시 → 서울)
- [ ] 더 많은 테스트 케이스

---

## 📄 라이선스

[MIT License](LICENSE) - 자유롭게 사용, 수정, 배포할 수 있습니다.

MIT 라이선스는 이 프로그램 코드에 적용됩니다. KOSIS·공공데이터포털·MDIS 자료의 저작권, 출처 표시, 이용 조건과 접근 승인은 각 공급자의 조건을 따릅니다.

---

## 🔗 관련 링크

- [KOSIS 국가통계포털](https://kosis.kr/)
- [KOSIS OpenAPI 개발 가이드](https://kosis.kr/openapi/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

---

## 💬 문의

이슈나 질문이 있으시면 [GitHub Issues](https://github.com/Dayoooun/korea-stats-mcp/issues)에 등록해 주세요.

---

<p align="center">
  <b>Made with ❤️ for Korean Statistics</b><br>
  <sub>KOSIS OpenAPI 기반 | MCP Compatible</sub>
</p>