Metadata-Version: 2.1
Name: mcp-tuniu-travel
Version: 2.0.1
Summary: 途牛旅行助手MCP Server v2.0.0 — 17个工具覆盖酒店/机票/火车票/景点门票/邮轮/度假全品类，全量camelCase，结构化返回，基于MCPServer(mcp 2.x)构建
Author: mako2026
License: MIT
Keywords: tuniu,travel,hotel,flight,train,ticket,cruise,holiday,mcp,途牛,旅行,酒店,机票,火车票,门票,邮轮,度假
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Other/Nonlisted Topic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp (>=2.0.0)
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: pydantic (>=2.0)
Provides-Extra: dev
Requires-Dist: pytest (>=8.0) ; extra == 'dev'
Requires-Dist: pytest-asyncio (>=0.23) ; extra == 'dev'

# 🧳 途牛旅行助手 MCP Server v2.0.0

途牛旅行助手MCP Server — 17个工具覆盖酒店/机票/火车票/景点门票/邮轮/度假全品类查询预订，途牛API实时数据直连，零配置即装即用。

v2.0.0 全面升级：MCPServer框架 + 全量camelCase + 结构化返回，对齐魔搭MCP代码标准规范。

## ✨ 核心特性

▸ **全品类覆盖** — 酒店/机票/火车票/景点门票/邮轮/度假 6大品类17个工具
▸ **MCPServer框架** — 基于mcp 2.x的MCPServer，兼容所有主流MCP客户端
▸ **全量camelCase** — 工具名、参数名统一camelCase命名规范
▸ **结构化返回** — 所有工具返回status/message/data三层JSON结构，便于AI Agent解析
▸ **实时数据直连** — 途牛旅行API实时返回，价格、余票、房态均为最新数据
▸ **完整预订链路** — 搜索→详情→下单→取消，每个品类都支持完整的预订流程
▸ **安全代理架构** — 腾讯云SCF代理+SSL证书验证+域名白名单，数据传输安全可靠
▸ **环境变量兼容** — 空字符串自动回退默认值，兼容魔搭等部署平台

## 🚀 快速开始

```bash
pip install mcp-tuniu-travel==2.0.0
```

### 运行

```bash
mcp-tuniu-travel
```

### 环境变量（可选）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PROXY_URL` | 途牛SCF代理地址 | `https://1439498936-0junm3maxj.ap-guangzhou.tencentscf.com` |
| `PROXY_TOKEN` | 代理认证Token | `tp_8k2mX9vQ4z` |
| `TIMEOUT` | 请求超时时间（秒） | `120` |

## 🛠 工具清单（17个）

### 🏨 酒店类（3个）

| 工具名 | 说明 |
|--------|------|
| `hotelSearch` | 按城市和日期搜索酒店，支持关键词、商圈筛选和翻页 |
| `hotelDetail` | 查看酒店房型和报价，返回preBookParam用于下单 |
| `hotelCreateOrder` | 基于hotelDetail返回的preBookParam预订酒店 |

### ✈️ 机票类（5个）

| 工具名 | 说明 |
|--------|------|
| `flightSearch` | 按出发/到达城市和日期搜索航班，支持单程/往返 |
| `flightCabinDetail` | 查看航班各舱位价格和退改规则 |
| `flightBookingInfo` | 获取下单时必填字段说明和乘客信息格式要求 |
| `flightSaveOrder` | 基于舱位详情的cabinPriceId预订机票 |
| `flightCancelOrder` | 取消已创建的机票订单 |

### 🚄 火车票类（5个）

| 工具名 | 说明 |
|--------|------|
| `trainSearch` | 按出发/到达城市和日期搜索车次，支持6种排序方式 |
| `trainDetail` | 查看座位余票和价格，返回resId用于预订 |
| `trainBook` | 基于车次详情的resId预订火车票 |
| `trainOrderDetail` | 查看已创建的火车票订单详情 |
| `trainCancelOrder` | 取消已创建的火车票订单 |

### 🎫 门票类（2个）

| 工具名 | 说明 |
|--------|------|
| `ticketQuery` | 按景点名称搜索门票价格和票种信息 |
| `ticketCreateOrder` | 基于门票查询的productId和resourceId预订景点门票 |

### 🚢 邮轮类（1个）

| 工具名 | 说明 |
|--------|------|
| `cruiseSearch` | 按日期范围和航线搜索邮轮产品 |

### 🏖 度假类（1个）

| 工具名 | 说明 |
|--------|------|
| `holidaySearch` | 搜索跟团游、自由行等度假产品 |

## 📋 返回格式

所有工具均返回结构化JSON，统一格式：

```json
{
  "status": "ok",
  "message": "描述信息",
  "data": { ... }
}
```

错误时返回：

```json
{
  "status": "error",
  "message": "错误信息",
  "data": { ... }
}
```

## 📝 使用示例

▸ "上海6月20到22日的酒店" → hotelSearch搜索酒店列表
▸ "这个酒店有什么房型" → hotelDetail查看房型报价
▸ "北京到上海6月20日的机票" → flightSearch搜索航班
▸ "MU5101航班的舱位价格" → flightCabinDetail查看舱位详情
▸ "上海到北京6月20日的高铁" → trainSearch搜索车次
▸ "故宫门票多少钱" → ticketQuery查询景点门票
▸ "去日本的邮轮" → cruiseSearch搜索邮轮产品
▸ "三亚5日游" → holidaySearch搜索度假产品

## 📦 版本对比

| 特性 | v1.1.0 | v2.0.0 |
|------|--------|--------|
| 框架 | FastMCP (mcp 1.x) | MCPServer (mcp 2.x) |
| 工具命名 | snake_case + camelCase混合 | 全量camelCase |
| 返回格式 | 纯文本Markdown | 结构化JSON |
| 函数类型 | 同步def | 异步async def |
| 环境变量 | os.environ.get | _get_env空串过滤 |
| 入口点 | 包级 | 包级（更规范） |
| 构建后端 | hatchling | setuptools |

## 适用场景

- AI编程助手：在Cursor/Windsurf中直接调用旅行查询
- 旅行智能体：给旅行AI Agent接上途牛能力
- 对话式旅行应用：自然语言输入即可获得结构化数据
- 与其他旅行MCP联动：搭配高德/飞猪等MCP服务

## License

MIT
