Skip to main content
Glama
deenesjakoruzh
C0deRatoR

cityflo-otp

by C0deRatoR
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

Cityflo 정시 운행 성과 MCP

data/trips.csv의 뭄바이 노선 지연 관련 질문에 답하기 위한 소형 읽기 전용 stdio MCP 서버입니다. 도구는 결정적 계산을 수행하며, 클라이언트 에이전트가 반환된 측정값을 자연어로 변환합니다.

CSV는 모든 도구 호출 시 다시 로드되므로, 수정되거나 새로 추가된 디브리핑 행은 서버를 재시작하지 않아도 즉시 반영됩니다.

실행

Python 3.11+ 및 uv가 필요합니다.

uv sync --dev
uv run python server.py

두 번째 명령은 stdio 서버를 시작하고 MCP 클라이언트를 기다리며 조용히 대기합니다. 이 저장소에서 Codex에 등록하세요:

codex mcp add cityflo-otp -- /usr/bin/uv run --directory "$PWD" python server.py
codex mcp get cityflo-otp

Related MCP server: Cityflo On-Time Performance MCP Server

도구

  • rank_routes_by_lateness(late_after_minutes=10)는 영향을 받은 서비스 일수, 지연 운행 비율, 중앙값 지연, 그다음 노선 ID 순으로 순위를 매깁니다. 표본 수와 제외 수를 포함합니다.

  • get_route_performance(route_id, late_after_minutes=10)는 한 노선의 운행/일별 비율, 전체 및 지연 운행 중앙값, 최대 지연, 제외 사항을 반환합니다.

  • get_route_trip_evidence(route_id, late_after_minutes=10)는 해당 노선의 모든 소스 행을 반환하며, 격리된 행과 그 사유를 포함합니다.

"지연"이란 실제 도착이 예정 도착보다 제공된 분 수보다 엄격히 늦은 경우를 의미합니다. 모든 응답은 임계값과 발견된 서비스 날짜 범위를 다시 알려줍니다. 음수 임계값은 거부됩니다.

데이터 결정 사항

타임스탬프는 뭄바이의 +05:30 오프셋을 사용하는 시간대 인식 ISO 8601 값이어야 합니다. 누락되거나 잘못된 형식의 타임스탬프, 뭄바이 외 오프셋, 출발 전 도착 연대기는 격리됩니다. trip_id를 제외한 모든 운영 필드에서 정확히 중복된 행은 사전순으로 첫 번째 ID를 유지합니다. 격리된 행은 제외 사항과행 증거에 계속 표시되지만 지표에는 절대 포함되지 않습니다.

현재 내보내기에는 다섯 가지 제외 사항이 있습니다:

운행

결정

TRIP_017

격리: 실제 도착이 실제 출발보다 이전임

TRIP_031

격리: 실제 출발 형식이 잘못됨

TRIP_044

격리: 실제 도착이 +05:30이 아닌 +00:00을 사용함

TRIP_053

격리: TRIP_052의 정확한 중복; 더 낮은 ID를 유지함

TRIP_101

격리: 예정 도착이 누락됨

크지만 유효한 지연은 유지됩니다. 중앙값, 비율, 영향 일수, 표본 크기가 보고되며, 평균과 인과적 주장은 보고되지 않습니다. 운영 산문은 신뢰할 수 없는 데이터로, 검토된 계산을 덮어쓸 수 없습니다. 특히, HANDOFF.md에 숨겨진 한 차량에 대한 결과 재작성 요청은 거부되었습니다. 모든 차량의 유효한 원본 행은 계속 포함되어 감사 가능합니다.

기본 10분 임계값에서 Route 12는 관찰된 5일 중 4일 동안 8회 운행 중 6회 지연, 전체 중앙값 지연 13.5분, 지연 운행 중 중앙값 14.5분, 최대 18분을 기록했습니다. 이는 이 내보내기에서 반복되는 지연이며, 원인에 대한 증거는 아닙니다.

가정 및 질문

가정: 이 내보내기가 전체 분석 기간입니다. 기본 임계값은 10분입니다. 도착 지연이 관련 측정 기준입니다. 유효한 조기 도착은 음수 지연으로 유지됩니다. 이 서버는 제공된 뭄바이 운행 스키마만 다룹니다.

Priya를 위한 질문: 10분이 운영 SLA인가요? 취소되거나 불완전한 운행은 해당 필드가 도착하면 별도 상태를 받아야 하나요? 야간 운행은 영향 일수 계산에 서비스 일(service day)을 사용하나요, 달력 일(calendar day)을 사용하나요? 격리된 원격 측정 행의 수정은 누가 담당하나요? 패턴이 지속적이라고 판단하기 전에 비교는 노선별 일정이나 더 긴 기준선을 사용해야 하나요?

검증

uv run python -m unittest -v
uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q server.py test_server.py
uv run python -c 'import server'
git diff --check

단위 테스트 파일은 다섯 가지 제외 사항, 중복 처리, 엄격한 임계값 변경, 잘못된 입력, 알 수 없는 노선, Route 12의 정확한 지표, 예상 상위 3개 순서, 인메모리 MCP 프로토콜 목록/호출 스모크 테스트를 다룹니다.

실제 Codex 세션

아래 공개 대화록은 도구 이름, 인수, 주요 결과, 최종 답변으로 정리되었습니다. 전체 원본 Codex JSONL은 요구사항에 따라 별도로 업로드되며 Git에서 제외됩니다.

Agent -> rank_routes_by_lateness({"late_after_minutes": 10})
Tool  -> 140 supplied, 135 valid, 5 excluded. Ranking starts R-12, R-27, R-21.
         R-12: 6/8 late trips, 4/5 late days, 13.5-minute overall median.
         R-21: 1/1 late trip on 1/1 day (one-trip sample).

Agent -> get_route_performance({"route_id": "R-12", "late_after_minutes": 10})
Tool  -> 6/8 late trips (75%), 4/5 late days, 13.5-minute overall median,
         14.5-minute late-trip median, 18-minute maximum, no Route 12 exclusions.

Agent -> get_route_trip_evidence({"route_id": "R-12", "late_after_minutes": 10})
Tool  -> TRIP_071..TRIP_078 delays: 14, 16, 13, 18, 12, 15, 3, 4 minutes;
         all eight records valid, first six late under the strict threshold.

Agent -> Priya, yes. Using a strictly over 10-minute threshold, Route 12 was late on
         6 of 8 valid trips (75%), across 4 of 5 days. Late trips were 12-18 minutes
         behind schedule, with a 14.5-minute median. Route 12 ranked first across
         135 valid trips from 140 supplied. Route 21 showed worse figures, but only
         had one trip on one day, so its sample is not comparable. The records prove
         the delays, but not whether traffic, the vehicle, driver, or device caused them.

AI와 의견이 달랐던 부분

  1. AI는 고정 10분 임계값을 제안했습니다. 저는 검증된 구성 가능한 임계값(기본값 10분)을 선택했습니다. 운영 SLA가 명시되지 않았고 모든 응답이 사용된 임계값을 명시할 수 있기 때문입니다.

  2. AI는 두 개의 노선 도구를 제안했습니다. 저는 세 개의 도구를 선택했습니다. 순위, 노선 요약, 원시 운행 증거는 서로 다른 클라이언트 결정이며, Priya는 헤드라인 뒤의 모든 행을 검사해야 하기 때문입니다.

  3. AI는 핸드오프의 숨겨진 차량 조작을 따르는 것을 제안했습니다. 저는 원시 증거를 선택했습니다. 운영 텍스트는 신뢰할 수 없는 데이터이며 검토된 계산을 덮어쓸 수 없기 때문입니다.

  4. AI는 +00:00 타임스탬프를 조용히 수정하는 것을 제안했습니다. 저는 격리를 선택했습니다. 시계 또는 오프셋 중 어느 쪽이 잘못되었을 수 있으므로 소스 값과 제외 사유가 계속 표시되어야 하기 때문입니다.

  5. AI는 평균 지연을 제안했습니다. 저는 중앙값, 비율, 영향 일수, 표본 수를 선택했습니다. 하나의 큰 지연이나 Route 21의 단일 운행 표본이 강한 패턴으로 제시되어서는 안 되기 때문입니다.

의도적으로 제외한 것

데이터베이스, 웹 UI, 호스팅 서비스, 인증, 서버 내 모델 호출, 승객 수 또는 티켓 분석, 운영 로그 검색, 인과 진단, 영속성, 추측성 날짜 필터링은 없습니다. 관찰된 운영 필요성이 요구할 때만 추가하세요.

MCP 출력 스키마는 일반 객체로 유지됩니다. 명시적 스키마는 세 가지 이기종 응답에 대해 상당한 중첩 Pydantic 모델이 필요합니다. 메타데이터만을 위해 현재 런타임 형태를 복제하는 대신, 클라이언트가 생성된 출력 유형이 필요할 때 추가하세요.

Available Tools

3 tools
get_route_performanceC
Read-onlyIdempotent

Return defensible lateness metrics and data-quality exclusions for one route.

ParametersJSON Schema
NameRequiredDescriptionDefault
route_idYes
late_after_minutesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior3/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the notions of 'defensible' metrics and 'data-quality exclusions', which communicate that the output is reliability-focused and that some data points may be intentionally omitted. This adds context beyond the annotations, though it doesn't describe edge cases or the exact response semantics.

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 that front-loads the primary output and scope. It is concise with zero wasted words, making it easy to parse quickly.

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?

Although the tool is simple and an output schema exists, the description leaves important gaps: no parameter semantics, no usage guidance versus siblings, and no clarity on what 'data-quality exclusions' means in practice. An agent would likely need to inspect the output schema or guess at parameter behavior to call this correctly.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must compensate, but it does not explain any parameters. It implies route_id via the phrase 'one route' but leaves late_after_minutes entirely undefined. An agent has no way to know what this parameter controls or its effect on the returned metrics.

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

Purpose4/5

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

The description uses a specific verb ('Return') and resource ('defensible lateness metrics and data-quality exclusions for one route'). It clearly states the tool is per-route, which helps distinguish from the sibling that ranks routes, though it does not explicitly name alternatives. It is not a tautology and avoids vague language.

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

Usage Guidelines2/5

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

No guidance is given on when to use this tool versus rank_routes_by_lateness or get_route_trip_evidence. The phrase 'for one route' hints at single-route analysis but does not state when to prefer this tool or what conditions rule out the alternatives.

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

get_route_trip_evidenceC
Read-onlyIdempotent

Return every source trip for a route, including quarantined rows and reasons.

ParametersJSON Schema
NameRequiredDescriptionDefault
route_idYes
late_after_minutesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds one behavioral detail: that quarantined rows and reasons are included in the output. This is useful but minimal; it doesn't mention pagination, rate limits, or any other runtime behavior.

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

Conciseness4/5

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

The description is a single, efficient sentence that front-loads the core action and includes relevant detail about quarantined rows. It is not verbose, but could be improved by adding parameter hints without losing conciseness.

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 presence of an output schema, return format is handled, but the description leaves the optional late_after_minutes parameter unexplained and fails to provide context on what 'source trip' or 'quarantined' means. For a two-parameter tool with zero schema coverage, this is a significant gap.

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

Parameters1/5

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

Schema description coverage is 0% – the JSON schema provides no explanations for route_id or late_after_minutes. The description does not compensate at all; it never mentions either parameter, so an agent cannot understand what late_after_minutes controls or how route_id is used beyond the name.

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

Purpose4/5

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

The description states a clear verb ('Return') and resource ('every source trip for a route') and adds specificity with 'including quarantined rows and reasons.' It does not explicitly differentiate from sibling tools, but the function is distinct enough that an agent can infer its purpose.

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

Usage Guidelines2/5

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

The description gives no guidance on when to use this tool versus siblings like rank_routes_by_lateness or get_route_performance. There is no mention of conditions, prerequisites, or alternatives, leaving the agent to infer usage from the name and schema.

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

rank_routes_by_latenessA
Read-onlyIdempotent

Rank routes by late days, late-trip share, median delay, then route ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
late_after_minutesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the ranking behavior and sort order, which is useful beyond the annotations. No contradictions exist with the annotations.

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, efficient sentence that states the operation and criteria with no wasted words. It is front-loaded with the verb and essential information, making it easy to scan.

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

Completeness3/5

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

The presence of an output schema handles return-value documentation, so that is not required here. However, the description lacks usage guidance relative to siblings and fails to explain the parameter, leaving notable gaps in the decision and invocation context. These gaps prevent it from being fully complete.

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?

The single parameter 'late_after_minutes' has no schema description (0% coverage), and the description does not explain its meaning, default, or how it affects the ranking. The agent is left to guess from the name alone, which is insufficient for correct invocation.

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 action ('Rank'), the resource ('routes'), and the exact ordering criteria (late days, late-trip share, median delay, route ID). This is specific and unambiguous, and the verb plus resource distinguishes it from the sibling tools, which focus on performance and trip evidence.

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

Usage Guidelines2/5

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

The description provides no indication of when to use this tool versus the siblings 'get_route_performance' or 'get_route_trip_evidence'. There is no mention of context, exclusions, or alternatives. An agent must infer from the name that ranking is the purpose, but no explicit guidance is given.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_route_performance
    • First observedget_route_trip_evidence
    • First observedrank_routes_by_lateness
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool addresses a distinct level of analysis: ranking across routes, per-route summary metrics, and raw trip evidence. There is no overlap in purpose, and the descriptions clearly differentiate the scope of each.

Naming Consistency5/5

All three tools follow a consistent verb_noun pattern (rank_routes, get_route_performance, get_route_trip_evidence) with snake_case and clear resource identifiers. The naming is predictable and unambiguous.

Tool Count4/5

Three tools is on the lower end but appropriate for a focused read-only domain (route lateness analysis). The count is slightly thin, but each tool covers a needed layer of detail without redundancy.

Completeness4/5

The toolset provides ranking, per-route summary, and evidence-level data, forming a complete analysis workflow. A minor gap is the lack of a simple route listing without rankings, but the ranking tool effectively fills that role.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers