get-train-route-stations
Retrieve detailed stop information including stations, arrival/departure times, and dwell durations for specific train routes on China's railway network.
Instructions
查询特定列车车次在指定区间内的途径车站、到站时间、出发时间及停留时间等详细经停信息。当用户询问某趟具体列车的经停站时使用此接口。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| trainCode | Yes | 要查询的车次 `train_code`，例如"G1033"。 | |
| departDate | Yes | 列车出发的日期 (格式: yyyy-MM-dd)。如果用户提供的是相对日期，请务必先调用 `get-current-date` 解析。 | |
| format | No | 返回结果格式，默认为text，建议使用text。可选标志：[text, json] | text |
Implementation Reference
- src/index.ts:1408-1486 (handler)The main handler function for the 'get-train-route-stations' tool. It searches for the train using the public API to get train_no, then queries the private 12306 API for route stations using cookies, parses the response data with parseRouteStationsInfo, formats it, and returns as text or JSON.
async ({ trainCode, departDate, format }) => { const searchParams = new URLSearchParams({ keyword: trainCode, date: departDate.replaceAll('-', ''), }); const searchUrl = `${SEARCH_API_BASE}/search/v1/train/search`; const searchResponse = await make12306Request<TrainSearchResponse>( searchUrl, searchParams ); if ( searchResponse == null || searchResponse.data.length == 0 || searchResponse.data == undefined ) { return { content: [ { type: 'text', text: '很抱歉，未查询到对应车次。', }, ], }; } const searchData = searchResponse.data[0]; const queryParams = new URLSearchParams({ 'leftTicketDTO.train_no': searchData.train_no, 'leftTicketDTO.train_date': departDate, rand_code: '', }); const queryUrl = `${API_BASE}/otn/queryTrainInfo/query`; const cookies = await getCookie(); if (cookies == null || Object.entries(cookies).length === 0) { return { content: [ { type: 'text', text: 'Error: get cookie failed. Check your network.', }, ], }; } const queryResponse = await make12306Request<RouteQueryResponse>( queryUrl, queryParams, { Cookie: formatCookies(cookies) } ); if (queryResponse == null || queryResponse.data == undefined) { return { content: [ { type: 'text', text: 'Error: get train route stations failed. ', }, ], }; } const routeStationsInfo = parseRouteStationsInfo( queryResponse.data.data ); if (routeStationsInfo.length == 0) { return { content: [{ type: 'text', text: '未查询到相关车次信息。' }], }; } var formatedResult; switch (format) { case 'json': formatedResult = JSON.stringify(routeStationsInfo); break; default: formatedResult = formatRouteStationsInfo(routeStationsInfo); break; } return { content: [{ type: 'text', text: formatedResult }], }; } - src/index.ts:1389-1407 (schema)Zod input schema for the tool parameters: trainCode (required string), departDate (required 10-char date string), format (optional 'text' or 'json').
{ trainCode: z .string() .describe('要查询的车次 `train_code`，例如"G1033"。'), departDate: z .string() .length(10) .describe( '列车出发的日期 (格式: yyyy-MM-dd)。如果用户提供的是相对日期，请务必先调用 `get-current-date` 解析。' ), format: z .string() .regex(/^(text|json)$/i) .default('text') .optional() .describe( '返回结果格式，默认为text，建议使用text。可选标志：[text, json]' ), }, - src/index.ts:1386-1487 (registration)Registers the MCP tool 'get-train-route-stations' on the server instance with name, Chinese description, input schema, and inline handler function.
server.tool( 'get-train-route-stations', '查询特定列车车次在指定区间内的途径车站、到站时间、出发时间及停留时间等详细经停信息。当用户询问某趟具体列车的经停站时使用此接口。', { trainCode: z .string() .describe('要查询的车次 `train_code`，例如"G1033"。'), departDate: z .string() .length(10) .describe( '列车出发的日期 (格式: yyyy-MM-dd)。如果用户提供的是相对日期，请务必先调用 `get-current-date` 解析。' ), format: z .string() .regex(/^(text|json)$/i) .default('text') .optional() .describe( '返回结果格式，默认为text，建议使用text。可选标志：[text, json]' ), }, async ({ trainCode, departDate, format }) => { const searchParams = new URLSearchParams({ keyword: trainCode, date: departDate.replaceAll('-', ''), }); const searchUrl = `${SEARCH_API_BASE}/search/v1/train/search`; const searchResponse = await make12306Request<TrainSearchResponse>( searchUrl, searchParams ); if ( searchResponse == null || searchResponse.data.length == 0 || searchResponse.data == undefined ) { return { content: [ { type: 'text', text: '很抱歉，未查询到对应车次。', }, ], }; } const searchData = searchResponse.data[0]; const queryParams = new URLSearchParams({ 'leftTicketDTO.train_no': searchData.train_no, 'leftTicketDTO.train_date': departDate, rand_code: '', }); const queryUrl = `${API_BASE}/otn/queryTrainInfo/query`; const cookies = await getCookie(); if (cookies == null || Object.entries(cookies).length === 0) { return { content: [ { type: 'text', text: 'Error: get cookie failed. Check your network.', }, ], }; } const queryResponse = await make12306Request<RouteQueryResponse>( queryUrl, queryParams, { Cookie: formatCookies(cookies) } ); if (queryResponse == null || queryResponse.data == undefined) { return { content: [ { type: 'text', text: 'Error: get train route stations failed. ', }, ], }; } const routeStationsInfo = parseRouteStationsInfo( queryResponse.data.data ); if (routeStationsInfo.length == 0) { return { content: [{ type: 'text', text: '未查询到相关车次信息。' }], }; } var formatedResult; switch (format) { case 'json': formatedResult = JSON.stringify(routeStationsInfo); break; default: formatedResult = formatRouteStationsInfo(routeStationsInfo); break; } return { content: [{ type: 'text', text: formatedResult }], }; } ); - src/index.ts:303-332 (helper)Helper function that transforms raw API RouteStationData array into formatted RouteStationInfo array, adding train class/service info to the first station.
function parseRouteStationsInfo( routeStationsData: RouteStationData[] ): RouteStationInfo[] { const result: RouteStationInfo[] = []; routeStationsData.forEach((routeStationData, index) => { if (index == 0) { result.push({ train_class_name: routeStationData.train_class_name, service_type: routeStationData.service_type, end_station_name: routeStationData.end_station_name, station_name: routeStationData.station_name, station_train_code: routeStationData.station_train_code, arrive_time: routeStationData.arrive_time, start_time: routeStationData.start_time, lishi: routeStationData.running_time, arrive_day_str: routeStationData.arrive_day_str, }); } else { result.push({ station_name: routeStationData.station_name, station_train_code: routeStationData.station_train_code, arrive_time: routeStationData.arrive_time, start_time: routeStationData.start_time, lishi: routeStationData.running_time, arrive_day_str: routeStationData.arrive_day_str, }); } }); return result; } - src/index.ts:462-478 (helper)Helper function that formats the RouteStationInfo array into a human-readable markdown table string showing train details, station sequence, times, and durations.
function formatRouteStationsInfo( routeStationsInfo: RouteStationInfo[] ): string { let result = `${routeStationsInfo[0].station_train_code}次列车（${ routeStationsInfo[0].train_class_name } ${ routeStationsInfo[0].service_type == '0' ? '无空调' : '有空调' }）\n站序|车站|车次|到达时间|出发时间|历时(hh:mm)\n`; routeStationsInfo.forEach((routeStationInfo, index) => { result += `${index + 1}|${routeStationInfo.station_name}|${ routeStationInfo.station_train_code }|${routeStationInfo.arrive_time}|${routeStationInfo.start_time}|${ routeStationInfo.arrive_day_str } ${routeStationInfo.lishi}\n`; }); return result; }