12306-mcp

Instructions

Implementation Reference

• src/index.ts:922-936 (handler)

  The handler function that implements the core logic of the 'get-station-by-telecode' tool. It retrieves station details from the STATIONS object using the provided telecode and returns it as JSON text content or an error if not found.

  async ({ stationTelecode }) => {
      if (!STATIONS[stationTelecode]) {
          return {
              content: [{ type: 'text', text: 'Error: Station not found. ' }],
          };
      }
      return {
          content: [
              {
                  type: 'text',
                  text: JSON.stringify(STATIONS[stationTelecode]),
              },
          ],
      };
  }

• src/index.ts:918-921 (schema)

  Input schema definition using Zod for the stationTelecode parameter.

      stationTelecode: z
          .string()
          .describe('车站的 `station_telecode` (3位字母编码)'),
  },

• src/index.ts:914-937 (registration)

  The server.tool registration call that defines and registers the 'get-station-by-telecode' tool with its name, description, input schema, and handler.

  server.tool(
      'get-station-by-telecode',
      '通过车站的 `station_telecode` 查询车站的详细信息，包括名称、拼音、所属城市等。此接口主要用于在已知 `telecode` 的情况下获取更完整的车站数据，或用于特殊查询及调试目的。一般用户对话流程中较少直接触发。',
      {
          stationTelecode: z
              .string()
              .describe('车站的 `station_telecode` (3位字母编码)'),
      },
      async ({ stationTelecode }) => {
          if (!STATIONS[stationTelecode]) {
              return {
                  content: [{ type: 'text', text: 'Error: Station not found. ' }],
              };
          }
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify(STATIONS[stationTelecode]),
                  },
              ],
          };
      }
  );

• src/types.ts:138-162 (schema)

  TypeScript interface defining the StationData structure, which matches the output format returned by the tool from STATIONS[telecode]. Includes array of keys for parsing.

  export type StationData = {
      station_id: string;
      station_name: string;
      station_code: string;
      station_pinyin: string;
      station_short: string;
      station_index: string;
      code: string;
      city: string;
      r1: string;
      r2: string;
  };
  
  export const StationDataKeys: (keyof StationData)[] = [
      'station_id',
      'station_name',
      'station_code',
      'station_pinyin',
      'station_short',
      'station_index',
      'code',
      'city',
      'r1',
      'r2',
  ];

• src/index.ts:1489-1514 (helper)

  Helper function that asynchronously loads the global STATIONS dictionary from the 12306 website by fetching and parsing station data JavaScript file, adding missing stations, which is used by the tool handler.

  async function getStations(): Promise<Record<string, StationData>> {
      const html = await make12306Request<string>(WEB_URL);
      if (html == null) {
          throw new Error('Error: get 12306 web page failed.');
      }
      const match = html.match('.(/script/core/common/station_name.+?.js)');
      if (match == null) {
          throw new Error('Error: get station name js file failed.');
      }
      const stationNameJSFilePath = match[0];
      const stationNameJS = await make12306Request<string>(
          new URL(stationNameJSFilePath, WEB_URL)
      );
      if (stationNameJS == null) {
          throw new Error('Error: get station name js file failed.');
      }
      const rawData = eval(stationNameJS.replace('var station_names =', ''));
      const stationsData = parseStationsData(rawData);
      // 加上缺失的车站信息
      for (const station of MISSING_STATIONS) {
          if (!stationsData[station.station_code]) {
              stationsData[station.station_code] = station;
          }
      }
      return stationsData;
  }