# korea-onegov-mcp

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/socialkim/korea-onegov-mcp)

[OneGov](https://korea-onegov.vercel.app/) — 대한민국 중앙행정기관 약 50곳의 보도자료·정책·법령·통계·정보공개·고시공고 약 9만 건을 모아 색인한 통합검색 서비스 — 의 **공개 API를 감싼 MCP 서버**입니다.

사이트에 직접 들어가지 않고 Claude(웹/데스크톱/Code), ChatGPT(개발자 모드), Cursor 등에서 대화로 정부 자료를 검색·조회할 수 있습니다.

- **원격(Streamable HTTP)** 과 **로컬(stdio)** 두 방식을 하나의 코드베이스로 지원합니다.
- 빌드 단계가 없습니다. 순수 ESM JavaScript라 `git push` 하면 Vercel이 그대로 배포합니다.
- 인증 키가 필요 없습니다. OneGov API가 무인증 공개 API이기 때문입니다.

> ⚠️ OneGov는 정부 공식 사이트가 아니라 공개자료를 모아 색인한 비공식 검색 서비스입니다. 자료 대부분에 공공누리(KOGL) 조건이 적용되므로, 인용·재사용할 때는 **기관명과 원문 링크(source_url)** 를 반드시 함께 표기하세요. 이 서버는 모든 응답 하단에 해당 안내를 자동으로 붙입니다.

---

## 제공 도구 (11개)

| 도구 | 하는 일 |
| --- | --- |
| `onegov_search` | 통합검색. 문서유형·기관·지역·법령·발행일 범위·정렬·검색모드 전체 필터 지원 |
| `onegov_get_document` | 문서 id로 전문 + 첨부 + 관련법령 + 연관문서 조회 |
| `onegov_suggest_keywords` | 실제 색인된 검색어 자동완성 (0건 나올 때 먼저 쓰기) |
| `onegov_list_ministries` | 기관코드 목록과 보유 문서 수 (`ministry` 필터용 코드 확인) |
| `onegov_trending_keywords` | 공개자료 제목에 자주 등장하는 상위 주제어 |
| `onegov_deadline_grants` | 마감임박 지원사업 공고 (D-day·기관 필터) |
| `onegov_find_support_programs` | 지원사업·공고 주제 검색 (범위를 미리 좁힌 편의 도구) |
| `onegov_ministry_latest` | 특정 부처의 최근 N일 자료를 최신순으로 |
| `onegov_research_topic` | 검색 → 상위 문서 본문 자동 수집까지 한 번에 (주제 브리핑) |
| `search` / `fetch` | ChatGPT 커넥터·딥리서치 규격 호환용 (`ONEGOV_CHATGPT_COMPAT=off` 로 끌 수 있음) |

모든 도구는 읽기 전용이며, `response_format` 으로 `markdown`(기본) / `json` 을 고를 수 있습니다.

---

## A. 원격 MCP 서버로 배포하기 (Claude 웹 / ChatGPT 웹에서 쓰려면 이 방법)

### A-1. Vercel에 올리기

**방법 1 — GitHub 경유 (권장)**

이 폴더에는 이미 git 저장소가 초기화되어 있고 커밋도 들어 있습니다. 원격만 연결해서 밀어 올리면 됩니다.

**윈도우** — 탐색기에서 `push-to-github.cmd` 를 더블클릭하거나, 명령 프롬프트에서:

```
push-to-github.cmd
```

git·GitHub CLI가 없으면 스크립트가 winget으로 설치할지 물어보고, GitHub 로그인까지 안내한 뒤 저장소 생성과 푸시를 진행합니다.
(윈도우 CMD에는 `bash` 가 없으므로 `bash push-to-github.sh` 는 동작하지 않습니다.)

**macOS / Linux**

```bash
cd korea-onegov-mcp
bash push-to-github.sh
```

**수동으로 하려면** — [github.com/new](https://github.com/new) 에서 빈 저장소(README·라이선스 체크 해제)를 만든 뒤:

```bash
git remote add origin https://github.com/<사용자명>/korea-onegov-mcp.git
git push -u origin main
```

그다음 [vercel.com/new](https://vercel.com/new) 에서 해당 저장소를 Import 합니다.
3. Framework Preset은 **Other**, 나머지 설정은 손대지 않고 **Deploy**.
4. 배포가 끝나면 `https://<프로젝트명>.vercel.app` 주소가 나옵니다.

**방법 2 — CLI**

```bash
npm i -g vercel
cd korea-onegov-mcp
vercel --prod
```

### A-2. 배포 확인

```bash
curl https://<프로젝트명>.vercel.app/mcp
# {"server":"korea-onegov-mcp-server","version":"1.0.0", ...} 가 나오면 정상

# 도구 목록까지 확인
curl -X POST https://<프로젝트명>.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

**MCP 접속 주소는 `https://<프로젝트명>.vercel.app/mcp` 입니다.** (`/api/mcp` 도 동일하게 동작합니다.)

### A-3. Claude 웹/데스크톱에 등록

1. Claude 설정 → **Connectors**
2. **+ Add custom connector**
3. 이름: `OneGov 정부자료`, URL: `https://<프로젝트명>.vercel.app/mcp`
4. **Add** → 대화창의 도구 아이콘에서 켜고 사용

인증 설정은 비워 두면 됩니다(무인증 서버).

### A-4. ChatGPT에 등록

ChatGPT의 커스텀 MCP 커넥터는 **개발자 모드**가 필요하며 Pro/Team/Enterprise/Edu 플랜에서 제공됩니다.

1. 설정 → **Connectors** → **Advanced** → **Developer mode** 켜기
2. **Connectors** → **Create**
3. 이름과 서버 URL(`https://<프로젝트명>.vercel.app/mcp`) 입력, 인증은 **No authentication**
4. 신뢰 확인에 체크하고 생성

이 서버는 딥리서치 규격에 맞춘 `search` / `fetch` 도구를 함께 제공하므로 딥리서치 커넥터로도 붙습니다.

---

## B. 로컬(stdio)로 쓰기 — Claude 데스크톱앱 / Claude Code / Cursor

```bash
cd korea-onegov-mcp
npm install
node src/index.js --help
```

### Claude 데스크톱앱

`claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) 에 추가:

```json
{
  "mcpServers": {
    "korea-onegov": {
      "command": "node",
      "args": ["/절대/경로/korea-onegov-mcp/src/index.js"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add korea-onegov -- node /절대/경로/korea-onegov-mcp/src/index.js
```

### 로컬 HTTP로 띄우기 (원격 배포 전 테스트용)

```bash
npm run http          # http://127.0.0.1:3000/mcp
npm run inspect       # MCP Inspector로 도구 직접 호출해 보기
```

---

## 환경변수

| 이름 | 기본값 | 설명 |
| --- | --- | --- |
| `PORT` | `3000` | 로컬 HTTP 모드 포트 |
| `HOST` | `127.0.0.1` | 로컬 HTTP 모드 바인딩 주소 |
| `ONEGOV_API_BASE` | `https://korea-onegov.vercel.app` | OneGov API 베이스 URL |
| `ONEGOV_TIMEOUT_MS` | `25000` | 외부 API 타임아웃 |
| `ONEGOV_CHATGPT_COMPAT` | (켜짐) | `off` 로 두면 `search`/`fetch` 도구를 등록하지 않음 |

---

## 테스트

```bash
npm run smoke              # HTTP 모드로 띄우고 실제 API까지 20개 항목 검증
node scripts/stdio-test.js # stdio 모드 연결 + 주제 브리핑 도구 확인
```

---

## 구조

```
korea-onegov-mcp/
├── api/mcp.js          Vercel 서버리스 함수(원격 MCP 엔드포인트)
├── src/
│   ├── index.js        실행 진입점 (stdio / 로컬 HTTP)
│   ├── server.js       McpServer 생성 + 사용 지침
│   ├── tools.js        도구 11개 정의
│   ├── client.js       OneGov API 클라이언트 + 에러 매핑
│   ├── format.js       마크다운/JSON 포매팅, 길이 제한
│   └── constants.js    상수
├── scripts/            스모크 테스트
├── public/index.html   배포 확인용 안내 페이지
└── vercel.json         함수 설정 + /mcp 리라이트
```

---

## 알아 둘 점

- **레이트리밋**: OneGov API는 IP 단위 제한이 있어 429가 날 수 있습니다. 서버는 429를 만나면 재시도 안내가 담긴 에러 메시지를 돌려줍니다.
- **응답 길이**: 한 응답이 25,000자를 넘으면 잘라내고 "필터를 좁히라"는 안내를 붙입니다.
- **stateless**: Vercel 함수는 요청마다 새 서버 인스턴스를 만드는 stateless Streamable HTTP 모드로 동작합니다. SSE(GET 스트리밍)는 지원하지 않습니다.
- **원본 서비스 존중**: 이 래퍼는 OneGov가 공개한 API를 그대로 호출합니다. 대량 크롤링 용도로 쓰지 마세요.

## 라이선스

MIT (이 래퍼 코드에 한함). 검색되는 자료의 저작권·이용조건은 각 소관 기관 및 공공누리 조건을 따릅니다.