MCP 服务器

parking-recommendation

Provides destination-based public parking lot recommendations in Seoul. It converts destinations to coordinates, finds nearby public parking lots, and estimates wait times using real-time availability and historical statistics.

README

목적지 기반 공영주차장 추천 MCP 서버

Node.js + TypeScript로 만든 서울시 공영주차장 추천 MCP 서버 MVP입니다. 목적지명을 좌표로 바꾸고, 주변 공영주차장을 찾은 뒤, 실시간 가능대수와 과거 출차 통계 기반 예상 대기시간을 계산해 추천합니다.

API 키가 없으면 mock 데이터로 바로 실행됩니다.

설치

npm install

환경 설정

.env.example을 참고해 .env를 만듭니다.

KAKAO_REST_API_KEY=
SEOUL_API_KEY=
SEOUL_PARKING_ENDPOINT=http://openapi.seoul.go.kr:8088

KAKAO_REST_API_KEY가 없으면 src/data/mockDestinations.ts를 사용합니다.
SEOUL_API_KEY가 없으면 src/data/mockParkingLots.ts를 사용합니다.
과거 입출차 통계는 MVP 단계에서 src/data/mockParkingStats.ts를 사용합니다.

실행

개발 실행:

npm run dev

빌드 후 실행:

npm run build
npm start

MCP 클라이언트 연결 예시

Claude Desktop 또는 MCP 호환 클라이언트 설정에 아래 서버를 추가합니다.

{
  "mcpServers": {
    "parking-recommendation": {
      "command": "node",
      "args": ["C:/Users/ksj47/OneDrive/문서/dev/test-mcp/dist/index.js"],
      "env": {
        "KAKAO_REST_API_KEY": "",
        "SEOUL_API_KEY": ""
      }
    }
  }
}

개발 중에는 tsx로도 연결할 수 있습니다.

{
  "mcpServers": {
    "parking-recommendation-dev": {
      "command": "npx",
      "args": ["tsx", "C:/Users/ksj47/OneDrive/문서/dev/test-mcp/src/index.ts"]
    }
  }
}

제공 MCP tools

search_destination

{ "query": "코엑스" }

목적지명을 좌표로 변환합니다. 카카오 API 키가 있으면 카카오 로컬 검색 API를, 없으면 mock 데이터를 사용합니다.

find_parking_lots

{ "destination": "코엑스", "radius_m": 700 }

또는:

{ "latitude": 37.511823, "longitude": 127.059159, "radius_m": 700 }

목적지명이나 좌표 기준 주변 공영주차장을 찾습니다. 거리는 Haversine 공식으로 계산합니다.

get_parking_detail

{ "parking_lot_id": "seoul-gangnam-tancheon" }

주차장 상세 정보, 실시간 가능대수, 운영시간, 요금, 초보 친화 점수를 반환합니다.

estimate_wait_time

{
  "parking_lot_id": "seoul-gangnam-coex-north",
  "current_queue_count": 3
}

가능대수가 있으면 대기시간 0분, 만차면 현재 대기열과 과거 시간대별 출차 통계를 바탕으로 예상 대기시간을 계산합니다. 통계가 부족하면 기본값 5분/대를 사용합니다.

recommend_parking

{
  "destination": "코엑스",
  "radius_m": 900,
  "expected_parking_hours": 2,
  "priority": "fastest",
  "current_queue_count_by_lot": {
    "seoul-gangnam-coex-north": 4
  }
}