# daejeon-mcp-server

대전광역시 관내 음식점 정보조회 오픈API(`http://bigdata.daejeon.go.kr/api/stores`)를 호출하는 MCP(Model Context Protocol) 서버입니다.

저장소: https://github.com/iapke486-arch/daejeon-mcp-server

대전광역시 관내에 운영중인 음식점들의 정보(매장명/주소/전화번호/영업시간/업종/대표메뉴/상세 메뉴 및 가격 등)를 조회할 수 있으며, 원본 데이터는 월 단위로 갱신됩니다.

## 사전 준비: 인증키(서비스키) 발급

이 API는 [공공데이터포털](https://www.data.go.kr/data/15098146/openapi.do)에 등록되어 있지만 **API 유형이 "LINK"**입니다. LINK 유형은 공공데이터포털이 제공기관 사이트로 연결만 해주는 방식이라, 일반 REST API처럼 마이페이지에서 인코딩/디코딩 키 쌍을 발급받는 절차가 없습니다. 실제 서비스는 대전광역시가 운영하는 [대전 빅데이터 통합플랫폼](http://bigdata.daejeon.go.kr)에서 직접 제공하므로, 인증키도 그 사이트에서 발급받아야 합니다(발급 절차 문의: 대전 빅데이터 포털 고객센터 1566-0025, 평일 09:00~18:00).

> **실제 확인된 동작**: 테스트 결과 이 API는 `serviceKey`가 없거나 임의의 값이어도 정상 응답을 반환합니다 — 문서상 필수 파라미터이지만 실제로는 검증하지 않는 것으로 보입니다. 다만 향후 검증이 추가될 수 있으므로, 이 서버는 여전히 `DAEJEON_API_KEY` 설정을 요구합니다.

## 설치 및 빌드

```bash
git clone https://github.com/iapke486-arch/daejeon-mcp-server.git
cd daejeon-mcp-server

npm install
npm run build
```

## 실행

### 직접 실행 (테스트)

```bash
DAEJEON_API_KEY=발급받은인증키 node build/index.js
```

Windows PowerShell:

```powershell
$env:DAEJEON_API_KEY = "발급받은인증키"
node build/index.js
```

> 본 API는 HTTP로만 서비스되어 TLS 인증서 문제가 없으므로 별도 플래그 없이 실행하면 됩니다. 다만 사내망/회사 프록시가 다른 HTTPS 트래픽까지 가로채는 환경이라면 `node --use-system-ca build/index.js`처럼 `--use-system-ca`(Node 22+)를 붙여 Windows 인증서 저장소를 함께 신뢰하도록 할 수 있습니다.

### Claude Desktop / Claude Code 설정

#### Claude Desktop

`claude_desktop_config.json`(보통 `%APPDATA%\Claude\claude_desktop_config.json`)에 아래와 같이 등록합니다.

```json
{
  "mcpServers": {
    "daejeon": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/daejeon-mcp-server/build/index.js"],
      "env": {
        "DAEJEON_API_KEY": "발급받은인증키"
      }
    }
  }
}
```

경로 예시:
- Windows: `C:/Users/YourName/Documents/pke/daejeon-mcp-server/build/index.js`
- macOS/Linux: `/home/username/projects/daejeon-mcp-server/build/index.js`

저장 후 Claude Desktop을 완전히 종료했다가 다시 실행해야 반영됩니다.

#### Claude Code CLI

```bash
claude mcp add daejeon --env DAEJEON_API_KEY=발급받은인증키 -- node /path/to/daejeon-mcp-server/build/index.js

# 모든 프로젝트에서 사용하려면 사용자 전역 스코프로 등록
claude mcp add daejeon --scope user --env DAEJEON_API_KEY=발급받은인증키 -- node /path/to/daejeon-mcp-server/build/index.js
```

> 서버 이름(`daejeon`)은 반드시 `--` 앞의 첫 번째 인자로 지정해야 합니다. 생략하면 명령어(`node`)가 서버 이름으로 등록되어 버립니다.

### 연결 확인

Claude Code: `/mcp` 목록에서 `daejeon` 서버가 ✓ Connected 상태인지 확인하세요.

## 제공 도구 (Tools)

| Tool | 설명 |
|---|---|
| `daejeon_search_restaurants` | 음식점 목록 조회. `category`로 서버 측 업종 필터링(한식/야식/일식/중식/분식 등), `nameKeyword`/`addressKeyword`/`menuKeyword`로 클라이언트 측 부분 일치 필터링 지원 |

### 파라미터

- `page` (선택, 기본 1): 페이지 번호
- `numOfRows` (선택): 한 페이지 결과 수를 요청하는 파라미터이지만, **실제 서버는 이 값과 무관하게 항상 50건을 반환합니다** (문서와 다른 서버 자체의 동작이며, 필요한 정확한 건수는 응답의 `results.length`를 확인하세요)
- `category` (선택): 업종 필터. 원본 API 문서 예시는 한식/야식/일식/중식/분식이며, 실제 `TOB_INFO` 값과 정확히 일치해야 필터링됩니다 (실제 호출로 정상 동작 확인됨)
- `nameKeyword` (선택): 매장명(`REST_NM`) 부분 일치. 이번에 조회된 페이지 안에서만 필터링됩니다
- `addressKeyword` (선택): 주소(`ADDR`/`DADDR`) 부분 일치, 예: `유성구`, `둔산동`. 이번에 조회된 페이지 안에서만 필터링됩니다
- `menuKeyword` (선택): 대표메뉴(`RPRS_MENU_NM`) 또는 메뉴명 목록(`MENU_KORN_NM`) 부분 일치. 이번에 조회된 페이지 안에서만 필터링됩니다

`nameKeyword`/`addressKeyword`/`menuKeyword`는 원본 API가 지원하는 검색 조건이 아니라, 조회된 결과 페이지에 대해 이 도구가 클라이언트 측에서 걸러내는 필터입니다. 전체 데이터(약 2만 건)에서 폭넓게 찾고 싶다면 `numOfRows`를 늘리거나 여러 `page`를 순회해야 합니다.

## 참고

- 원본 API는 HTTP(비암호화)로만 서비스되며, JSON으로 응답합니다.
- 인증키는 대전 빅데이터 통합플랫폼에서 발급받은 것을 그대로 설정하세요. 이 서버가 URL 인코딩을 처리합니다.
- 응답의 `count`는 필터 적용 전 서버 측 전체 건수(약 20,000건), `next`는 다음 페이지 조회 URL입니다.
- **문서와 실제 응답의 차이(실제 호출로 확인됨)**:
  - 문서에는 응답에 `resultCode`/`resultMsg` 필드가 있다고 되어 있으나, 실제 응답에는 `count`/`next`/`previous`/`results`만 존재합니다. 이 서버는 `results` 배열의 존재 여부로 성공을 판단합니다.
  - `numOfRows` 파라미터는 실제로 무시되며 페이지당 항상 50건이 반환됩니다.
  - `serviceKey`는 값이 없거나 유효하지 않아도 요청이 거부되지 않는 것으로 확인되었습니다.
- HTTP 오류나 JSON 파싱 실패 등 명백한 오류 상황에서는 원본 응답 본문을 그대로 전달합니다.