EV Failure Safe MCP

전기차 충전 실패를 줄이기 위한 PlayMCP 서버입니다. 사용자의 차량, 남은 주행거리, 출발지/목적지, 커넥터 조건을 받아 실제 공공 충전소 데이터와 경로 정보를 기준으로 충전 후보를 정렬합니다.

운영 중인 MCP

• PlayMCP에서 EV Failure Safe MCP 사용하기

무엇을 해결하나요

• 차량 커넥터와 충전기 타입이 맞지 않는 문제
• 도착했을 때 충전기가 사용 중이거나 고장인 문제
• 목적지에서 너무 멀리 벗어나는 충전소를 추천하는 문제
• 공공 API가 느리거나 실패할 때 임의 데이터를 보여주는 문제

이 서버는 충전소를 단순 거리순으로 보여주지 않고, 실패 가능성이 낮은 후보를 먼저 보여주는 것을 목표로 합니다.

주요 기능

MCP tool	설명
ev_failure_safe_recommend	차량/커넥터/속도/잔여 주행거리 기준으로 실패 위험이 낮은 충전소를 추천합니다.
ev_charge_stop_plan	추천 충전소, 카카오맵 길찾기 링크, 예상 비용, 공유 메시지를 한 번에 만듭니다.
ev_charger_search	지역, 커넥터, 급속/완속 조건으로 충전소를 검색합니다.
place_search	Kakao Local API로 장소를 검색합니다.
meeting_place_recommend	여러 출발지를 고려해 약속 장소 후보를 추천합니다.
map_link	카카오맵 지도/길찾기 링크를 생성합니다.
share_message	카카오톡에 붙여넣기 좋은 공유 메시지를 생성합니다.
service_status	서버 상태와 필수 키 설정 여부를 확인합니다.

빠른 시작

1. 환경 변수 준비

cp .env.example .env

최소 실행에 필요한 값:

KAKAO_REST_API_KEY=your_kakao_rest_api_key
EV_API_SERVICE_KEY=your_public_data_decoding_key

KEPCO_API_KEY가 있으면 Kakao Local 기반 완속 후보를 한국전력공사 충전소 운영 정보로 추가 보강합니다. 키가 없거나 조회에 실패하면 임의 데이터를 대신 만들지 않습니다.

2. 로컬 실행

npm start

• 브라우저 데모: http://127.0.0.1:3000
• MCP endpoint: POST http://127.0.0.1:3000/mcp
• 상태 확인: GET http://127.0.0.1:3000/health

3. JSON-RPC 호출 예시

curl -s http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ev_failure_safe_recommend","arguments":{"area":"강남역","destination":"잠실","connector":"dc_combo","speed":"fast","remainingRangeKm":60,"vehicleProfileId":"kia-niro-ev-2025","size":3}}}'

데이터 원칙

• 충전소 데이터는 한국환경공단 전기자동차 충전소 공공데이터를 사용합니다.
• 장소와 경로는 Kakao Local API, Kakao Mobility 자동차 길찾기, 카카오맵 링크를 사용합니다.
• 공공 API 조회 결과, 최근 캐시, 정적 마스터 데이터를 기준으로 후보를 정렬합니다.
• API가 실패하면 확인 가능한 후보만 표시하며, 가짜 충전소나 임의 상태값을 만들지 않습니다.
• 충전 비용은 실시간 사업자 요금이 아니라 급속/완속 평균 단가 기반 참고 금액입니다.

민간 충전사업자별 요금 검토

민간 충전사업자별 요금 기능은 페이즈 2(본선) 개발 범위에서 제외합니다. 현재는 급속/완속 평균 단가로 참고 비용만 계산하며, 실제 결제 요금은 운영사 앱이나 공식 안내에서 확인하도록 안내합니다.

사업자별 요금은 회원·비회원·로밍·충전 출력·개별 충전소 정책에 따라 달라지고, 공식 데이터 이용 허가와 지속적인 수집·검수·서버 운영이 필요합니다. 따라서 공개 홈페이지의 요금을 자동 수집하거나 민간 운영사별 가격 비교·정렬에는 사용하지 않습니다.

향후 공식 API 또는 데이터 파일과 재표시 권한을 확보하고 운영 비용을 감당할 수 있을 때 별도 기능으로 재검토합니다.

차량 프로필

data/vehicle-profiles.ndjson에는 국내 판매 또는 운용 가능성이 높은 전기차 프로필이 들어 있습니다. 현대, 기아, 제네시스, KGM, 르노, 쉐보레, 테슬라 차량을 포함하며, 차량별 커넥터/배터리/효율/권장 충전 조건을 추천 로직에 사용합니다.

프로필 데이터는 추천 품질을 높이기 위한 보조 데이터입니다. 실제 충전 가능 여부는 충전소 운영 상태, 차량 트림, 연식, 어댑터 사용 여부에 따라 달라질 수 있습니다.

정적 충전소 마스터

data/static-chargers.ndjson는 공공 API가 느리거나 실패할 때 먼저 보여줄 수 있는 읽기 전용 충전소 마스터입니다. 현재 데이터는 주요 권역 중심이며, 휴게소/고속도로 충전소는 운영 전 추가 보강 대상입니다.

정적 마스터 수집 대상 확인:

npm run collect:static-ev -- --profile=major-cities --rows=5000 --dry-run

휴게소 후보만 보강:

npm run collect:static-ev -- --zscodes=47150,47850 --rows=1000 --highway-only=true

시도 단위 조회는 응답량이 커서 타임아웃될 수 있습니다. 실패하면 시군구 단위와 작은 --rows 값으로 나눠 실행하는 편이 안정적입니다.

검증

npm test
npm run perf
npm run smoke
npm run verify

npm run perf는 외부 API를 호출하지 않는 stub 기반 성능 게이트입니다. PlayMCP 응답 예산과 정적 지역 alias, 모호 입력 차단 동작을 확인합니다.

Kakao Cloud 배포

예선 단계에서는 GitHub private repository를 Kakao Cloud 소스 빌드에 연결하는 흐름을 권장합니다. 이 프로젝트는 Node 22 표준 기능 중심으로 구성되어 있으며, Dockerfile도 함께 제공합니다.

필수 환경 변수:

HOST=0.0.0.0
PORT=<Kakao Cloud assigned port>
KAKAO_REST_API_KEY=<Kakao Developers REST API key>
EV_API_SERVICE_KEY=<공공데이터포털 Decoding 인증키>
ALLOWED_ORIGINS=https://playmcp.kakao.com

운영 권장 환경 변수:

EV_CACHE_TTL_MS=600000
EV_CACHE_STALE_MS=1800000
TOOL_RESPONSE_TIMEOUT_MS=2900
EV_API_TIMEOUT_MS=2000
EV_API_DAILY_LIMIT=96000
EV_STATIC_FIRST=true
EV_STATIC_SEARCH_RADIUS_METERS=3000
EV_FAST_AVERAGE_PRICE_PER_KWH=347
EV_SLOW_AVERAGE_PRICE_PER_KWH=347

선택 연동:

• KEPCO_API_KEY: 한국전력공사 충전소 운영 정보 보강
• TMAP_ENABLED=false: TMAP 조회 비활성화 권장
• TMAP_API_KEY: TMAP을 명시적으로 사용할 때만 설정
• EV_PRICE_FILE: 운영사별 단가 JSON 파일

등록할 PlayMCP endpoint:

https://<cloud-endpoint>/mcp

자세한 배포 점검은 docs/kakao-cloud-checklist.md를 확인하세요.

운영 참고

• 로컬 알파/베타 기준: docs/local-release-plan.md
• EV API 캐시/prewarm 전략: docs/ev-api-performance-strategy.md

운영계정 승인 후 캐시 품질을 높일 때:

npm run prewarm:ev -- --profile=starter
npm run prewarm:ev -- --profile=major-cities --max-jobs=10

실제 prewarm은 호출량을 확인한 뒤 --execute를 붙여 실행합니다.

출처

• 충전소 데이터: 한국환경공단_전기자동차 충전소 정보 — 공공누리 제1유형(출처표시), 제3자 권리 포함
• 지도/장소/경로: Kakao Local API, Kakao Mobility 자동차 길찾기, 카카오맵 링크
• MCP specification: https://modelcontextprotocol.io/specification
• Kakao Local REST API: https://developers.kakao.com/docs/latest/ko/local/dev-guide
• Kakao Maps URL Scheme: https://apis.map.kakao.com/web/guide/

라이선스

별도 표시가 없는 이 프로젝트의 자체 소스 코드와 문서는 MIT License로 공개합니다.

공공데이터, 차량 제원 출처, API 제공자 권리, 시각 자산의 적용 범위는 THIRD_PARTY_NOTICES.md를 확인하세요.