# daegu-transit-mcp

대구광역시 실시간 교통 오픈데이터를 MCP(Model Context Protocol) 도구로 감싼 서버입니다.

## 구성

| 영역 | 제공기관 | 데이터셋 |
|---|---|---|
| 버스 도착예정/위치 | 대구광역시 (data.go.kr) | [대구버스정보시스템](https://www.data.go.kr/data/15139134/openapi.do) |
| 도로 구간 소통정보 | 대구광역시 (data.go.kr) | [교통소통정보(신)](https://www.data.go.kr/data/15126266/openapi.do) |
| 주차장 실시간 여유/혼잡 | 대구광역시 통합주차정보시스템 | [pis.daegu.go.kr](https://pis.daegu.go.kr/opendata/) |

## 사전 준비

1. [data.go.kr](https://www.data.go.kr) 회원가입 → 아래 2개 데이터셋 활용신청 (개발계정 자동승인, 즉시 발급)
   - [대구버스정보시스템](https://www.data.go.kr/data/15139134/openapi.do), [교통소통정보(신)](https://www.data.go.kr/data/15126266/openapi.do)
   - 두 데이터셋이 같은 **일반 인증키(디코딩 값)** 를 공유 → `DATA_GO_KR_KEY`
2. [pis.daegu.go.kr](https://pis.daegu.go.kr/opendata/) 개발자 등록 → `실시간주차혼잡도 조회` API 키 발급 (관리자 검토 후 승인) → `DAEGU_PARKING_API_KEY`

## 설치

```bash
git clone https://github.com/wlstmd/daegu-transit-mcp && cd daegu-transit-mcp
npm install && npm run build

claude mcp add daegu-transit \
  -e DATA_GO_KR_KEY=YOUR_KEY \
  -e DAEGU_PARKING_API_KEY=YOUR_KEY \
  --scope user \
  -- node $(pwd)/dist/index.js
```

`/mcp`로 6개 도구가 로드됐는지 확인 후 "동대구역 버스 언제 와?" 같은 질문으로 테스트하세요.

로컬 개발 시 `.env.example`을 `.env`로 복사해 키를 채우면 `npm run dev`로 바로 실행됩니다.

## 도구 목록

| 도구 | 설명 |
|---|---|
| `search_bus_stop` | 정류소 이름 → bsId 검색 |
| `search_bus_route` | 버스 번호 → routeId 검색 |
| `get_bus_arrivals` | 정류소 실시간 도착예정 버스 |
| `get_bus_location` | 노선 실시간 버스 위치 |
| `get_road_traffic` | 도로 구간별 실시간 속도/소통상황 |
| `get_parking` | 주차장 실시간 여유/혼잡 + 상세정보 |

## 참고 사항

- `apis.data.go.kr` 계열 API는 `Accept-Language` 헤더가 없으면 영문으로 응답합니다. 클라이언트(`src/client/dataGoKr.ts`, `daeguParking.ts`)가 `ko-KR,ko;q=0.9`를 항상 보냅니다.
- `get_road_traffic`은 API에 위치 필터가 없어 넓은 풀(500건)을 가져와 클라이언트에서 도로명/구간명으로 걸러냅니다. 아주 드문 지명은 안 잡힐 수 있습니다.
- `get_parking`은 통합주차정보시스템에 등록된 주차장(주로 공영)만 커버합니다. 건물 부설주차장 전체 목록(data.go.kr 15108762)은 실시간 데이터가 없고 ID 체계도 달라 제외했습니다.