途牛 MCP CLI

途牛 CLI 操作指南

概述

途牛 CLI 是将 途牛开放平台 提供的旅行服务封装而成的命令行工具，支持通过 Shell 命令调用门票、酒店、机票、火车票、邮轮、度假产品等相关能力，适用于 AI Agent 集成、自动化脚本及本地调试场景。

快速开始

如果你是第一次接触这个项目，推荐先走这 4 步：

# 1) 安装
npm install -g tuniu-cli@latest

# 2) 配置 API Key
export TUNIU_API_KEY=your_api_key

# 3) 看看有哪些服务
tuniu list

# 4) 试一次真实调用
tuniu call ticket query_cheapest_tickets -a '{"scenic_name":"中山陵"}'

如果你更偏向临时使用或在 CI 中调用，也可以直接：

npx tuniu-cli list

常见上手入口：

• 查看所有服务：tuniu list
• 查看某个服务的工具：tuniu list ticket
• 导出 Schema 给 Agent 初始化：tuniu schema --output json
• 安装/更新 Skill：tuniu skill install

术语约定：

• 命令（command）：tuniu 的一级能力入口，如 list、call、schema
• 服务（server）：业务域标识，如 ticket、hotel、flight、train、cruise、holiday
• 工具（tool）：服务下可调用的方法，如 query_cheapest_tickets、searchCruiseList、searchHolidayList
• 工具输入参数（args）：通过 -a/--args 传入的 JSON 字符串
• Schema：工具能力定义（包含工具列表、参数结构、必填项）
• Skill：本文提到的 Skill 均指 tuniu-cli 对应的 SKILL.md

核心特性：

• 🚀 统一入口：使用同一套命令（list/call/health/schema）调用不同业务服务，减少“每个服务一套 SDK/调用方式”的维护成本，便于 Agent 和自动化脚本快速复用。
• 🔐 API Key 认证：通过环境变量 TUNIU_API_KEY 注入凭证，避免在代码中硬编码密钥，降低泄露风险；同时便于在本地、CI、容器环境统一管理认证。
• 📦 标准协议：底层兼容 JSON-RPC 2.0，输出支持 JSON / Table / YAML；其中 JSON 统一输出适合 LLM/Agent 解析，Table 适合人工排查，兼顾“机器可读 + 人可读”。
• 🤖 支持 AI Agent 动态集成：可通过 tuniu schema --output json 动态获取工具能力，通过 tuniu discovery 子命令刷新/查看服务状态，帮助 Agent 在运行时适配新增服务。
• 🧩 支持 Skill 分发与安装：内置 SKILL.md 会在 npm 安装时自动检测并安装到现存的 Agent 目录，一键完成 Skill 注册；也可通过 tuniu skill install 显式安装/更新。
• 🐳 安装便捷灵活：支持 npm install -g、npx 安装，适合个人开发、团队协作和生产部署场景。

---

一、安装 CLI

1.1 前置条件

条件	说明
运行环境	Node.js 18+
API Key	调用途牛服务前需配置 TUNIU_API_KEY，从 途牛开放平台 注册登录后申请
网络	需能访问途牛服务端点（如 https://openapi.tuniu.cn/mcp/hotel）

1.2 安装方式

方式一：npm 全局安装（推荐）

npm install -g tuniu-cli@latest

若提示需要 sudo 权限，则使用下列命令进行安装：

sudo npm install -g tuniu-cli@latest

安装后，可使用下列命令验证安装是否成功：

tuniu --version

若输出类似 tuniu version 1.0.0，则说明安装成功。

方式二：npx 临时使用

无需全局安装，直接执行：

npx tuniu-cli --version
npx tuniu-cli list

适合一次性使用或 CI 环境中临时调用。

方式三：从源码安装

git clone https://github.com/tuniucorp/tuniu-cli.git
cd tuniu-cli
npm install
sudo npm link

1.3 安装 Skill 到 Agent 目录（可选）

注意：安装 CLI 与 Skill 注册是两条路径：

• 通过 npm 安装时，postinstall 会自动检测本机已安装的 Agent（例如 ~/.claude/、~/.cursor/ 等），并将内置 Skill 安装到对应目录；若未检测到任何 Agent，则默认 ~/.agents/skills/tuniu-cli/。
• 通过 CLI 命令注册 Skill 时，可用 tuniu skill install 显式安装/更新 Skill（更可控，适合 CI、容器或多 Agent 环境）。

如果希望显式安装/更新 Skill（不依赖 npm 自动检测），可执行：

tuniu skill install

该命令默认仅安装到：

• ~/.agents/skills/tuniu-cli/

也支持以下用法：

# 位置参数：单个 Agent（更简洁）
tuniu skill install claude

# 选项参数：多个 Agent（逗号分隔）或 all
tuniu skill install --agent cursor,claude
tuniu skill install --agent all

# 自定义目录
tuniu skill install --dir ~/.custom-agent/skills

---

二、配置 CLI

调用途牛服务需要配置 API Key。若您未注册使用过途牛服务，可前往 途牛开放平台 注册并登录账号，在控制台申请 API Key。将 API Key 配置到环境变量 TUNIU_API_KEY 中即可使用完整服务。可配置环境变量示例如下：

变量	说明	示例
TUNIU_API_KEY	API 认证密钥	export TUNIU_API_KEY=your_api_key
MCP_TIMEOUT	请求超时秒数，可选	30
TUNIU_DISCOVERY_ENABLED	途牛服务动态发现开关（true 开启，false 关闭）	export TUNIU_DISCOVERY_ENABLED=true

---

三、使用 CLI

3.1 快速入门（3 步上手）

以门票查询 CLI 为例：

# ① 查看有哪些服务
tuniu list

# ② 查看门票服务下的工具列表
tuniu list ticket

# ③ 查询景点门票
tuniu call ticket query_cheapest_tickets -a '{"scenic_name": "中山陵"}'

3.2 命令分类速查

类型	命令	说明
🔍 查询	tuniu list	列出所有可用的服务（ticket、hotel、flight、train、cruise、holiday 等）
	tuniu list <server>	列出指定服务下的工具清单及简介，如 tuniu list ticket 可查看门票相关工具
	tuniu health	检查服务连通性与健康状态，支持指定服务或并行检查全部
🧭 服务发现	tuniu discovery status	查看服务发现启用状态、Discovery URL 及缓存状态
	tuniu discovery list	从 Discovery 获取当前可用服务列表（失败时会自动回退静态配置/缓存）
	tuniu discovery refresh	强制刷新 Discovery 缓存
🚀 调用	tuniu call <server> <tool> -a '<JSON>'	调用指定服务的工具，详见下方 3.3
⚙️ 配置	tuniu config init	初始化配置文件，在默认路径生成配置文件 ~/.tuniu-mcp/config.json
	tuniu config show	查看当前加载的配置内容
🧩 Skill	tuniu skill install	将内置 SKILL.md 安装到 Agent 可识别目录
ℹ️ 帮助	tuniu help	查看 CLI 使用帮助
	tuniu help <server> <tool>	查看指定工具的功能说明与参数详情
🔧 调试	tuniu call ... -d	调试模式，打印完整请求/响应
	tuniu schema --output json	导出所有工具的能力定义（Schema），供 Agent 或自动化脚本初始化时使用

3.3 调用工具（核心用法）

tuniu call 集成了调用多种途牛服务的功能，命令格式如下：

tuniu call <server> <tool> --args '<JSON>'
# 或简写
tuniu call <server> <tool> -a '<JSON>'

参数	说明
server	服务名称，如 ticket（门票）、hotel（酒店）、flight（机票）、train（火车票）、cruise（邮轮）、holiday（度假产品）
tool	工具名称，如 query_cheapest_tickets、tuniu_hotel_search、searchHolidayList 等
--args 或 -a	工具的输入参数，必须是合法的 JSON 字符串

⚠️ 参数注意事项：

• --args 的值必须是 JSON 格式，且用引号包裹，避免 Shell 解析错误
• 中文可直接写入 JSON 中，无需转义
• 无参数时用空对象：-a '{}'

常用服务速查

服务	功能	可用工具	详细说明
ticket	景点门票查询与预订，支持查询票型价格并在线下单	query_cheapest_tickets（门票查询） create_ticket_order（创建订单）	门票服务
hotel	酒店搜索、详情查询与在线预订，支持城市/日期/关键词筛选	tuniu_hotel_search（酒店搜索） tuniu_hotel_detail（酒店详情） tuniu_hotel_create_order（创建订单）	酒店服务
flight	国内航班搜索与预订，支持低价/时段/价格区间等 6 种查询模式	searchLowestPriceFlight（航班搜索） multiCabinDetails（舱位查询） getBookingRequiredInfo（预订信息） saveOrder（创建订单） cancelOrder（取消订单）	机票服务
train	火车票车次查询与预订，支持搜索车次列表并在线下单	searchLowestPriceTrain（查询车次） queryTrainDetail（车次详情） bookTrain（预订下单） queryTrainOrderDetail（订单详情） cancelOrder（取消订单）	火车票服务
cruise	邮轮产品搜索与预订，支持按日期/航线/品牌筛选，兼容"游轮"说法	searchCruiseList（邮轮搜索） getCruiseProductDetail（产品详情） getCruiseBookingRequiredInfo（预订信息） saveCruiseOrder（创建订单）	邮轮服务
holiday	度假产品搜索与预订，支持目的地/出游日期/品类筛选，兼容跟团、自助游、自驾游、当地游等表述	searchHolidayList（度假列表搜索） getHolidayProductDetail（产品详情与团期日历） getHolidayBookingRequiredInfo（预订说明） saveHolidayOrder（创建订单）	度假服务

建议：Agent 在运行前先执行 tuniu schema --output json 获取最新工具参数定义；当服务侧新增/变更工具时，可配合 tuniu discovery refresh 做动态更新。

3.4 场景示例：

🎫 门票完整预订流程

以"查询中山陵门票并下单"为例，展示从查询到下单的完整流程。其他服务（酒店、机票、火车票、邮轮、度假产品）的完整流程请参考上方表格中各服务文档。

第一步：查询景点门票

tuniu call ticket query_cheapest_tickets -a '{"scenic_name": "中山陵"}'

返回门票列表，记录结果中的 productId 和 resId（下单时必需）：

{
  "scenic_name": "南京中山陵",
  "tickets": [
    { "productId": 12345, "resId": "res001", "price": "50", "ticketType": "成人票" }
  ]
}

第二步：创建订单

将上一步获取的 productId（对应 product_id）和 resId（对应 resource_id）传入下单：

tuniu call ticket create_ticket_order -a '{
  "product_id": 12345,
  "resource_id": "res001",
  "depart_date": "2026-04-01",
  "adult_num": 1,
  "contact_name": "张三",
  "contact_mobile": "***********",
  "tourist_1_name": "张三",
  "tourist_1_mobile": "***********",
  "tourist_1_cert_type": "身份证",
  "tourist_1_cert_no": "*****************"
}'

返回订单号与支付链接：

{
  "success": true,
  "orderId": "ORD2026040100001",
  "paymentUrl": "https://m.tuniu.com/u/gt/order/ORD2026040100001?orderType=75",
  "message": "订单创建成功"
}

⚠️ 下单成功后请将 paymentUrl 发给用户，提醒用户点击链接完成支付。

3.5 全局选项

可在命令后添加以下选项：

选项	短选项	说明	示例
--detail	-d	调试模式，打印完整请求/响应	tuniu call ... -d
--output	-o	输出格式：json/table/yaml	tuniu list -o table
--profile	-p	环境配置（默认 production）	tuniu list -p development
--config	-c	指定配置文件路径	tuniu config show -c ./config.json
--timeout	-t	设置请求超时时间（秒）	tuniu call ... -t 60
--version	-V	显示版本号	tuniu -V

---

四、常见问题

Q1: 如何获取 API Key？

前往 途牛开放平台 注册并登录账号，获取 API Key。具体流程可参考平台文档或联系项目负责人。

Q2: 提示「未配置 API Key」怎么办？

确保已设置环境变量：export TUNIU_API_KEY=your_api_key。若使用配置文件，需确保其中占位符为 ${TUNIU_API_KEY}，与代码中的变量名一致。可执行 tuniu config init --force 重新初始化配置。

Q3: 如何更换 API Key？

# 将环境变量 TUNIU_API_KEY 覆盖为新的 API Key
export TUNIU_API_KEY=your_new_api_key

Q4: 如何查看工具参数说明？

以查询门票工具参数为例：

tuniu help ticket query_cheapest_tickets

响应如下：

query_cheapest_tickets
描述: 查询指定景点的门票详情信息，包括门票的类型和价格等
参数:
  scenic_name (必填): string - 

Q5: 如何做 dry-run 测试？

tuniu call ticket query_cheapest_tickets --args '{"scenic_name":"上海迪士尼"}' --dry-run

Q6: 退出码含义？

退出码	含义
0	成功
101	连接失败
102	工具不存在
103	参数错误
104	认证失败
105	超时
106	服务器错误
107	配置错误
108	未配置 API Key（需设置 TUNIU_API_KEY）
199	未知错误

Q7: 如何让 AI Agent 使用途牛 CLI？

推荐按“准备环境 → 初始化能力 → 动态发现 → 注册 Skill → 工具调用”五步接入：

1. 准备运行环境

• 安装 CLI：npm install -g tuniu-cli
• 配置 API Key：export TUNIU_API_KEY=your_api_key

2. 初始化工具能力

• 执行：tuniu schema --output json
• 作用：让 Agent 获取最新工具列表、参数结构、必填项，用于意图路由和参数补全。

3. 开启动态集成能力（可选但推荐）

• 执行：tuniu discovery refresh（刷新服务列表）
• 执行：tuniu discovery status / tuniu discovery list（查看发现状态与服务清单）
• 作用：当平台新增服务或工具时，Agent 能在不改代码的情况下更新可用能力。

4. 可选：注册 Skill

• 执行：tuniu skill install
• 默认行为：仅安装到 ~/.agents/skills/tuniu-cli/。
• 如需安装到指定 Agent / 多个 Agent：tuniu skill install cursor 或 tuniu skill install --agent cursor,claude
• 如需安装到全部内置支持的 Agent：tuniu skill install --agent all
• 说明：对于未内置适配的 Agent，请使用 tuniu skill install --dir <path> 安装到目标 Agent 的技能目录。

5. 运行时调用工具

通过 Python subprocess 示例调用 CLI：

import subprocess, json

result = subprocess.run(
    ["tuniu", "call", "ticket", "query_cheapest_tickets",
     "-a", '{"scenic_name": "中山陵"}', "--output", "json"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

在任意 AI Agent 聊天窗口（如 Claude 终端），也可直接输入自然语言指令，Agent 会自动执行对应的 shell 命令：

"帮我用途牛命令行工具查这周六上海迪士尼的低价门票"

Q8: 如何卸载？

npm uninstall -g tuniu-cli

如需同时移除已安装的 Skill，请手动删除对应 Agent 目录下的 tuniu-cli 子目录。

贡献

许可证

MIT

联系我们

• Email: agent@tuniu.com

---

Made with ❤️ by Tuniu Team