12306-MCP

Instructions

Implementation Reference

• src/index.ts:985-1025 (handler)

  The core handler function that implements the tool logic. It makes an API request to 12306.cn for the train's route stations between specified from/to stations on the departure date, handles cookies, parses the response, and returns the list of stations with times.

  async ({
    trainNo: trainNo,
    fromStationTelecode,
    toStationTelecode,
    departDate,
  }) => {
    const queryParams = new URLSearchParams({
      train_no: trainNo,
      from_station_telecode: fromStationTelecode,
      to_station_telecode: toStationTelecode,
      depart_date: departDate,
    });
    const queryUrl = `${API_BASE}/otn/czxx/queryByTrainNo`;
    const cookies = await getCookie(API_BASE);
    if (cookies == null) {
      return {
        content: [{ type: 'text', text: 'Error: get cookie failed. ' }],
      };
    }
    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: '未查询到相关车次信息。' }],
      };
    }
    return {
      content: [{ type: 'text', text: JSON.stringify(routeStationsInfo) }],
    };
  }

• src/index.ts:962-984 (schema)

  Zod input schema defining the parameters for the tool: trainNo (internal train number), fromStationTelecode, toStationTelecode, and departDate.

  {
    trainNo: z
      .string()
      .describe(
        '要查询的实际车次编号 `train_no`，例如 "240000G10336"，而非"G1033"。此编号通常可以从 `get-tickets` 的查询结果中获取，或者由用户直接提供。'
      ),
    fromStationTelecode: z
      .string()
      .describe(
        '该列车行程的**出发站**的 `station_telecode` (3位字母编码`)。通常来自 `get-tickets` 结果中的 `telecode` 字段，或者通过 `get-station-code-by-name` 得到。'
      ),
    toStationTelecode: z
      .string()
      .describe(
        '该列车行程的**到达站**的 `station_telecode` (3位字母编码)。通常来自 `get-tickets` 结果中的 `telecode` 字段，或者通过 `get-station-code-by-name` 得到。'
      ),
    departDate: z
      .string()
      .length(10)
      .describe(
        '列车从 `fromStationTelecode` 指定的车站出发的日期 (格式: yyyy-MM-dd)。如果用户提供的是相对日期，请务必先调用 `get-current-date` 解析。'
      ),
  },

• src/index.ts:959-1027 (registration)

  Registers the 'get-train-route-stations' tool on the MCP server with name, description, input schema, and handler function.

  server.tool(
    'get-train-route-stations',
    '查询特定列车车次在指定区间内的途径车站、到站时间、出发时间及停留时间等详细经停信息。当用户询问某趟具体列车的经停站时使用此接口。',
    {
      trainNo: z
        .string()
        .describe(
          '要查询的实际车次编号 `train_no`，例如 "240000G10336"，而非"G1033"。此编号通常可以从 `get-tickets` 的查询结果中获取，或者由用户直接提供。'
        ),
      fromStationTelecode: z
        .string()
        .describe(
          '该列车行程的**出发站**的 `station_telecode` (3位字母编码`)。通常来自 `get-tickets` 结果中的 `telecode` 字段，或者通过 `get-station-code-by-name` 得到。'
        ),
      toStationTelecode: z
        .string()
        .describe(
          '该列车行程的**到达站**的 `station_telecode` (3位字母编码)。通常来自 `get-tickets` 结果中的 `telecode` 字段，或者通过 `get-station-code-by-name` 得到。'
        ),
      departDate: z
        .string()
        .length(10)
        .describe(
          '列车从 `fromStationTelecode` 指定的车站出发的日期 (格式: yyyy-MM-dd)。如果用户提供的是相对日期，请务必先调用 `get-current-date` 解析。'
        ),
    },
    async ({
      trainNo: trainNo,
      fromStationTelecode,
      toStationTelecode,
      departDate,
    }) => {
      const queryParams = new URLSearchParams({
        train_no: trainNo,
        from_station_telecode: fromStationTelecode,
        to_station_telecode: toStationTelecode,
        depart_date: departDate,
      });
      const queryUrl = `${API_BASE}/otn/czxx/queryByTrainNo`;
      const cookies = await getCookie(API_BASE);
      if (cookies == null) {
        return {
          content: [{ type: 'text', text: 'Error: get cookie failed. ' }],
        };
      }
      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: '未查询到相关车次信息。' }],
        };
      }
      return {
        content: [{ type: 'text', text: JSON.stringify(routeStationsInfo) }],
      };
    }
  );

• src/index.ts:230-252 (helper)

  Helper function used by the handler to parse raw RouteStationData into user-friendly RouteStationInfo, handling the first station specially (using start_time as arrive_time).

  function parseRouteStationsInfo(
    routeStationsData: RouteStationData[]
  ): RouteStationInfo[] {
    const result: RouteStationInfo[] = [];
    routeStationsData.forEach((routeStationData, index) => {
      if (index == 0) {
        result.push({
          arrive_time: routeStationData.start_time,
          station_name: routeStationData.station_name,
          stopover_time: routeStationData.stopover_time,
          station_no: parseInt(routeStationData.station_no),
        });
      } else {
        result.push({
          arrive_time: routeStationData.arrive_time,
          station_name: routeStationData.station_name,
          stopover_time: routeStationData.stopover_time,
          station_no: parseInt(routeStationData.station_no),
        });
      }
    });
    return result;
  }

• src/types.ts:188-193 (schema)

  TypeScript type definition for the output RouteStationInfo used in the tool's response.

  export type RouteStationInfo = {
    arrive_time: string;
    station_name: string;
    stopover_time: string;
    station_no: number;
  };