Metadata-Version: 2.4
Name: mcp-tuniu-travel
Version: 1.2.0
Summary: 途牛旅行助手MCP Server — 17个工具覆盖酒店/机票/火车票/景点门票/邮轮/度假全品类查询预订，途牛API实时数据直连，含图片渲染和服务间互推荐
Author: Tuniu Travel MCP Team
License-Expression: MIT
Keywords: flight,hotel,mcp,ticket,train,travel,tuniu,旅行,机票,火车票,途牛,酒店,门票
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Other/Nonlisted Topic
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🧳 途牛旅行助手

途牛旅行助手MCP Server — 17个工具覆盖酒店、机票、火车票、景点门票、邮轮、度假全品类查询与预订，途牛API实时数据直连，含图片渲染和服务间互推荐，零配置即装即用。

## ✨ 核心特性

▸ **全品类覆盖** — 酒店/机票/火车票/景点门票/邮轮/度假6大品类17个工具，从搜索到下单全流程闭环
▸ **图片渲染** — 酒店、邮轮、房型搜索结果附带高清图片，直观展示，所见即所得
▸ **服务间互推荐** — 每个查询工具末尾自动推荐关联服务，如搜酒店推荐景点门票和机票，搜火车票推荐酒店和邮轮
▸ **实时数据直连** — 途牛旅行API实时返回，价格、余票、房态均为最新数据
▸ **格式化输出** — 查询类工具返回结构化Markdown文本，信息一目了然；订单类工具返回JSON便于程序处理
▸ **完整预订链路** — 搜索→详情→下单→取消，酒店/机票/火车票/门票均支持完整预订流程
▸ **安全代理架构** — 腾讯云SCF代理+SSL证书验证+域名白名单，数据传输安全可靠
▸ **零配置即用** — MCP URL直连即用，PROXY_TOKEN内置兜底值

## 🛠 工具列表（17个）

### 🏨 酒店工具（3个）

#### hotel_search — 酒店搜索
按城市和日期搜索酒店，支持关键词、商圈筛选和翻页。返回酒店列表、价格、评分及酒店图片。

**参数：**
- `cityName`（string，选填）：城市名称，如上海、北京（首页查询必填）
- `checkInDate`（string，选填）：入住日期，如2025-06-20
- `checkOutDate`（string，选填）：离店日期，如2025-06-22
- `keyword`（string，选填）：搜索关键词，如外滩、迪士尼
- `queryId`（string，选填）：翻页查询ID（翻页查询时必填）
- `pageNum`（int，选填）：翻页页码，从1开始
- `districtName`（string，选填）：区域/商圈名称，如浦东、春熙路

#### hotel_detail — 酒店详情
查看酒店房型和报价，返回preBookParam用于下单。结果含酒店图片、房型图片、入住政策和各价格方案。

**参数：**
- `hotelId`（string，选填）：酒店ID（hotelId或hotelName至少填一个）
- `hotelName`（string，选填）：酒店名称，如上海外滩华尔道夫
- `checkInDate`（string，选填）：入住日期
- `checkOutDate`（string，选填）：离店日期

#### hotel_create_order — 酒店下单
基于hotel_detail返回的preBookParam预订酒店。

**参数：**
- `hotelId`（string，必填）：酒店ID
- `roomId`（string，必填）：房型ID
- `preBookParam`（string，必填）：预订参数，来自hotel_detail返回
- `checkInDate`（string，必填）：入住日期
- `checkOutDate`（string，必填）：离店日期
- `roomCount`（int，必填）：房间数量
- `roomGuests`（string，必填）：入住人信息JSON字符串
- `contactName`（string，必填）：联系人姓名
- `contactPhone`（string，必填）：联系人手机号

---

### ✈️ 机票工具（5个）

#### flight_search — 机票搜索
按出发/到达城市和日期搜索航班，支持单程/往返、多种排序。返回航班号、起降时间、价格等信息。

**参数：**
- `departureCityName`（string，必填）：出发城市，如上海、北京
- `arrivalCityName`（string，必填）：到达城市，如北京、成都
- `departureDate`（string，必填）：出发日期，如2025-06-20
- `tripType`（int，选填）：行程类型，0单程1往返，默认0
- `returnDate`（string，选填）：返程日期，往返时必填
- `sortType`（int，选填）：排序类型，0价格1时间2折扣

#### flight_cabin_detail — 机票舱位详情
查看航班各舱位价格和退改规则，返回cabinPriceId用于下单。需先通过flight_search获取航班号。

**参数：**
- `departureCityName`（string，必填）：出发城市
- `arrivalCityName`（string，必填）：到达城市
- `departureDate`（string，必填）：出发日期
- `flightNo`（string，必填）：航班号，如MU5101

#### flight_booking_info — 机票预订信息
获取下单时必填字段说明和乘客信息格式要求，下单前建议先调用此工具了解必填项。

**参数：** 无

#### flight_save_order — 机票下单
基于舱位详情的cabinPriceId预订机票。

**参数：**
- `departureCityName`（string，必填）：出发城市
- `arrivalCityName`（string，必填）：到达城市
- `departureDate`（string，必填）：出发日期
- `flightNo`（string，必填）：航班号
- `cabinPriceId`（string，必填）：舱位价格ID，来自flight_cabin_detail返回
- `tourists`（string，必填）：乘客信息JSON字符串

#### flight_cancel_order — 机票取消订单
取消已创建的机票订单。

**参数：**
- `orderId`（string，必填）：订单ID

---

### 🚄 火车票工具（5个）

#### train_search — 火车票搜索
按出发/到达城市和日期搜索车次，支持6种排序方式。返回车次、时间、价格、余票等信息。

**参数：**
- `departureCityName`（string，选填）：出发城市（首页查询必填）
- `arrivalCityName`（string，选填）：到达城市
- `departureDate`（string，选填）：出发日期
- `queryId`（string，选填）：翻页查询ID（翻页查询时必填）
- `sortType`（int，选填）：排序类型，0时间1价格2时长3出发早到晚4出发晚到早5到达早到晚

#### train_detail — 火车票车次详情
查看座位余票和价格，返回resId用于预订。需先通过train_search获取车次号。

**参数：**
- `departureStationName`（string，必填）：出发站名称，如上海虹桥
- `arrivalStationName`（string，必填）：到达站名称，如北京南
- `departureDate`（string，必填）：出发日期
- `trainNum`（string，必填）：车次号，如G2

#### train_book — 火车票预订
基于车次详情的resId预订火车票。

**参数：**
- `resources`（string，必填）：座位资源信息JSON字符串
- `adultTourists`（string，必填）：成人乘客信息JSON字符串
- `contact`（string，必填）：联系人信息JSON字符串

#### train_order_detail — 火车票订单详情
查看已创建的火车票订单详情。

**参数：**
- `orderId`（string，必填）：订单ID

#### train_cancel_order — 火车票取消订单
取消已创建的火车票订单。

**参数：**
- `orderId`（string，必填）：订单ID

---

### 🎫 门票工具（2个）

#### ticket_query — 景点门票查询
按景点名称搜索门票价格和票种信息，返回productId和resourceId用于下单。

**参数：**
- `scenic_name`（string，必填）：景点名称，如故宫、迪士尼、长隆

#### ticket_create_order — 门票下单
基于门票查询的productId和resourceId预订景点门票。

**参数：**
- `product_id`（string，必填）：产品ID，来自ticket_query返回
- `resource_id`（string，必填）：资源ID，来自ticket_query返回
- `depart_date`（string，必填）：出行日期
- `adult_num`（int，必填）：成人数量
- `contact_name`（string，必填）：联系人姓名
- `contact_mobile`（string，必填）：联系人手机号
- `tourist_1_name`（string，必填）：游客1姓名
- `tourist_1_mobile`（string，必填）：游客1手机号
- `tourist_1_cert_type`（string，必填）：游客1证件类型，如身份证
- `tourist_1_cert_no`（string，必填）：游客1证件号码

---

### 🚢 邮轮工具（1个）

#### cruise_search — 邮轮搜索
按日期范围和航线搜索邮轮产品，返回邮轮名称、价格、天数、品牌及邮轮图片。不填日期默认未来30天。

**参数：**
- `departsDateBegin`（string，选填）：出发日期范围-开始，如2025-06-20
- `departsDateEnd`（string，选填）：出发日期范围-结束，如2025-07-20
- `cruiseLineName`（string，选填）：邮轮航线名称，如日本、东南亚
- `pageNum`（int，选填）：页码，从1开始
- `pageSize`（int，选填）：每页数量，默认10

---

### 🏖️ 度假工具（1个）

#### holiday_search — 度假产品搜索
搜索跟团游、自由行等度假产品，支持按目的地、天数、价格、产品类型筛选。返回产品名称、价格、天数等信息。

**参数：**
- `departsDateBegin`（string，选填）：出发日期范围-开始
- `departsDateEnd`（string，选填）：出发日期范围-结束
- `keyWord`（string，选填）：关键词，如三亚、日本、亲子
- `tourDay`（int，选填）：行程天数，如5
- `queryTypeName`（string，选填）：产品类型，如跟团游、自由行
- `highPrice`（int，选填）：最高价格
- `lowPrice`（int，选填）：最低价格
- `departCityName`（string，选填）：出发城市，如上海、北京
- `pageNum`（int，选填）：页码，从1开始
- `pageSize`（int，选填）：每页数量

---

## 📝 使用示例

- "上海6月20到22日的酒店" → hotel_search 搜索酒店列表（含图片）
- "这个酒店有什么房型" → hotel_detail 查看房型报价（含房型图片）
- "北京到上海6月20日的机票" → flight_search 搜索航班
- "MU5101航班的舱位价格" → flight_cabin_detail 查看舱位详情
- "上海到北京6月20日的高铁" → train_search 搜索车次
- "G2车次的余票情况" → train_detail 查看座位余票
- "故宫门票多少钱" → ticket_query 查询景点门票
- "有什么日本邮轮" → cruise_search 搜索邮轮产品（含图片）
- "三亚5天跟团游" → holiday_search 搜索度假产品

## 🔗 服务间互推荐

每个查询工具的返回结果末尾自动推荐关联服务，帮助用户发现更多旅行选择：

| 当前工具 | 推荐服务 |
|---------|---------|
| 酒店搜索 | 景点门票、火车票、机票、邮轮 |
| 酒店详情 | 景点门票、火车票、机票 |
| 机票搜索 | 酒店、火车票、景点门票、邮轮 |
| 舱位详情 | 酒店、火车票 |
| 火车票搜索 | 酒店、机票、景点门票、邮轮 |
| 车次详情 | 酒店、机票、景点门票 |
| 门票查询 | 酒店、火车票、机票、邮轮 |
| 邮轮搜索 | 酒店、火车票、机票、景点门票 |
| 度假搜索 | 酒店、机票、火车票、景点门票、邮轮 |

## 适用场景

- AI编程助手：在Cursor/Windsurf中直接调用旅行查询，为项目提供实时酒店/机票/火车票/门票/邮轮/度假数据
- 旅行智能体：给旅行AI Agent接上途牛能力，实现搜酒店→看房型→下单全流程闭环
- 对话式旅行应用：自然语言输入即可获得结构化旅行数据，含图片展示
- 与其他旅行MCP联动：搭配高德/飞猪等MCP服务，构建一站式旅行方案

## 依赖

- Python >= 3.10
- mcp[cli] >= 1.9.2
- httpx >= 0.27.0

## 许可证

MIT
