Voyagier

@voyagier/cli

在终端中规划、估价并预订真实旅程。所有内容都会同步到 voyagier.com。

该 CLI 是 Voyagier MCP 服务的命令行入口：每个工具对应一条命令。 每条行程规划命令都是一个 MCP 工具——voyagier <tool_name> --<param> <value>——运行时根据服务在 https://mcp.voyagier.com/api/mcp 提供的工具列表生成。这些工具也为 claude.ai、Claude Desktop 和其他所有 MCP 客户端提供支持，因此每个操作都只有一个实现，而且服务上发布的工具无需升级就会出现在终端中。对于只支持 stdio 的宿主，voyagier mcp 是同一服务的代理。

npm install -g voyagier             # or the canonical package: @voyagier/cli
voyagier auth login                 # browser flow; keeps the token out of shell history
voyagier doctor                     # credentials, MCP connection, tool count, version
voyagier mcp install claude-code    # point an MCP client at the hosted server (also: cursor, claude-desktop)
voyagier update                     # later: bring a global install to the latest release

voyagier 是一个便捷别名，会跟踪最新的兼容 @voyagier/cli 版本。要固定到某个确切版本？请使用规范包：npm install -g @voyagier/cli@<version>。

没有安装权限（例如在沙箱中运行的 Agent 或 CI）？所有命令都可以通过 npx 零安装运行：

VOYAGIER_TOKEN=<your-token> npx @voyagier/cli doctor --json

快速开始

行程计划是一个目标图：计划包含各项目标（航班、酒店、日期、目的地、旅客），你可以通过探索库存、将搜索结果关联到目标并选择选项来组合行程。搜索是异步的——持续轮询，直到状态进入终止状态。

# 1) Find or create the client
voyagier list_clients --query "Doe" --json
voyagier create_client --name "Doe Family" --client_type Individual --email "[email protected]" --json

# 2) Resolve the destination, then scaffold the plan with its party
voyagier search_destinations --query "Lisbon" --json
voyagier create_plan --client_id <CLIENT_ID> --title "Doe — Lisbon" \
  --travel_destination_id <DESTINATION_ID> --start_date 2026-11-20 --end_date 2026-11-27 \
  --travellers '[{"first_name":"Jane","last_name":"Doe","type":"Adult"}]' --json

# 3) Explore flights (no plan is touched), poll, then promote the result onto the plan's goal
voyagier search_flights --from BWI --to LIS --date 2026-11-20 --return 2026-11-27
voyagier get_search_status --search_id <SEARCH_ID>
voyagier promote_search --plan_id <PLAN_ID> --search_id <SEARCH_ID> --goal_id <GOAL_ID> --json

# 4) Options → pick
voyagier get_options --selection_id <SELECTION_ID>
voyagier select_option --option_id <OPTION_ID> --json

# 5) Readiness, quote, book at exactly the quoted price
voyagier get_plan_status --plan_id <PLAN_ID>
voyagier get_plan_quote --plan_id <PLAN_ID>
voyagier book_plan --plan_id <PLAN_ID> --expect_total_cents <CENTS> --item_ids <ID> <ID> --json

# Not sure which tool? Ask the server.
voyagier search_tools --query "hotel dates" --json
voyagier get_tool_details --name set_hotel_dates --json

voyagier <tool_name> --help 会输出服务对该工具的说明，并为每个输入提供一个标志，列出类型和是否必填。

命令界面的工作方式

• voyagier --help 会列出本地命令，以及服务器发布的每个工具对应的一个命令。
• 标志与工具的输入架构一致。 plan_id 对应 --plan_id；必填输入必须通过必填标志提供。字符串、整数、数字、布尔值（--force / --force false）、枚举（允许的值列在 --help 中）、数组（--item_ids a b，或重复使用该标志），以及对象的 JSON 字面值（--travellers '[…]'；--help 会列出对象的键、必填键会加星号，并附上类型和说明）。架构允许为 null 的标志（在 --help 中标记为 (pass null to clear)）也接受字面值 null，并会以 JSON null 发送：voyagier update_plan --plan_id <id> --cover_media_id null 会清除封面照片。每个可重复的数组标志都有一个对应的 --no-<flag> 标志，用于发送空列表 []——这是工具定义了相关行为时，服务器提供的“传入空列表以清除”方式：voyagier get_search_status --search_id <id> --no-airlines 会读取已清除航空公司筛选条件的已存储搜索。属性或项目架构若通过本地 $ref 引用工具自身的架构，会在确定标志类型前解析，因此其行为与目标架构一致。
• 输出。 --json 会以 JSON 格式打印工具结果：直接输出负载对象，不带包装键。不使用该标志时，get_plan_status、search_flights / search_hotels / search_activities / get_search_status / promote_search、get_options、get_plan_itinerary 和 get_plan_quote 会以精简的人类可读形式呈现；其他所有工具（包括 search_destinations、search_tools 和 refresh_options）都会美化打印 JSON。
• 错误统一使用以下封装格式：{ "error": true, "code", "message", "details"? }，退出码为 1。错误类型包括 AUTH_FAILED、PERMISSION_DENIED、RATE_LIMITED（包含 details.retryAfterSeconds）、VALIDATION、API_ERROR（工具自身的错误文本）、NETWORK、COMMAND_REMOVED。
• 工具缓存。 服务器的工具列表会在 ~/.voyagier/tools-cache.json 中缓存 24 小时。voyagier doctor 会刷新缓存，运行缓存中尚未知晓的工具名称也会刷新缓存。doctor 和 --verbose 会报告工具界面（名称 + 输入架构）的稳定哈希，以便脚本检测契约变更。
• Agent 基础设施。 非交互式；使用 --json 时，stdout 只包含一份 JSON 文档（诊断信息、旋转动画和警告会发送到 stderr）；退出码稳定（0 / 1 已处理 / 2 意外）；呈现的输出使用绝对时间戳。

命令

命令	说明
voyagier <tool_name>	每个 MCP 工具对应一个命令，例如 list_plans、search_destinations、create_plan、search_flights、promote_search、get_options、select_option、get_plan_status、get_plan_quote、book_plan。voyagier --help 会列出服务器当前提供的命令；可在 CLI 中使用 search_tools 和 get_tool_details 查找并了解工具
voyagier doctor	自检：凭据、MCP 服务连接 + 工具列表、身份、状态、版本
voyagier update	将全局 npm 安装更新到最新版本（别名为 upgrade；--check 仅报告而不安装，--json 供脚本使用）
voyagier auth	管理 Personal Access Token（login、set-token、status、logout、setup）
voyagier mcp install <client>	将 MCP 客户端（Claude Code、Cursor、Claude Desktop）连接到 Voyagier MCP 服务
voyagier mcp	运行一个 stdio MCP 服务，代理托管的 Voyagier MCP 服务
voyagier agent-docs	打印服务器的 Agent 指南，然后打印 CLI 使用说明（AGENT.md）
voyagier telemetry	匿名使用情况遥测（status、on、off）

所有 3.x 行程规划命令（plan-trip、search flights、select、plans …、clients … 等）都已由工具取代。运行这些命令会打印替代方案并以退出码 1 退出；完整表格见 CHANGELOG。

面向 AI Agent

voyagier agent-docs            # the MCP server's guidance, then the CLI usage notes (AGENT.md)
npx @voyagier/cli agent-docs   # zero-install variant

第一部分是服务端自身的 instructions（旅行规划指南：工具调用顺序、搜索如何完成、预订如何设置门槛），每个 MCP 客户端收到的都是相同文本。第二部分是 AGENT.md：工具模型、标志类型、JSON 结构、错误代码表和 3.x 迁移说明。

连接 AI Agent

Voyagier 在 https://mcp.voyagier.com/api/mcp 上运行托管 MCP 服务。这是 AI Agent 和助手使用 Voyagier 的推荐方式：客户端使用你的个人访问令牌通过 HTTP 连接，即可使用完整的工具集，无需管理本地安装。CLI 本身提供相同的工具集，可用于命令行工作流、脚本和 CI。

voyagier mcp install <client> 可一步完成设置：

voyagier mcp install claude-code      # writes ./.mcp.json (--global writes ~/.claude.json)
voyagier mcp install cursor           # writes ~/.cursor/mcp.json (--project writes ./.cursor/mcp.json)
voyagier mcp install claude-desktop   # writes claude_desktop_config.json

该命令会使用你保存的令牌（voyagier login），将 voyagier 条目合并到客户端现有配置中，并保留文件中的所有其他服务。传入 --dry-run 可在写入任何内容前查看解析后的路径和确切条目；传入 --token <pat> 可安装指定令牌。所有输出中的令牌都会被屏蔽，并且只会写入配置文件。之后重启客户端以应用更改。

Claude Desktop 的配置格式仅支持 stdio 服务，因此该客户端会指向 CLI 的本地服务（voyagier mcp）。也可以通过应用设置中的远程连接器部分添加 Voyagier，该方式会直接使用托管端点。

Stdio MCP 代理

对于只支持 stdio 的主机，CLI 提供了一个 MCP stdio 服务，用作托管服务的代理：

voyagier mcp          # stdio proxy (JSON-RPC on stdout)

该代理没有自己的工具表。tools/list 和 tools/call 会被转发到 https://mcp.voyagier.com/api/mcp（或 VOYAGIER_MCP_URL），并使用 VOYAGIER_TOKEN 中的令牌或已保存的凭据；结果会按服务端返回的原样传回，因此代理始终会公开服务端当前的工具。服务端的 instructions 会在 initialize 时传递。当无法连接服务端时，代理仍会完成本地握手，并在 instructions 中说明问题；之后每个请求都会返回 JSON-RPC 错误，指出解决方法（401 时设置 VOYAGIER_TOKEN，429 时等待 Retry-After），并重试连接服务端，因此修复环境变量后无需重启。只要客户端支持远程 MCP 服务，就优先直接使用托管端点。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "voyagier": {
      "command": "npx",
      "args": ["-y", "@voyagier/cli", "mcp"],
      "env": { "VOYAGIER_TOKEN": "voy_pat_xxxxx" }
    }
  }
}

环境变量

变量	描述
VOYAGIER_TOKEN	个人访问令牌（覆盖已保存的令牌）
VOYAGIER_MCP_URL	所有工具命令、stdio 代理和扩展使用的 MCP 端点（默认值：https://mcp.voyagier.com/api/mcp）。必须使用 https://；仅在本地开发期间，localhost / 127.0.0.1 / ::1 才接受普通 http://
VOYAGIER_API_URL	voyagier auth setup 更新配置文件时使用的 GraphQL 基础 URL（默认值：https://travel.voyagier.com/api）；与 VOYAGIER_TOKEN 配合使用
VOYAGIER_CONFIG_DIR	凭据和工具缓存目录（默认值：~/.voyagier）

工作原理

CLI 是一个 MCP 客户端。启动时，它会加载服务端的 tools/list（如果本地缓存仍然有效，则从缓存加载），并为每个工具注册一个 Commander 命令，命令标志根据各工具的 JSON 输入架构生成。运行命令时，会通过 Streamable HTTP 发送 tools/call，并在 Bearer 标头中携带你的令牌；CLI 会遵循服务端的会话和速率限制标头，并打印结果。操作顺序、搜索完成方式以及预订的门控规则均由服务端决定；请使用 voyagier agent-docs 查看相关规则，并查看每个工具的 --help。

**速率限制。**托管端点每个令牌每分钟允许 180 个请求，CLI、stdio 代理以及使用该令牌的其他客户端的请求都会计入其中。脚本循环应采用退避策略；当服务端发送 Retry-After 时，CLI 会报告 RATE_LIMITED，并提供 details.retryAfterSeconds。

获取访问权限

Voyagier 访问权限需要申请，不开放自行注册——请通过 voyagier.com/agents 申请访问权限。顾问、行程规划客户和 Agent 开发者都需要通过此流程获取权限。

账户获批 API 访问权限后，请前往 travel.voyagier.com/me/settings/tokens 创建个人访问令牌，即可开始使用。目前有两种账户类型可以使用 CLI：

• 旅行顾问 — 管理一组客户（list_clients、create_client）；计划需针对某位客户创建（create_plan --client_id <CLIENT_ID>）。
• 行程规划者 — 为自己规划旅行的客户。省略 --client_id：create_plan 会自动将计划关联到你自己的客户记录（即 list_clients 返回的 isSelf: true 条目）。

非管理员令牌会过期（最长 90 天，默认 30 天）——令牌过期后请重新创建。

**提示：**建议使用 voyagier login（交互式提示），而不是 voyagier auth set-token <token>，这样令牌不会留在 shell 历史记录中。对于脚本，可通过标准输入传递令牌（echo "$VOYAGIER_PAT" | voyagier auth set-token -），或使用 VOYAGIER_TOKEN 环境变量。

Claude Desktop 扩展（MCPB）

stdio 代理也打包为 Claude Desktop 扩展包（MCPB）：该扩展使用你安装时输入的个人访问令牌，将 Claude Desktop 连接到托管的 Voyagier MCP 服务，并始终提供服务端当前的工具。可在代码库中使用 scripts/build-mcpb.sh 构建，生成 dist-mcpb/voyagier-<version>.mcpb。安装时，将 .mcpb 文件拖入 Claude Desktop → Settings → Extensions，然后按提示输入令牌。

隐私政策

通过 CLI 和 Voyagier 服务处理的数据，均按照 Voyagier 隐私政策处理。

许可证

Apache-2.0 — 版权所有 2026 Voyagier, Inc. 通过 CLI 使用 Voyagier 服务须遵守 Voyagier 服务条款。“Voyagier”及 Voyagier 徽标是 Voyagier, Inc. 的商标；Apache-2.0 许可证不授予商标权。