Parking Recommendation

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
  }
}

추천 우선순위:

• nearest: 거리 우선
• fastest: 가능대수와 예상 대기시간 우선
• cheapest: 예상 요금 우선
• beginner_friendly: 초보 친화 점수 우선

응답에는 도보 시간, 예상 대기시간, 예상 요금, 추천 점수, 추천 이유, 카카오맵 URL이 포함됩니다.

MVP 데이터 범위

• 서울시 공영주차장 API 연동 함수 포함
• API 키 없을 때 시연 가능한 mock 목적지, 주차장, 통계 포함
• 실시간 가능대수가 없는 주차장은 available_spaces: null
• beginner_score는 사진 분석 전 단계이므로 mock 필드로 처리
• 요금 계산은 기본/추가 단위 요금 기반의 MVP 추정값

검증

npm run typecheck