MCP server for Tokyo/Japan real-time train data via ODPT API
tokyo-train-mcp demonstrates solid tool definition quality with consistent naming conventions (all verb-first), comprehensive parameter descriptions, and clear input schemas using Zod. All 6 tools are explicitly registered with descriptions and structured inputs. However, output schemas are not documented in the code, the handler implementations are not visible, making it impossible to verify what fields are returned to the LLM. Parameter descriptions are generally good (60-90 chars) but lack constraints like min/max ranges for numeric parameters. Tool descriptions are appropriately detailed (130-180 chars) and explain WHEN to use each tool. The server uses proper tool annotations (readOnlyHint, openWorldHint) correctly on all tools. No security issues detected, no credentials in parameters. Main gaps: (1) missing output schema documentation in tool registration, (2) no pagination parameters on tools that might return large result sets (get-departures, get-service-alerts), (3) no enum constraints on string parameters like 'line' and 'operator' that have known valid formats (e.g., odpt.Railway:TokyoMetro.Ginza).
Get upcoming train departures from a station. Shows scheduled times, destinations, train types, and real-time delay information when available.
Get fare between two stations. Returns ticket fare, IC card fare, and child fares. Only works for stations on the same operator's network.
Get status overview of train lines. Shows which lines are running normally and which have disruptions. Can filter by specific line.
Get current service alerts, delays, and disruptions for train lines. Shows status, cause, and estimated recovery time.
Get detailed information about a station including multilingual names, location, connecting lines, and annual passenger data.
Search for train stations in Tokyo/Japan by name. Supports Japanese, English, and romanized input with fuzzy matching. Use this first to find station IDs for other tools.
Output schemas not documented in tool registration. While input schemas are comprehensive, there is no visible documentation of what fields the tools return. LLMs cannot plan follow-up calls or extract necessary data (e.g., station_id from search-station) without knowing the response structure.
No constraints on string parameters with known valid formats. Parameters like 'line' (e.g., 'odpt.Railway:TokyoMetro.Ginza'), 'operator' (e.g., 'odpt.Operator:TokyoMetro'), and 'direction' follow rigid ODPT API conventions but are registered as free-form strings without regex patterns or enum constraints. LLMs may generate invalid IDs.
No pagination parameters on tools that may return unbounded results. get-departures could return 100+ departures; get-service-alerts could return many lines with alerts. No limit cap enforcement, no offset/cursor, no total count in response specification. Large result sets will exhaust context window.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 55 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 50 | - | v1 |
No numeric bounds specified for 'limit' parameter in get-departures. The parameter accepts 'number' type but provides no min/max. LLMs might pass 0, negative, or extremely large values. Should specify e.g. 'limit: 1-100'.
Parameter descriptions include example IDs (e.g., 'odpt.Station:TokyoMetro.Ginza.Ginza', 'odpt.Railway:TokyoMetro.Ginza') within the description text. LLMs commonly reuse example values literally in subsequent calls, causing hard-coded ID usage instead of dynamic lookups.
No error recovery guidance in tool descriptions. Tools do not explain what to do if a station_id is invalid, if a line is not found, or if a fare lookup fails across operator networks. Descriptions lack phrases like 'If station not found, use search-station to find the correct ID.'