# 12306-MCP 服务 原理

## 1. 启动初始化

### 1.1 车站数据加载

服务启动时通过 `getStations()` 函数从 12306 API 获取全国车站信息，构建四个核心索引：

**具体流程：**
1. 访问 12306 首页 (https://www.12306.cn/index/)
2. 从 HTML 中提取车站名称 JS 文件路径 
3. 下载并解析 JS 文件，获取原始车站数据
4. 补充缺失的车站信息 (MISSING_STATIONS)
5. 基于车站数据得到四个核心数据结构映射表

```typescript
// 1. 车站id -> 车站信息
STATIONS: Record<string, StationData>        

// "AAA": {
// "station_id": "@aaa",
// "station_name": "北京北",
// "station_code": "AAA",
// "station_pinyin": "beijingbei",
// "station_short": "aaa",
// "station_index": "0",
// "code": "1234",
// "city": "北京",
// "r1": "",
// "r2": ""
// }


//  2. 城市名 ->  车站id 和 站名 (可能一个城市多个站)
CITY_STATIONS: Record<string, { station_code: string; station_name: string }> 

// "北京": [{"station_code": "AAA","station_name": "北京北"},{"station_code": "BBB","station_name": "京东"},...]

// 3. 车站名(与城市名相同,只会有一个) -> 车站id 和 站名 
CITY_CODES: Record<string, { station_code: string; station_name: string }>      

// "北京":{"station_code":"CCC","station_name":"北京"}

// 4. 车站名 ->  车站id 和 站名
NAME_STATIONS: Record<string, { station_code: string; station_name: string }>   

// "北京北":{"station_code":"AAA","station_name":"北京北"}

```

## 2. MCP tools

### 2.1 基础tool

- **`get-current-date`**: 获取上海时区当前日期
  - 返回当前上海时区的时间日期字符串("yyyy-MM-dd")
  - 为其他工具提供准确的查询日期基准

- **`get-stations-code-in-city`**: 查询城市内所有车站（使用 `CITY_STATIONS`）
  - 输入：中文城市名
  - 查找：`CITY_STATIONS[city]` 获取该城市所有车站列表
  - 返回：包含 `station_code` 和 `station_name` 的数组
    
- **`get-station-code-of-citys`**: 获取城市代表车站id（使用 `CITY_CODES`）
  - 输入：城市名（支持 "|" 分隔的多个城市）
  - 查找：`CITY_CODES[city]` 获取与城市同名的主要车站
  - 返回：每个城市对应的代表车站信息

- **`get-station-code-by-names`**: 车站名转车站id（使用 `NAME_STATIONS`）
  - 输入：具体车站名（支持 "|" 分隔的多个车站）
  - 查找：`NAME_STATIONS[stationName]` 精确匹配车站名
  - 返回：车站id和车站名

- **`get-station-by-telecode`**: 车站id查车站信息（使用 `STATIONS`）
  - 输入：车站id
  - 查找：`STATIONS[telecode]` 获取完整车站信息
  - 返回：包含拼音、城市等详细信息

### 2.2 核心tool (输入可通过基础tool获取)

- **`get-tickets`**: 查询12306余票信息
  - 输入：出发日期、出发站id、到达站id、车次类型筛选
  - 参数处理：检查日期不早于当前日期，验证车站id存在性, 构造请求入参
  - Cookie 处理：先获取 12306 Cookie 用于身份验证
  - API 调用：访问 `/otn/leftTicket/query` 接口
  - 数据处理, 车次类型筛选
  - 返回格式化数据

- **`get-interline-tickets`**: 中转换乘查询，支持指定中转站
  - 输入：出发站id、到达站id、中转站id、是否显示无座、车次类型筛选
  - 参数处理：检查日期不早于当前日期，验证车站id存在性, 构造请求入参
  - Cookie 处理：先获取 12306 Cookie 用于身份验证
  - API 调用：访问 `/lcquery/queryU` 接口
  - 数据处理, 车次类型筛选
  - 返回格式化数据

- **`get-train-route-stations`**: 列车经停站查询
  - 输入：车次编码(可以调用get-tickets获取)、出发站id、到达站id、出发日期
  - 参数处理：检查日期不早于当前日期，验证车站id存在性, 构造请求入参
  - Cookie 处理：先获取 12306 Cookie 用于身份验证
  - API 调用：访问 `/otn/czxx/queryByTrainNo` 接口
  - 返回格式化数据

## 3. 数据流程与工具关系

### 3.1 车票查询流程

```
用户查询 "后天北京到上海的高铁" - 大模型调用流程：
    ↓
1. get-current-date() → "2024-01-15" (获取当前日期)
2. 大模型理解后天日期 → "2024-01-17"
3. get-station-code-of-citys("北京|上海") → {"北京": {"station_code": "BJP","station_name": "北京"}, "上海": {"station_code": "SHH","station_name": "上海"}}
    ↓
4. get-tickets(date: "2024-01-17", fromStation: "BJP", toStation: "SHH", trainFilterFlags: "G")
    ↓
5. 内部数据处理(参数验证, Cookie获取, API调用, 格式化输出文本)
    ↓
6. 返回格式化的高铁车次信息（车次、时间、价格、余票等）
```

### 3.2 中转查询流程

```
用户查询 "深圳到拉萨，经过西安中转"
    ↓
1. 获取三个城市的车站id
2. get-interline-tickets(from: "SZQ", to: "LSO", transfer: "XAY")
    ↓
3. 内部数据处理(参数验证, Cookie获取, API调用, 格式化输出文本)
    ↓
4. 返回中转方案（第一程 + 第二程）
```

### 3.3 经停站查询流程

```
用户查询 "G1次列车经停哪些站"
    ↓
1. get-train-route-stations(trainNo: "G1", from: "BJP", to: "SHH")
    ↓
2. 数据处理：parseRouteStationsData() → parseRouteStationsInfo()
    ↓
3. 返回经停站列表（站名、到达时间、出发时间、停留时间）
```

### 3.4 工具依赖关系

```
基础工具层：
├── get-current-date 
├── get-stations-code-in-city 
└── get-station-code-of-citys 
└── get-station-code-by-names 
└── get-station-by-telecode 

     ↓ 为核心工具层提供基础数据

核心工具层：
├── get-tickets (依赖车站id)
├── get-interline-tickets (依赖车站id)
└── get-train-route-stations (依赖车站id和车次号)
```