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;
}

12306-mcp