航班动态 MCP 调用指南

调用方式

基础信息

> API Key 绑定用户身份，所有调用自动关联该用户，无需传递用户标识。

> C 端用户获取 API Key：https://h5.133.cn/webapp/pages/mcpApiKey

统一调用格式

curl -s -X POST https://fly.huoli.com/mcp/dynamic_server_huoshan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "<工具名>",
      "arguments": { ... }
    }
  }'

响应结构

{"msg": "success", "data": {...}, "code":0}

检查 code 字段判断是否等于0。业务错误通过 msg 返回，HTTP 状态码仍为 200。

铁律（违反即出错）

铁律 1 — 必须先搜索机场/城市获取三字码

dynamic_airport_search 是所有航班查询的入口，dep/arr/airportCode/depCode/arrCode 等三字码必须通过该工具获取，不可自行编造。

铁律 2 — 机场航线和天气直接使用三字码查询

dynamic_airport_lines、dynamic_airport_wearher、dynamic_city_wearher 直接使用三字码查询，无需前置搜索。

铁律 3 — 航司搜索结果必须展示完整信息

dynamic_airline_search 返回的航司列表需展示航司二字码、简称、全称，并标注是否为客运航司。

铁律 4 — 航班查询结果必须格式化展示

查询返回后必须按以下格式展示给用户：

【航班号】航司名
状态：航班状态
计划：计划起飞 → 计划到达
实际：实际起飞 → 实际到达
航站楼：T1 → T2  登机口：G12  行李转盘：3
值机柜台：A01-05
距离：XXX km
机型：机型  注册号：XXXX

若 isShare=1，需标注"共享航班，承运航班号：XXX"。

铁律 5 — 延误/取消/前序航班异常需主动提醒

• dynamic_flight_change 返回调时记录时，需对比展示变更前后的计划时间
• dynamic_flight_prevList 返回前序航班时，若前序状态异常（延误/取消），需提醒用户当前航班可能受到影响
• dynamic_flight_calendar 返回日历数据时，需按时间线展示每日状态并标注准点/延误/取消

铁律 6 — 出行决策信息需对比展示

• dynamic_flight_ontimeRank：展示各航班的准点率及排名，按准点率从高到低排列
• dynamic_flight_congestion：展示旅客数、座位数、拥挤状态（空闲/正常/拥挤）及历史趋势
• dynamic_plane_type：展示详细机型、计划机型、机龄、座位数、厂商、WIFI、飞机大小
• dynamic_plane_cabin：按舱位分别展示座位布局、间距、宽度、角度、餐食信息

铁律 7 — 赏月航班需告知观赏方位

dynamic_flight_sun 返回后，需告知用户日出/日落/赏月的观赏方位（左侧/右侧），不可观看的需明确说明。

铁律 8 — 值机功能直接通过航班号进入

无需先查询行程，用户提供航班号、起降地三字码、航班日期即可直接调用 checkin_window 查询值机窗口，再通过 checkin_handle 获取在线值机入口。成果展示时应展示值机开放/截止时间和官方入口链接。

铁律 9 — 行程信息需展示完整要素

trip_query 返回的行程列表必须按 triptype 区分展示：

• flight：航班号、出发/到达城市、计划/实际时间、航站楼、登机口、值机柜台
• train：车次号、出发/到达站、车厢座位、检票口
• car：车型、车牌、司机、用车类别
• hotel：酒店名、地址、房型、入住/离店日期

铁律 10 — 增值服务需按顺序调用

• checkin_pet-cabin_types → checkin_pet-cabin_airlines：先查宠物类型枚举，再选择类型查支持航司
• checkin_baggage_condition：需先确认航班号、舱位代码、乘机人类型，不可自行编造舱位代码

工具决策树

用户意图
├── 搜索机场/城市 → dynamic_airport_search
├── 搜索航司 → dynamic_airline_search
├── 查询航班动态
│   ├── 单航班 → dynamic_flight_query
│   ├── 多航班 → dynamic_flight_batch
│   ├── 前序航班 → dynamic_flight_prevList
│   └── 调时记录 → dynamic_flight_change
├── 出行决策
│   ├── 准点率排名 → dynamic_flight_ontimeRank
│   ├── 延误取消日历 → dynamic_flight_calendar
│   ├── 航班拥挤度 → dynamic_flight_congestion
│   ├── 机场天气 → dynamic_airport_wearher
│   ├── 城市天气 → dynamic_city_wearher
│   ├── 机型详情 → dynamic_plane_type
│   └── 舱位舒适度 → dynamic_plane_cabin
├── 查询行程 → trip_query
├── 在线值机
│   ├── 值机时间 → checkin_window
│   └── 是否支持 → checkin_handle
├── 宠物服务
│   ├── 宠物类型 → checkin_pet-cabin_types
│   └── 宠物客舱航司 → checkin_pet-cabin_airlines
├── 付费行李 → checkin_baggage_condition
└── 主题航班 → dynamic_flight_sun

业务流程

航班动态查询流程

dynamic_airport_search(keyword)
    ↓ 返回机场三字码
dynamic_flight_query(no, date, dep, arr) 或 dynamic_flight_batch(flights)
    ↓ 返回航班基本信息
用户查看详情
    ├── dynamic_flight_prevList → 查看前序航班
    ├── dynamic_flight_change → 查看调时记录
    └── dynamic_flight_sun → 查看赏月/日出日落

出行决策流程

dynamic_airport_search(keyword) → dynamic_airport_lines
    ↓
dynamic_flight_ontimeRank(dep, arr, date)
    ↓
dynamic_flight_calendar(no, date, dep, arr)
    ↓
dynamic_flight_congestion(no, date, dep, arr)
    ↓
dynamic_airport_wearher(airportCode) / dynamic_city_wearher(cityCode)
    ↓
dynamic_plane_type(no, date, dep, arr)
    ↓
dynamic_plane_cabin(no, date, dep, arr)

行程与值机流程

trip_query(tripDateFrom, tripDateTo)
    ↓
用户选择行程
    ↓
checkin_window(depCode, arrCode, flightDate, flightNo)
    ↓
checkin_handle(depCode, arrCode, flightDate, flightNo)
    ↓
引导用户通过管家链接完成值机

工具说明

机场工具

dynamic_airport_search — 机场/城市/国家搜索

根据关键词搜索机场、城市或国家，支持三字码、名称等模糊匹配。

必填： keyword（搜索关键词，支持机场名、城市名、国家名或三字码）

响应关键字段： data.list[].code(编码)、type(1=机场/2=城市/3=国家)、airportFullName、airportName、city、cityEn、province、tag、countryName、area

注意： 所有航班查询的入口，返回的三字码必须用于后续调用，不可编造。

dynamic_airline_search — 航司搜索

关键词搜索航司信息。

必填： keyword（搜索关键词，支持航司名或二字码）

响应关键字段： data.list[].code(二字码)、threeCode(三字码)、shortName(简称)、name(一般名)、fullName(全称)、passenger(是否客运)、freight(是否货运)

dynamic_airport_lines — 机场航线查询

根据机场三字码与进出港标识，查询该机场的进港或出港航线列表。

必填： airportCode(机场三字码)、flag(1=进港，2=出港)

响应关键字段： data.airport(当前机场)、plan/flew/delay/cancel(航班统计)、data.list[].airport(对端机场)、各航线统计

dynamic_airport_wearher — 机场天气查询

根据机场三字码查询机场实时天气报文（METAR）。

必填： airportCode（机场三字码）

响应关键字段： data.METAR.type(天气类型)、temperature、visib(可见度)、wind(风向风力)、windSpeed、windDirection、clouds、trends、tmpLow、tmpHigh、aqi、weather(天气描述)

dynamic_city_wearher — 城市天气查询

根据城市编码查询城市实时天气与空气质量。

必填： cityCode（城市编码，通常与机场三字码一致）

响应关键字段： data.weather(天气)、temperature、templow/temphigh、wind(风力风向)、hum(湿度)、aqi、aqi_lv、aqigrad

航班工具

dynamic_flight_batch — 航班基本信息批量查询

批量查询航班基本信息，支持多种入参组合，单次不超过 20 条。

必填： flights（数组）

入参组合（任选其一）：

• no + date（航班号+日期）
• dep + arr + date（起降地+日期）
• no + dep + arr + date（航班号+起降地+日期）

响应关键字段： data[].flightNo、depCode/arrCode、state(航班状态)、depPlanTime/arrPlanTime、depReadyTime/arrReadyTime、depTime/arrTime、depTerm/arrTerm、gate、luggage、tailNo、isShare、shareInfo、checkIn.counter、prevFlight、followFlight、distance

dynamic_flight_query — 航班基本信息单条查询

查询单个航班基本信息，支持多种入参组合。

必填/可选： 同 dynamic_flight_batch 的参数组合方式

入参组合（任选其一）： no+date / dep+arr+date / no+dep+arr+date

date 为必填项

响应关键字段： 同 dynamic_flight_batch（返回数组结构）

dynamic_flight_prevList — 前序列表查询

查询执行当前航班前飞机所执飞的航班列表。

必填： dep(起飞地三字码)、arr(到达地三字码)、date(飞行日期 YYYY-MM-DD)、no(航班号)

响应关键字段： data.tailNo(注册号)、model(机型)、duration(总飞行时长)、times(总班次)、data.flights[].flightNo、depCode/arrCode、depName/arrName、depCity/arrCity、depTerm/arrTerm、depTime/arrTime、depPlanTime/arrPlanTime、airlineCode、state、type(current/arrived/notArrived)

注意： 若前序状态异常（延误/取消），需主动提醒用户当前航班可能受影响。

dynamic_flight_change — 调时记录查询

查询航班计划时刻变更记录。

必填： no(航班号)、date(航班日期 YYYY-MM-DD)、dep(起飞地三字码)、arr(到达地三字码)

响应关键字段： data.datas[].flightNo、depCode/arrCode、localDate、depPlanTimeBefore/arrPlanTimeBefore(变更前)、depPlanTimeAfter/arrPlanTimeAfter(变更后)、createTime/updateTime

注意： 需对比展示变更前后的计划时间。

dynamic_flight_congestion — 航班拥挤度查询

查询指定航班的客座拥挤度。

必填： dep(起飞地三字码)、arr(到达地三字码)、date(飞行日期 YYYY-MM-DD)、no(航班号)

响应关键字段： data.passenger(旅客数)、seat(座位数)、state(拥挤状态：空闲/正常/拥挤)、data.list[].date(历史日期)、passenger(历史旅客数)、state(历史状态)

dynamic_flight_calendar — 延误取消日历查询

查询该航班最近一段时间每日的准点/延误/取消状态。

必填： dep(起飞地三字码)、arr(到达地三字码)、date(飞行日期 YYYY-MM-DD)、no(航班号)

响应关键字段： data.list[].date(日期)、state(状态：ontime=准点，dly=延误，cancel=取消，none=无计划)

dynamic_flight_ontimeRank — 准点率排名查询

按起飞地、到达地、日期，查询航线准点率及排名。

必填： dep(起飞地三字码)、arr(到达地三字码)、date(航班日期 YYYY-MM-DD)

响应关键字段： data.flights[].flightNo、flightDate、depCode/arrCode、planTime、rate(准点率)、state

注意： 按准点率从高到低排列展示。

dynamic_plane_type — 机型详情查询

查询执飞飞机的机型详情。

必填： no(航班号)、date(航班日期 YYYY-MM-DD)、dep(起飞地三字码)、arr(到达地三字码)

响应关键字段： data.model(详细机型)、planModel(计划机型)、age(机龄)、avgage(平均机龄)、seatSize(座位数)、producer(厂商)、ticketCode、wifi(0/1)、apSize(大/中/小)

dynamic_plane_cabin — 舱位舒适度查询

查询各舱位的舒适度信息。

必填： no(航班号)、date(航班日期 YYYY-MM-DD)、dep(起飞地三字码)、arr(到达地三字码)

响应关键字段： data.cabins[].cabinName(舱位名称)、cabinCode(舱位代码)、layout(座位布局)、space(间距)、width(宽度)、tilt(角度)、meal(餐食)、mealCode(餐食代码)

dynamic_flight_sun — 赏月/日出日落查询

计算航班飞行过程中是否可观赏日出、日落或赏月及观赏方位。

必填： no(航班号)、date(航班日期 YYYY-MM-DD)、dep(起飞地三字码)、arr(到达地三字码)

响应关键字段： data.rise(日出：left/right/null)、set(日落：left/right/null)、moon(赏月：left/right/null)

注意： 需告知用户观赏方位，不可观看的需明确说明。

行程与值机工具

trip_query — 行程查询

按时间范围查询用户的行程列表。

必填： tripDateFrom(起始时间 yyyy-MM-dd)、tripDateTo(结束时间 yyyy-MM-dd)

响应关键字段： data[].triptype(flight/train/car/hotel)、tripkey、tripNo、depcode/arrcode、depname/arrname、deptime/arrtime、deptimeplan/arrtimeplan、status、passengers 等

• flight 额外：airlinecode/airlinename、depterm/arrterm、chdsk、board
• train 额外：traintype、entrance、carriage
• car 额外：category、carno、carmodel、drivername
• hotel 额外：hotelname、hoteladdress、roomtype、checkindate/checkoutdate

checkin_window — 值机时间窗口查询

根据航班与日期返回值机开放/截止等关键时间点。

必填： depCode(出发地三字码)、arrCode(到达地三字码)、flightDate(航班日期 yyyy-MM-dd)、flightNo(航班号)

响应关键字段： data.ckiOpenTime(值机开放)、ckiCloseTime(截止)、checkinDeadline(柜台截止)、gateCloseTime(登机口关闭)、timezone、entryUrl(官方入口)、entryDesc

checkin_handle — 值机支持查询

判断指定航班在当前渠道/时间窗口是否支持在线值机。

必填： depCode(出发地三字码)、arrCode(到达地三字码)、flightDate(航班日期 yyyy-MM-dd)、flightNo(航班号)

响应关键字段： data.ckiUrl(管家值机链接)

增值工具

checkin_pet-cabin_types — 宠物类型查询

获取系统支持的宠物类型枚举。

无参数，直接调用。

响应关键字段： data[].type(编码)、name(名称)、img(图标地址)

checkin_pet-cabin_airlines — 宠物客舱航司查询

基于航线与起飞日期及宠物类型，查询支持宠物进客舱的航司清单。

必填： flightDate(起飞日期 yyyy-MM-dd)、depCode(出发三字码)、arrCode(到达三字码)、petType(宠物类型，从 checkin_pet-cabin_types 获取)

响应关键字段： data[].airlineCode(二字码)、airlineCodeIcao(三字码)、airlineName(名称)、handleUrl(办理入口)

checkin_baggage_condition — 付费行李查询

校验指定航班航段在当前舱位与乘机人类型下是否可售额外行李服务。

必填： flightNo(航班号)、depCode(出发地三字码)、arrCode(到达地三字码)、cabin(舱位代码)、passengerType(ADT/CHD/INF)、flightDate(航班日期 yyyy-MM-dd)

响应关键字段： data.handleUrl(办理入口链接，为空表示不可购买)

数据字典

完整的数据字典（航班状态、数据类型、行程类型、常用三字码等）请见 reference.md。