CommuteHell

출발지와 도착지의 대중교통 경로, 날씨, 환승 횟수, 도보 부담 등을 종합하여 퇴근 난이도를 계산하는 Python MCP 서버입니다.

주요 기능

항목별 점수를 합산한 퇴근 난이도 제공
TMAP 대중교통 경로 조회
총 이동시간 및 환승 횟수 조회
도보시간 및 도보거리 조회
기상청 초단기예보 조회
기온·습도·강수 기반 불쾌지수 계산
주말 및 법정공휴일 확인

퇴근 난이도 산정 기준

퇴근 난이도는 총 100점으로 계산합니다.

항목	최대 점수	산정 기준
이동시간 부담	30점	70분을 부담도 100%로 계산
환승 피로도	25점	환승 4회를 부담도 100%로 계산
도보 부담	20점	도보시간 70%, 도보거리 30% 반영
날씨 불쾌도	20점	불쾌지수 100을 부담도 100%로 계산
금요일·공휴일 보정	5점	평일 5점, 금요일·공휴일 0점

퇴근 난이도
= 이동시간 부담 30점
+ 환승 피로도 25점
+ 도보 부담 20점
+ 날씨 불쾌도 20점
+ 금요일·공휴일 보정 5점

사용 API

TMAP 대중교통 API

출발지와 도착지 사이의 대중교통 경로를 조회합니다.

항목	내용
제공 기관	SK Open API
API	TMAP 대중교통 경로 요약정보
요청 방식	`POST`
인증 방식	`appKey` 요청 헤더
사용 파일	`transit.py`

https://apis.openapi.sk.com/transit/routes/sub/

주요 사용 데이터:

총 이동시간
환승 횟수
도보시간
도보거리
대중교통 요금

기상청 초단기예보 API

도착지 좌표를 기준으로 현재와 가까운 시간의 날씨를 조회합니다.

항목	내용
제공 기관	기상청·공공데이터포털
API	초단기예보조회
요청 방식	`GET`
응답 형식	XML
사용 파일	`weather.py`

https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/getUltraSrtFcst

주요 사용 데이터:

기온
습도
하늘 상태
강수 형태 및 강수량
풍속
낙뢰 정보

위도·경도는 기상청 API에서 사용하는 격자 좌표로 변환하여 요청합니다.

한국천문연구원 특일정보 API

오늘이 법정공휴일인지 확인합니다.

항목	내용
제공 기관	한국천문연구원·공공데이터포털
API	국경일·공휴일 정보
요청 방식	`GET`
사용 파일	`holiday.py`

https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService/getRestDeInfo

토요일과 일요일은 API를 호출하지 않고 Python 날짜 정보로 판단합니다.

기술 스택

구분	기술
언어	Python
패키지 관리	uv
MCP SDK	`mcp`
MCP 전송 방식	로컬 stdio, 배포 Streamable HTTP
HTTP 통신	requests
XML 변환	xmltodict
환경변수 관리	python-dotenv
버전 관리	Git, GitHub

주요 Python 패키지

패키지	용도
`mcp[cli]`	MCP 서버와 Tool 구현
`requests`	TMAP·기상청·공휴일 API 호출
`xmltodict`	기상청 XML 응답을 Python 딕셔너리로 변환
`python-dotenv`	`.env` 파일에서 API 키 로딩
`uv`	가상환경과 의존성 관리

시스템 구성

로컬 MCP 클라이언트 ── stdio ───────────────┐
                                             ▼
원격 MCP 클라이언트 ── Streamable HTTP ── Railway
                                             │
                                             ▼
                                  CommuteHell MCP Server
                                      ├─ TMAP 대중교통 API
                                      ├─ 기상청 초단기예보 API
                                      ├─ 한국천문연구원 공휴일 API
                                      └─ 퇴근 난이도 점수 계산

실행 환경

Python 3.14
MCP Python SDK 2.x
로컬 실행: stdio
Docker/Railway 배포: Streamable HTTP
원격 MCP 엔드포인트: /mcp
기본 포트: 8000
Railway 배포 시: Railway가 제공하는 PORT 환경변수 사용
Railway 배포 URL: https://commutehell-production.up.railway.app/mcp

환경변수

변수	용도
`TMAP_API_KEY`	TMAP 대중교통 API 인증
`OPENDATA_API_KEY`	기상청 및 공휴일 API 인증

TMAP_API_KEY=발급받은_TMAP_키
OPENDATA_API_KEY=발급받은_공공데이터포털_키

API 키가 들어 있는 .env 파일은 Git에 포함하지 않습니다.

프로젝트 구조

commuteHell/
├─ src/
│  └─ commutehell/
│     ├─ __init__.py
│     ├─ commute.py
│     ├─ config.py
│     ├─ transit.py
│     ├─ weather.py
│     ├─ holiday.py
│     └─ scoring.py
├─ .env
├─ .gitignore
├─ .python-version
├─ pyproject.toml
├─ uv.lock
└─ README.md

함수 호출 구조

Claude CLI
└─ MCP tools/call 요청
   └─ commute.py
      └─ get_commute_difficulty() [MCP Tool]
         ├─ transit.py
         │  └─ get_transit_route()
         │     └─ TMAP API
         │
         ├─ weather.py
         │  └─ fetch_weather()
         │     ├─ st_forecast()
         │     │  ├─ get_wheather_time()
         │     │  ├─ convert_to_grid()
         │     │  └─ 기상청 API
         │     └─ summarize_weather()
         │        ├─ calculate_discomfort_index()
         │        ├─ get_discomfort_level()
         │        ├─ format_precipitation()
         │        ├─ add_unit()
         │        └─ make_weather_summary()
         │
         ├─ holiday.py
         │  └─ get_day_off_info()
         │     └─ 공휴일 API
         │
         └─ scoring.py
            ├─ calculate_travel_time_score()
            │  └─ clamp()
            ├─ calculate_transfer_fatigue()
            │  └─ clamp()
            ├─ calculate_walking_burden()
            │  └─ clamp()
            ├─ calculate_weather_discomfort()
            │  └─ clamp()
            └─ calculate_commute_difficulty()
               └─ calculate_day_score()

파일별 역할

파일	역할
`commute.py`	MCP 서버 실행 및 공개 Tool 관리
`config.py`	환경변수, API 키, API URL 관리
`transit.py`	TMAP 대중교통 경로 조회
`weather.py`	기상청 예보 조회 및 불쾌지수 계산
`holiday.py`	주말 및 법정공휴일 확인
`scoring.py`	항목별 점수 및 최종 퇴근 난이도 계산

Remote MCP Server

배포된 Streamable HTTP MCP 서버를 사용할 수 있습니다.

https://commutehell-production.up.railway.app/mcp

예를 들어 Gemini CLI에 다음과 같이 등록합니다.

gemini mcp add --transport http commuteHell https://commutehell-production.up.railway.app/mcp

MCP Tool

`get_commute_difficulty`

출발지와 도착지 좌표를 받아 퇴근 난이도를 계산합니다.

입력값

이름	형식	설명
`start_lat`	`float`	출발지 위도
`start_lon`	`float`	출발지 경도
`end_lat`	`float`	도착지 위도
`end_lon`	`float`	도착지 경도

호출 예시

{
  "start_lat": 37.5569,
  "start_lon": 126.8643,
  "end_lat": 37.5503,
  "end_lon": 126.9158
}

사용자가 지역명이나 주소를 입력하면 MCP 클라이언트가 먼저 좌표를 찾은 뒤 이 Tool을 호출합니다.