Skip to main content
Glama
soyunRyu

CommuteHell

by soyunRyu
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

CommuteHell

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

주요 기능

  • 항목별 점수를 합산한 퇴근 난이도 제공

  • TMAP 대중교통 경로 조회

  • 총 이동시간 및 환승 횟수 조회

  • 도보시간 및 도보거리 조회

  • 기상청 초단기예보 조회

  • 기온·습도·강수 기반 불쾌지수 계산

  • 주말 및 법정공휴일 확인

Related MCP server: Metro MCP

퇴근 난이도 산정 기준

퇴근 난이도는 총 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을 호출합니다.

참고 자료

Available Tools

1 tool
get_commute_difficultyB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
end_latYes
end_lonYes
start_latYes
start_lonYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the full burden. It states '계산합니다' (calculates), implying a read-only computation, but does not disclose any side effects, error behavior, data source, or performance characteristics. The description adds minimal behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the context (coordinates) and action (calculate difficulty), with no redundant or filler content. It is appropriately concise and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 required parameters, no output schema, and no annotations, the description should explain what the result looks like, any constraints, or potential errors. It only states the calculation without clarifying the output format (e.g., a score, label, or range), leaving significant gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only vaguely refers to '출발지와 도착지 좌표' (departure and arrival coordinates). It does not explicitly map to start_lat/start_lon and end_lat/end_lon, nor explain units, ranges, or formats. This provides a high-level semantic but fails to compensate for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it calculates commute difficulty based on departure and arrival coordinates. The verb '계산합니다' (calculates) and resource '퇴근 난이도' (commute difficulty) are specific, and since there are no sibling tools, differentiation is not required.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when one needs commute difficulty from coordinates, but it provides no explicit context on when to use it, exclusions, or alternatives. It merely states the action without guidance on scenarios or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion or misselection. The purpose of get_commute_difficulty is clear and distinct.

Naming Consistency5/5

The single name follows the snake_case verb_noun pattern (get_commute_difficulty), which is conventional and consistent by default.

Tool Count2/5

The server has only one tool, which is too few for the apparent domain of 'CommuteHell'. A single calculation function feels more like a standalone service than a coherent MCP tool set.

Completeness3/5

The tool covers the core operation of calculating difficulty but misses auxiliary capabilities such as retrieving traffic details, comparing route options, or explaining contributing factors. This creates notable gaps for a comprehensive commute analysis.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/soyunRyu/commuteHell'

If you have feedback or need assistance with the MCP directory API, please join our Discord server