# viajante

Local Google Flights, Google Hotels, and Booking.com search (Skiplagged is opt-in). No API keys.
Fetch locale is English. User prompts may be any language. No implied home hub.

## Which path

- **MCP tools are listed.** You are connected. Read `status`, `completeness`, and `empty_reason` before the rows. Only `provider_empty` means none found. `get_guide` is the long rules. `get_runtime_info` is the running version.
- **Nothing installed, you have a shell.** Primary: `npx -y @viajante/mcp` (needs uv and Python 3.10+). No Node: `uvx --from viajante[mcp] viajante-mcp`. Config below. If `viajante-mcp` says it needs the mcp extra, you are not in a checkout: use the uvx line, not `uv sync` (`uv sync` does not put the binary on PATH).
- **CLI only** (`viajante` runs, no MCP tools). `viajante <cmd> --help`. `viajante --version` before a new flag. Hotels need `--currency`.
- **Python.** `from viajante import get_flights, search_flights, search_hotels, validate_itinerary`. A route spec, not a sentence. `search_hotels` defaults to Booking (browser extra); pass `source="google"` and `currency`. `get_hotel_details(report, query_index, offer_index)` is the library form; MCP takes `selection_id`.
- **No shell and no local process.** You cannot search. Loopback HTTP has no auth and is never hosted. `server.json` has no remotes. Do not invent a URL.

Check `get_runtime_info` or `viajante --version` before a new parameter. An npm MCP and a separate uv tool can differ; unpinned `uvx` can reuse an old install.

## Install (agents)

Requires [`uv`](https://docs.astral.sh/uv/) and Python 3.10+.

```json
{
  "mcpServers": {
    "viajante": {
      "command": "npx",
      "args": ["-y", "@viajante/mcp"]
    }
  }
}
```

`@viajante/mcp` runs the PyPI package at its own version, with the browser extra.
Sweep and Google Hotels need no Chromium. Detail scrape, Booking.com, and
`search_explore` need it, installed once from the same environment:

```bash
uvx --from 'viajante[mcp,browser]==<version>' playwright install chromium
```

No Node: `"command": "uvx", "args": ["--from", "viajante[mcp]", "viajante-mcp"]`
(no browser extra). Installing `viajante[browser]` elsewhere does not update the
uvx environment.

Other clients (Claude Desktop extension, Claude Code plugin, Codex, Gemini CLI, VS Code,
Zed, Goose, OpenCode, a container): `docs/clients.md`. Pairing with a calendar, a
spreadsheet or a currency server: `docs/composition.md`.

## Tools

Twenty-two tools.

Every result (except lookup_airports) opens with an envelope: status, completeness, empty_reason (provider_empty | filtered_out | not_loaded), retry_after, observed_at. Only provider_empty means "none found".

- search_flights: named routes and dates. A metro code (LON, NYC, PAR, TYO)
  expands to its member airports on one-way and round-trip routes. One metro
  call sends at most 18 provider queries; a larger plan is rejected before
  anything is fetched. A route whose ends are the same metro is rejected. One-way
  searches also take depart_before, arrive_after, less_emissions, and
  hide_separate_tickets; fetch auto or sweep sends the clock, duration, layover,
  price-cap, and these two options to the page, and the page must echo each one.
  exclude_basic_economy is refused on every path. A successful query carries `price_insight`
  when Google's page states a level (`low`, `typical`, or `high`) that matches its heading.
  That level is Google's comparison with its typical range, not a forecast. Quote the label.
  `include_price_history` (default false) adds the page's own history; no extra request.
  A heading that does not match leaves `price_insight` null and `price_insight_error`
  `markup_drift`; the search still succeeds. A successful query may carry `recommendation` (none when
  the provider returned nothing): a pick that respects named requirements
  (`relaxed_requirements` lists any it relaxed), a varied shortlist, and
  highlights/tradeoffs from returned fields only. Additive; `offers` unchanged.
  nearby_days (default 0, off) adds nearby_dates: cheapest fare ±N days around
  the requested date, delta against that date, cheapest on the lowest day. Round
  trips shift both dates and keep the length. Same public date calendar as
  search_dates, one batch per query. Multi-city omits it. An unpriced day is not
  "no flights".
- search_dates: cheapest-per-day calendar (cheapest week). Max 31 days.
- search_flex: ±N around one date, then one shop. Not a date matrix.
- search_explore: dest triage from a named origin. A metro code (MIL, NYC)
  runs one explore per member airport, sequentially, and keeps the cheapest
  fare per destination (`origin_airport`). A rate limit stops the rest. `top`
  above 30 is clamped to 30 and named in `warnings`. A month window still
  shops one date; an empty shop that day is `not_loaded` for that
  `shopped_date`, not `no_results` and not `provider_empty` for the month.
- search_hotels: total-stay prices. Currency required. Default source google.
- search_hotel_rooms: Skiplagged room rates for one named hotel, in USD.
- get_hotel_details: read a hotel offer this process returned. room_rates must
  be a boolean. true fetches a separate USD room quote and does not replace
  the original stay. A quote whose provider does not echo adults, rooms, and
  dates comes back partial. A read does not evict stored searches.
- search_trip: flights then hotels. Same currency. Default hotel source google.
- search_split_tickets: opt-in separately ticketed itineraries from real one-way quotes (hub self-transfer for a one-way route; mixed one-ways for trip=rt). Capped extra searches. Not protected: a missed connection between tickets is not rebooked, bags may need re-checking. Total is null across currencies; no FX.
- lookup_airports: offline city, IATA, or metro lookup. Does not pick a hub.
- recheck_offer: one fresh Google Flights search (never cached) that matches an earlier
  offer by flight numbers and departure times. Outcomes: same_price, price_changed,
  not_found, multiple_matches (no pick, no verdict), incomplete_identity (no search
  sent), check_failed, and substituted only with allow_substitute. check_failed
  (blocked, rate limited, incomplete offers, any provider error; check_completed false)
  means the check did not run to an answer, not that the offer is gone. allow_loose_match
  opts in to carrier plus times. A price_cap in the query is reported as
  filter_violations. currency must be the offer's own. Re-check finalists
  before presenting them as current. Not a booking guarantee; confirm the price on
  the provider's own page.
- search_hidden_city: Skiplagged, opt-in. Cards are USD; omit currency or pass USD. Do not copy a Google/origin quote keep (GBP, JPY, …).
- compare_awards: local award vs cash math. No live award seats.
- lookup_transfers: local transfer-partner table for a named program.
- validate_itinerary: local pass/fail/unknown check of selected offers.
  Pass legs in travel order. arrival_deadline compares the final arrival with a
  named instant (an explicit offset is UTC; a naive time is local at the arrival
  airport). chronological checks owned segment instants in that order.
  min_stay_days and max_stay_days use owned dates between journeys; one journey
  is unknown. Unknown never becomes pass.
- plan_stay_blocks: local grouping of consecutive nights with the same people.
- split_stay_costs: local per-person split of named stay totals. No FX.
- verify_answer: flags amounts, codes, dates, and links in a draft reply that no
  search in this process returned.
- price_history: local read of this machine's recorded observations (opt-in via
  VIAJANTE_PRICE_HISTORY=1). One series per exact query and currency: first/last/
  lowest/highest and change since previous. One observation means no trend. No
  forecast, no currency comparison.
- watch_price: re-run one saved search_flights/search_hotels query on demand and
  report the change vs its last observation. A flight run includes that search's
  `price_insight`. No notifications, no scheduler; do
  not loop it (Google rate-limits). Each run bypasses the replay cache for a fresh search
  under the search lock and provider cooldown. A failed, empty or rate-limited run records nothing.
- get_runtime_info: executing package, Python, and hotel schema versions. Offline.

- get_guide: the long operational guide (markdown); same text as the `viajante://guide` resource.

One search at a time in the MCP process. Every tool has a title and annotations;
open-world for the search tools, `recheck_offer`, `watch_price`, and `get_hotel_details`
(`room_rates` false still runs during a search). `watch_price` writes. Bad input fails the call with
JSON text `{"error": {"code": "invalid_parameter", "field": ..., "message": ...}}`
after the SDK's exact `Error executing tool <name>: ` prefix (`field` null when not provable). Needs `mcp>=2.3.0`.

A cancelled call frees the lock. `deadline_seconds` (flights, dates, flex, explore, hotels, trip, split tickets) returns a
partial result: `coverage.complete=false`, `coverage.stopping_reason="deadline"`,
unfinished queries `error.code="deadline"`. Not proof of no availability.

Local HTTP (opt-in, no auth): `viajante-mcp --transport streamable-http` serves
`http://127.0.0.1:8000/mcp`; client entry `{"mcpServers": {"viajante": {"url": "http://127.0.0.1:8000/mcp"}}}`.
A non-loopback `--host` warns: every client searches from this machine's IP and
shares its provider cooldown.

Rate limits: a Google HTTP 429, a data-less RPC status 13, or three public-page
status-13 error frames or Explore bodies with no `wrb.fr` payload inside 2 minutes,
pauses Google searches on this machine (error `rate_limited: true`; the message
names the UTC time to wait, and `retry_after` / `retry_after_seconds` repeat it
when a cooldown was recorded). One status-13 frame does not. That message says
Google Flights is likely blocking this shared IP because viajante is running in a
cloud-hosted agent or sandbox, and that it works much better on your own computer:
the ChatGPT or Claude desktop app with `npx -y @viajante/mcp`, or `pip install viajante`.
Tell the user to wait; do not retry. Identical successful
searches within 5 minutes return `cached: true` without a new request. The replay
cache holds at most 20 entries.

## Currency

Pass `currency` (ISO 4217) or infer from a named origin airport country
(JFK USD, LHR GBP, NRT JPY, GRU BRL). Hotels have no origin: currency is required.
Skiplagged hidden-city keep is USD/omit; other keeps are `currency_mismatch` (no FX).
Do not invent IATA, gl, or ISO 4217. Viajante does not convert.

## Bags

Unnamed baggage_buffer is 0. carry_on is cabin bags for the whole party (CLI
`--carry-on` means 1, `--carry-on N` sets N) and is verified on the page; checked
bags are refused before any request. Pass carry_on, not bags, then confirm bag
rules on the airline or Google Flights page.
Do not invent a bag fee. Read empty_note and completeness_note before telling a
traveller a search failed or came back empty.

## Python

```python
from viajante import get_flights, search_flights, SearchErrorCode, QueryFailure

report = get_flights("JFK-LHR:YYYY-MM-DD", fetch="sweep")
```

Sweep `proxy` covers flights, dates, flex, and explore. Hotels have no proxy flag.
Signatures: `src/viajante/mcp_handlers.py` (`mcp_server.py` copies them into the client schema). On `get_flights` / `search_flights`, airline filters are `alliances` and `exclude_alliances`. MCP and the CLI call those `alliance` and `exclude_alliance`.
