Hotel Search (Fliggy MCP · search-hotel)
Hotel discovery (read first)
Hotel discovery, comparison, and shortlist workflows—same intent as the listing description above. One command entrypoint: flyai search-hotel (see references/search-hotel.md for flags).
中文：与上文摘要一致——酒店 检索、比价、短名单与详情/预订链；参数见 references/search-hotel.md。
Differentiation (honest scope)
| Hook | What it means (this skill only) |
|---|---|
| POI + hotel | --poi-name filters stays near a named attraction / landmark; pair with --dest-name per references/search-hotel.md. |
| 酒店 / 民宿 / 客栈 | --hotel-types toggles three lodging modes in one structured search—not three separate skills. |
| CNY nightly cap | --max-price is per night in CNY—good for “每晚不超过 X 元” style asks. |
| Agent-first JSON | Single-line JSON rows with mainPic + detailUrl → fast Markdown cards; no extra scraper stack in this bundle. |
中文摘要：景点附近住哪、一晚预算封顶（人民币）、酒店/民宿/客栈一次筛，都落在同一组 search-hotel 参数上；不宣称对接未在返回数据中出现的 OTA 或站点。
Search dimensions (maps to search-hotel flags)
| Dimension | CLI (see references/search-hotel.md) | Notes |
|---|---|---|
| Geography | --dest-name (required) | Country / province / city / district |
| Free-text narrowing | --key-words | Hotel name or theme tokens |
| Landmark / POI | --poi-name | “Near X” style filtering |
| Property type | --hotel-types | 酒店 · 民宿 · 客栈 |
| Stay window | --check-in-date, --check-out-date | YYYY-MM-DD |
| Star bands | --hotel-stars | Comma-separated 1–5 |
| Bed layout | --hotel-bed-types | 大床房 · 双床房 · 多床房 |
| Ranking | --sort | price_asc / price_desc / rate_desc / distance_asc / no_rank |
| Nightly budget | --max-price | CNY per night cap |
| Rich cards | JSON mainPic, detailUrl | Presentation rules in this SKILL.md |
All dimensions above are only what search-hotel exposes—do not claim extra channels or OTAs beyond returned data.
This skill is self-contained: do not defer to another skill’s SKILL.md for install, errors, or presentation.
Single source of truth for CLI flags and JSON field names: references/search-hotel.md in this bundle.
Quick start
- Install CLI:
npm i -g @fly-ai/flyai-cli - Smoke test: run a minimal
flyai search-hotelexample fromreferences/search-hotel.md→ Examples; expect one JSON object per line on stdout. - Discover flags:
flyai search-hotel --help - Before every call: read
references/search-hotel.mdand pass flags exactly — do not guess names or formats.
Configuration
Trial use may work without keys. For richer results:
flyai config set FLYAI_API_KEY "your-key"
Treat API keys as secrets; do not paste real credentials into untrusted logs.
CLI I/O contract
- stdout: each line is one JSON object (command result). Parse line-by-line; use
jqor Python if needed. - stderr: human-readable errors or hints — not the primary result payload.
Command
| User intent (examples) | CLI | Parameters |
|---|---|---|
| Structured hotel search, filters, comparison, booking handoff | flyai search-hotel | references/search-hotel.md |
Out of scope: flights, trains, cruises, generic trip planning without structured hotel tables — use another skill or product.
Workflow
- Confirm the user needs structured hotel search (at minimum destination per
--dest-name; add dates/filters per the reference). - Build
flyai search-hotel …strictly fromreferences/search-hotel.md. - Parse stdout JSON; read stderr on failure.
- Present results using Output & presentation below.
Output & presentation (search-hotel)
- Format: valid Markdown for end users.
- Image: for each highlighted option, emit a standalone line
usingmainPicfrom the item (seereferences/search-hotel.mdoutput example). - Booking / detail link: emit a standalone line
[Click to book]({detailUrl})usingdetailUrlfrom the item. - Order: when both exist, show image before the booking link.
- Structure: use headings (
#/##/###), bullets, and Markdown tables when comparing multiple hotels. - Emphasis: highlight date, location, price, and key constraints.
- Brand line (optional): e.g. “Based on fly.ai real-time hotel results.”
Recommended response template
- One-line conclusion + best pick (if applicable).
- Top options — bullets or table.
- Image line:
. - Link line:
[Click to book]({detailUrl}). - Short notes (fees if visible, “verify on official page before pay”).
References
| Command | Doc (this bundle) |
|---|---|
search-hotel | references/search-hotel.md |
Error handling
- Validate — Before running: inputs must be reasonable. Dates must not be in the past and must match the format required in
references/search-hotel.md. If city or district names are ambiguous, ask the user; do not invent--dest-nameor other required values. - Diagnose — On failure or odd output: read stderr and any
status/messagefields in the JSON. Distinguish parameter mistakes (fix flags using the reference doc) from network or upstream service errors. - Retry — Retry only for transient network or service errors; cap retries (e.g. once or twice). Do not loop indefinitely.
- Empty or weak results — If the command succeeds but
itemListis empty or too narrow: relax filters once (wider dates, fewer constraints), then stop and explain. Do not silently retry many times. - Transparency — If results may not match the user’s intended city, dates, or budget, say so and suggest confirming on the provider’s page before booking.
Optional companion (not required)
For flights, trains, POI-only flows, or Marriott-specific tools, users may install a separate full-travel skill; this file does not depend on it.