Transit

A real-time mobility assistant MCP for Korean public transit. It helps AI assistants compare what users can take now, what comes next, and what fallback remains. Instead of only listing routes, it combines route planning, live arrivals, vehicle position, seat availability, congestion, and boarding feasibility. Built for decision support: "What should I choose right now?"

실시간 대중교통 정보를 기반으로 사용자의 이동 의사결정을 지원하는 AI 이동비서 MCP입니다.

단순한 길찾기를 넘어 "지금 무엇을 타야 하는가?", **"놓치면 어떻게 달라지는가?"**를 AI가 판단할 수 있도록 설계했습니다.

---

왜 만들었나요?

기존 길찾기 서비스는 목적지까지 가는 방법을 알려주는 데 집중합니다.

하지만 실제 이동 중에는 다음과 같은 상황이 자주 발생합니다.

• 지금 오는 버스를 탈 수 있을까?
• 지하철은 지금 어디쯤 왔을까?
• 조금 뛰면 탈 수 있을까?
• 이번 차를 놓치면 얼마나 늦어질까?
• 다음 차를 기다리는 게 더 나을까?

이동비서 MCP는 이러한 질문에 답하기 위해 만들어졌습니다.

실시간 버스와 지하철 정보를 기반으로 현재 차량 위치, 도착 예정 시간, 탑승 가능 여부, 다음 선택지를 함께 제공하여 AI 비서가 사용자의 현재 이동 상황에 맞는 판단을 할 수 있도록 돕습니다.

---

이동비서 MCP가 다른 점

기존 길찾기 서비스는 **"어떻게 가는가"**를 알려줍니다.

이동비서 MCP는 **"지금 무엇을 선택해야 하는가"**를 판단할 수 있도록 실시간 이동 정보를 구조화합니다.

핵심 기능은 다음과 같습니다.

• 실시간 버스와 지하철 위치 반영
• 현재 차량 탑승 가능 여부 제공
• 첫 차량을 놓쳤을 때의 다음 선택 제공
• 조건별 추천 경로 제공
• AI 비서가 자연스럽게 설명할 수 있는 구조화된 결과 제공

---

F / N / L 구조

이동비서는 하나의 경로만 보여주지 않습니다.

실시간 상황을 기준으로 세 가지 이동 시나리오를 제공합니다.

구분	설명	의미
F, 현재	지금 바로 출발하는 경우	현재 잡을 수 있는 첫 번째 선택지
N, 다음	첫 차량을 놓친 경우	현재 선택을 놓쳤을 때의 다음 선택지
L, 차차선	조금 더 여유 있게 이동하는 경우	그다음 선택지 또는 대체 경로

각 선택지는 단순한 도착 예정 시간이 아니라, 다음 정보를 함께 제공합니다.

• 출발지부터 목적지까지의 door-to-door 도착 시각
• 첫 탑승 수단의 실시간 위치 또는 도착 예정 시간
• 탑승 가능 여부
• 놓쳤을 때 도착 시간에 생기는 영향
• 조건별 대체 경로

이를 통해 AI는 가능한 모든 경로를 나열하는 대신, 현재 상황에 맞는 이동 판단을 도와줄 수 있습니다.

---

예시 질문

지금 고속터미널역에서 광명역 가려면 어떻게 가는 게 좋아?

AI는 여러 도구를 조합하여 다음과 같이 답할 수 있습니다.

현재 선택, F

출발: 14:13
7호선 열차가 현재 1정거장 전에 있습니다.
14:19 탑승, 15:35 도착 예정입니다.
현재 위치에서 이동하면 탑승 가능성이 높습니다.

다음 선택, N

첫 열차를 놓치면 다음 열차는 약 4정거장 전에 있습니다.
14:22 탑승, 15:38 도착 예정입니다.
현재 선택보다 약 3분 늦어집니다.

차차선, L

그다음 열차는 약 8정거장 전에 있습니다.
14:25 탑승, 15:41 도착 예정입니다.

조건별 대안

최단시간 경로
최소환승 경로
최저요금 경로
도보최소 경로

핵심은 가능한 모든 경로를 나열하는 것이 아니라, 실시간 상황을 기반으로 지금 선택해야 하는 후보를 보여주는 것입니다.

---

제공 도구

도구	설명	주요 데이터
plan_journey	F / N / L 기반 실시간 이동 의사결정	경로, 실시간 도착, 차량 위치, 탑승 가능 여부, 대안
search_route	출발지와 목적지 사이의 대중교통 경로 탐색	경로, 환승, 요금, 도보, 정류장 ID
get_bus_arrival	경기버스 실시간 도착 조회	도착 예정, 남은 정거장, 좌석, 혼잡도, 배차
get_subway_arrival	수도권 지하철 실시간 도착 조회	현재 열차 위치, 행선지, 방향, 도착 예정

---

현재 지원 범위

• 수도권 대중교통 경로 탐색
• 경기버스 실시간 도착
• 수도권 지하철 실시간 도착
• 카카오 로컬 API 기반 장소 검색

향후 확장 예정입니다.

• 서울 시내버스 실시간
• 전국 버스 TAGO 연동
• KTX / SRT 탑승 가능 여부 시나리오
• 공항 이동 시나리오
• 사용자 현재 위치 기반 이동 판단
• 정기 이동 알림

택시 비교와 여행, 출장 이동 보조는 장기 확장 방향으로 검토합니다.

---

시스템 구조

사용자 자연어 질문
        |
        v
AI Assistant / LLM
        |
        v
Mobility Assistant MCP
        |
        +-- Kakao Local API
        +-- ODsay API
        +-- Gyeonggi Bus API
        +-- Seoul Subway API

Streamable HTTP 기반 stateless MCP 서버로 동작합니다.

---

실행 방법

npm install
cp .env.example .env
npm run build
npm start

기본 주소는 다음과 같습니다.

POST http://localhost:8080/mcp
GET  http://localhost:8080/health

개발 모드에서는 다음 명령을 사용할 수 있습니다.

npm run dev

---

Docker

docker build --platform linux/amd64 -t mobility-assistant-mcp .
docker run --env-file .env -p 8080:8080 mobility-assistant-mcp

---

환경 변수

변수	설명
KAKAO_REST_KEY	카카오 장소 검색
ODSAY_API_KEY	ODsay 대중교통 경로 탐색
ODSAY_REFERER	ODsay Referer 헤더
GYEONGGI_BUS_SERVICE_KEY	경기버스 실시간 도착
SEOUL_SUBWAY_ARRIVAL_KEY	지하철 실시간 도착
SEOUL_SUBWAY_POSITION_KEY	지하철 실시간 위치
PORT	기본 포트, 기본값 8080

---

이동비서 MCP의 차별점

이 프로젝트는 여러 교통 API를 단순히 MCP로 연결하는 데 목적이 있지 않습니다.

실시간 교통 데이터를 AI가 바로 이해하고 설명할 수 있는 형태로 구조화하여, 사용자의 이동 판단을 지원하는 것이 핵심입니다.

차별점은 다음과 같습니다.

• 실시간 이동 의사결정 지원
• F / N / L 기반 이동 시나리오
• 현재 차량 위치와 탑승 가능 여부 제공
• 첫 선택을 놓쳤을 때의 영향 제공
• 조건별 추천 경로 제공
• 경로 탐색과 실시간 정보를 하나의 흐름으로 연결
• AI 비서를 위한 구조화된 출력

---

로드맵

• 서울 시내버스 실시간 지원
• 전국 버스 TAGO 연동
• KTX / SRT 탑승 가능 여부 시나리오
• 공항 이동 시나리오
• 사용자 위치 기반 판단
• 정기 이동 알림

---

라이선스

MIT