EV Failure Safe MCP

AI가 차량 정보, 충전기 상태, 주행 가능 거리, 경로를 종합하여 충전 실패 가능성이 낮은 충전소를 추천하는 PlayMCP 서버

사용자의 차량, 남은 주행거리, 출발지·목적지, 커넥터 조건을 받아 실제 공공 충전소 데이터와 경로 정보를 기준으로 후보를 정렬합니다. 단순한 거리순 검색보다 충전 실패 위험을 낮추는 의사결정에 초점을 둡니다.

Demo

PlayMCP 서비스 화면

충전소 추천 결과

Related MCP server: mcp-openchargemap

Table of Contents

• Demo

• Problem & Solution

• Architecture

• Core MCP Tools

• Quality Engineering

• Test Strategy

• Performance & Reliability

• Quick Start

• Data Policy

• Vehicle Profiles

• Static Charger Master

• Kakao Cloud Deployment

• Roadmap

• Operations

• Sources & License

Problem & Solution

Problem

• 차량 커넥터와 충전기 타입이 맞지 않을 수 있습니다.

• 충전기가 고장 상태일 수 있습니다.

• 도착 시 사용 가능한 충전 포트가 없을 수 있습니다.

• 목적지나 실제 이동 경로에서 지나치게 벗어난 충전소가 추천될 수 있습니다.

• 공공 API가 느리거나 실패하면 추천에 필요한 실데이터를 확보하기 어렵습니다.

Solution

• 차량 프로필과 명시된 커넥터 조건을 추천에 반영합니다.

• 커넥터 호환성, 운영 상태, 상태 최신성, 사용 가능 포트를 함께 평가합니다.

• 남은 주행거리와 경로 정보를 이용해 도달 가능성과 우회 위험을 고려합니다.

• 공공 API 응답, 최근 캐시, 정적 충전소 마스터 등 확인 가능한 데이터만 사용합니다.

• 데이터가 부족하면 제한 사항을 알리고, 가짜 충전소나 임의 상태값을 생성하지 않습니다.

Architecture

Vehicle / Request
        ↓
Recommendation Engine
        ↓
┌─────────────────────────────────────────────────┐
│ Public EV API │ Kakao Local │ Kakao Mobility    │
│ KEPCO (optional)                                │
└─────────────────────────────────────────────────┘
        ↓
Failure-risk Ranking
        ↓
MCP Response

추천 엔진은 커넥터 호환성, 도달 가능성, 상태 최신성, 사용 가능 포트, 경로 위험, 참고 비용을 기준으로 후보를 정렬합니다. 외부 API 지연이나 실패 시에는 캐시와 정적 마스터를 활용하고, 확인된 후보가 없으면 빈 결과와 제한 사항을 반환합니다.

Core MCP Tools

Quality Engineering

테스트는 정상 흐름뿐 아니라 잘못된 입력, 커넥터 범위, 상태 최신성, 타임아웃, stale cache, 정적 마스터 fallback, 경로, 요금 안내 등 실패 가능성이 높은 경계를 다룹니다.

Test Strategy

npm test
npm run perf
npm run smoke
npm run verify

npm run verify에는 npm run perf가 포함되지 않습니다. 성능 게이트는 별도로 실행합니다.

Performance & Reliability

아래 값은 측정 결과를 임의로 작성한 것이 아니라 현재 설정과 성능 스크립트에 정의된 기본값·상한·테스트 게이트입니다.

Runtime Budget

Cache & Recovery

EV·KEPCO·TMAP 캐시 관련 TTL은 코드에서 최대 30분으로 제한됩니다. 공공 EV API의 온라인 재시도 기본값은 0이며, 넓은 범위의 갱신은 사용자 응답을 오래 막지 않도록 캐시·백그라운드 경로로 분리합니다.

Performance Gates

이 값들은 scripts/perf-test.js의 stub 기반 회귀 기준입니다. 실제 외부 API 응답 속도를 보장하는 수치가 아닙니다.

Quick Start

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

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

Data Policy

No Fake Data Policy

• API가 실패하면 확인 가능한 후보만 표시합니다.

• 가짜 충전소나 임의 상태값을 생성하지 않습니다.

• 실시간 사업자 요금을 확보하지 못한 경우 평균 단가 기반 참고 금액임을 알립니다.

민간 충전사업자별 요금

민간 충전사업자별 실시간 요금 기능은 현재 범위에 포함하지 않습니다. 회원·비회원·로밍·충전 출력·개별 충전소 정책에 따라 요금이 달라지고, 공식 데이터 이용 허가와 지속적인 수집·검수·서버 운영이 필요하기 때문입니다.

현재는 급속·완속 평균 단가로 참고 비용만 계산하며, 실제 결제 요금은 운영사 앱이나 공식 안내에서 확인하도록 안내합니다. 공식 API 또는 데이터 파일과 재표시 권한을 확보하고 운영 비용을 감당할 수 있을 때 별도 기능으로 재검토합니다.

Vehicle Profiles

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

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

저장소에서 확인되는 범위에는 제조사 사이트를 반복 호출하는 차량 제원 크롤러가 없고, 서비스 실행 중에도 제조사 사이트를 조회하지 않습니다. 현재 101개 프로필은 공개된 제조사 페이지에서 확인한 일부 제원 사실을 정적 파일로 선별·정규화한 것이며, 페이지 원문·이미지·개인정보를 저장하지 않습니다.

단, 각 레코드의 sourceUrl과 sourceCheckedAt은 출처 이력이지 제조사의 재이용 허가 증명이 아닙니다. 현재 저장소에는 제조사별 서면 허가 또는 데이터 재이용 라이선스 증빙이 없으므로 차량 프로필을 이용허락이 확인된 데이터라고 표시하지 않습니다. 상업 운영이나 제3자 재배포 전에는 제조사별 최신 약관과 필요한 허가를 별도로 확인해야 합니다.

자세한 내용은 차량 프로필 문서를 확인하세요.

Static Charger Master

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 값으로 나눠 실행하는 편이 안정적입니다.

Kakao Cloud Deployment

예선 단계에서는 GitHub private repository를 Kakao Cloud 소스 빌드에 연결하는 흐름을 권장합니다. 이 프로젝트는 Node.js 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

선택 연동

등록할 PlayMCP endpoint:

https://<cloud-endpoint>/mcp

자세한 배포 점검은 Kakao Cloud 체크리스트를 확인하세요.

Roadmap

• MCP Tool 구현

• 한국환경공단 공공 EV API 연동

• Kakao Local 장소 검색

• Kakao Mobility 자동차 길찾기

• Failure-safe Recommendation

• 영속 캐시와 Static Charger Master

• 휴게소·고속도로 충전소 정적 마스터 추가 보강

• 공식 데이터와 재표시 권한 확보 후 사업자별 실시간 요금 재검토

Operations

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

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

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

Sources & License

Sources

• 충전소 데이터: 한국환경공단_전기자동차 충전소 정보 — 공공누리 제1유형(출처표시), 제3자 권리 포함

• 차량 프로필: 제조사 공개 제원 페이지의 일부 사실을 선별·정규화한 정적 데이터 — 개별 sourceUrl 기록, 별도 재이용 허가 미확인

• 지도·장소·경로: Kakao Local API, Kakao Mobility 자동차 길찾기, 카카오맵 링크

• 프로토콜: Model Context Protocol Specification

• API 문서: Kakao Local REST API

• 지도 링크: Kakao Maps URL Scheme

License

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

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