<div align="center">

🌍 Wander Agent

A travel planning AI with 66 tools, zero API keys required.

Ask your AI anything about travel — flights, hotels, visas, weather, safety, local food, packing lists — and get real data back, not hallucinations.

See the launch demo

</div>

---

What is this?

Wander Agent is a tool plugin for AI assistants (Claude, Cursor, Windsurf, etc.) that gives the AI real travel data to work with.

Without this plugin, asking an AI "cheapest flights from New York to Tokyo in August?" gets you a made-up answer. With this plugin, the AI calls real data sources — Google Flights, Open-Meteo, US State Dept advisories, OpenStreetMap — and gives you actual prices, real forecasts, and live visa requirements.

You talk to the AI the same way you always do. The AI does the rest.

"Plan me a 10-day trip to Bali for 2 people leaving from Dubai in September, budget $3,000" → Real flights, real hotels, visa requirements, weather forecast, local restaurants, packing list, day-by-day itinerary — all in one response.

---

What can it do?

<details> <summary><strong>✈️ Flights</strong></summary>

• Search live flights (Google Flights + Kiwi.com in parallel)
• Find hidden-city fares — e.g. buy NYC→Mexico via Houston, exit in Houston at 40% discount
• Split-ticket search — book two separate tickets via a hub; OTAs are contractually forbidden from showing you this
• Month-level price scan — check every month for the next year, returns cheapest month to fly
• Fare calendar — cheapest day within a given month, day-of-week analysis
• Scan for mistake fares and error pricing from deal alert sites
• Find the cheapest destination you can fly to from anywhere
• Find cheapest meeting point for friends flying from different cities
• Automatically checks nearby airports (JFK also checks EWR, LGA; DXB also checks SHJ, AUH)

</details>

<details> <summary><strong>🏨 Hotels</strong></summary>

• Search hotels with direct booking links to Booking.com, Airbnb, Expedia, Tripadvisor, and 6 more
• Optimize for cheapest flight + hotel combo across flexible dates

</details>

<details> <summary><strong>📋 Visas & Entry</strong></summary>

• Check if you need a visa, e-visa, ETA, or nothing at all
• See every country you can enter without a full visa
• Passport power ranking — Henley Index 2024 rank, visa-free %, regional breakdown
• Dual-passport comparison — see exactly which destinations each passport unlocks that the other doesn't
• Transit visa check — do you need a visa just to change planes? 200+ passport × layover rules
• Official government apply links included

</details>

<details> <summary><strong>🌤️ Weather</strong></summary>

• 16-day live forecast for any location
• Best month to visit anywhere based on 5 years of climate data
• Jet lag calculator with science-based recovery schedule

</details>

<details> <summary><strong>⚠️ Safety</strong></summary>

• Live US State Dept advisory level for any country (1 = safe, 4 = do not travel)
• List every country at or above a given risk level
• Recent travel news: strikes, airport closures, entry bans, protests

</details>

<details> <summary><strong>💰 Costs</strong></summary>

• Daily budget estimates for 220 cities (budget / mid-range / luxury)
• Live currency conversion
• Total trip cost estimate combining flights, hotels, and daily spend

</details>

<details> <summary><strong>🗺️ Planning</strong></summary>

• Day-by-day itinerary with weather and activities for each day
• Rank and score destinations by cost + weather + safety + events
• Compare multiple destinations side-by-side
• Aurora viewing destinations with NOAA KP-index forecast
• Open-jaw trips — fly into Rome, train to Paris, fly home from Paris. Composed automatically.

</details>

<details> <summary><strong>🍜 Food & Nightlife</strong></summary>

• Restaurants, bars, pubs, and cafes near any location (OpenStreetMap)
• Cuisine filters, price level, opening hours, distance
• Booking links: Google Maps, Zomato, TripAdvisor, Yelp, OpenTable, Resy, Untappd

</details>

<details> <summary><strong>🎒 On the Ground</strong></summary>

• Packing list tailored to weather, activities, and trip length
• Language phrasebook for 17 languages with pronunciation guides
• Layover guide for 10 major hub airports (DXB, SIN, IST, DOH, NRT, CDG, HKG, ICN, AMS, HND)
• Health requirements: vaccines, water safety, food safety, pre-trip timeline
• Bus, train, and ferry options with direct booking links
• Viewpoints, beaches, hiking trails, coworking spaces near any location
• Local SIM guide — 25+ countries: best prepaid SIM vs eSIM, cost, where to buy, tethering policy

</details>

<details> <summary><strong>🧠 Memory & Decisions</strong></summary>

• Saves your home airports, passports, currency, and interests — never ask again
• Logs your trip history
• Saved trips — a persistent trip with an 8-item booking checklist that survives across sessions
• Fare watching — set a target price on a route, re-price on demand, get a buy signal when it drops
• Value ranking — scores options 0–100 on price plus stops, duration, refundability, baggage and hassle (flags hidden-city / split-ticket risk), so cheapest isn't blindly "best"

</details>

<details> <summary><strong>💳 Credit Card Points & Miles</strong></summary>

• Points valuation — is this award booking a good deal? Cents-per-point calculator with verdict (excellent / good / fair / poor) against 20+ program baselines
• Transfer partners — which airlines and hotels can you transfer Chase UR / Amex MR / Citi TYP / Capital One / Bilt points to? With ratios and transfer times
• Points vs cash — should you use points or pay cash? Factors in cpp value, opportunity cost, and what you'd earn back paying cash
• Earning calculator — how many points does a $500 dinner earn on your Amex Gold? 9 cards modeled with bonus categories
• Sweet spot awards — curated list of outsized-value redemptions: ANA first class for 120k VA miles (16.7cpp), Hyatt all-inclusive for 25k (2.4cpp), Turkish business for 45k (8.9cpp)
• Program comparison — which of your points programs gives the best value for a specific booking?
• Card portfolio — save your cards to your profile, points tools use them automatically

</details>

---

Setup (5 minutes)

Step 1 — Install Python

You need Python 3.10 or newer. Check if you have it:

python3 --version

Don't have it? Download from python.org.

---

Step 2 — Install Wander Agent

From PyPI (recommended):

pip install wander-agent

Or with uv — no install at all, run directly:

uvx wander-agent

Or from source:

git clone https://github.com/VirajMishra1/wander-agent.git
cd wander-agent
pip install -e .

Verify it worked:

wander-agent --help

---

Step 3 — Connect to your AI

Pick the app you use:

<details> <summary><strong>Claude Desktop</strong></summary>

Open this file in a text editor:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Save the file, then quit and reopen Claude Desktop.

If you get an error about wander-agent not being found, find the full path first:

which wander-agent

Then use that path in the config:

{
  "mcpServers": {
    "wander-agent": {
      "command": "/usr/local/bin/wander-agent"
    }
  }
}

</details>

<details> <summary><strong>Claude Code (terminal)</strong></summary>

claude mcp add wander-agent wander-agent

Confirm it registered:

claude mcp list

</details>

<details> <summary><strong>Cursor</strong></summary>

Create or edit .cursor/mcp.json in your home directory:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Restart Cursor.

</details>

<details> <summary><strong>Windsurf</strong></summary>

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

Restart Windsurf.

</details>

<details> <summary><strong>Cline (VS Code extension)</strong></summary>

Open VS Code settings, search for "Cline MCP", edit cline_mcp_settings.json:

{
  "mcpServers": {
    "wander-agent": {
      "command": "wander-agent"
    }
  }
}

</details>

<details> <summary><strong>Continue.dev</strong></summary>

Edit .continuerc.json in your project or home directory:

{
  "mcpServers": [
    {
      "name": "wander-agent",
      "command": "wander-agent"
    }
  ]
}

</details>

<details> <summary><strong>Zed</strong></summary>

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "wander-agent": {
      "command": {
        "path": "wander-agent",
        "args": []
      }
    }
  }
}

</details>

---

Optional: API keys for better data

Everything works without any API keys. These add richer data if you want:

Variable	What it unlocks	Get it free at
FOURSQUARE_API_KEY	Real ratings and price levels for restaurants/bars	foursquare.com/developers
TICKETMASTER_API_KEY	Live event listings (concerts, sports, shows)	developer.ticketmaster.com

Set them before starting your AI:

export FOURSQUARE_API_KEY=your_key_here
export TICKETMASTER_API_KEY=your_key_here

Or add them to your shell profile (~/.zshrc, ~/.bashrc) to make them permanent.

---

All 66 Tools

✈️ Flights

Tool	What it does
search_flights	Live flight search across Google Flights and Kiwi.com in parallel. Returns prices, duration, stops, and booking links.
find_skiplagged_fares	Hidden-city fares — buy a connecting flight and exit at the layover city. Often 40–60% cheaper. Carry-on only.
find_split_ticket	Book two separate tickets through a hub instead of one through-ticket. OTAs are contractually forbidden from showing this. Savings of 20–60% on many routes. Includes full risk disclosure.
find_cheapest_month	Scans the next 12 months by sampling the first Tuesday of each month (statistically cheapest booking day). Returns all months ranked by price with season analysis and booking links.
fare_calendar	Full month price grid — up to 15 sampled days, day-of-week analysis, price tiers, best/worst weeks. Find the cheapest day to fly within a given month.
find_mistake_fares	Scans Secret Flying and The Flight Deal RSS for error fares and flash deals.
cheap_anywhere_from	Cheapest destinations from an origin across 114 airports worldwide.
find_destinations_by_budget	Finds destinations reachable within a total budget (flights + hotels).
multi_origin_meetup	Cheapest city for multiple friends to meet, flying from different cities.
verify_flight_route	Confirms a direct or connecting route exists between two airports.
find_aurora_destinations	Aurora-viewing destinations with live NOAA KP-index forecast and flight prices.

🏨 Hotels

Tool	What it does
search_hotels	Hotels with booking links to Booking.com, Airbnb, Expedia, Tripadvisor, and 6 more.
optimize_budget	Finds the cheapest flight + hotel combo across a flexible date window (±7 days).

📋 Visas & Entry

Tool	What it does
check_visa_requirement	Visa category for a passport + destination pair. Returns visa-free, ETA, e-visa, visa on arrival, or visa required — with the official apply link.
visa_free_destinations	Every country a given passport can enter without a full embassy visa.
get_passport_power	Henley Index 2024 rank, visa-free access count, frictionless travel %, and regional breakdown for any passport. Pass two passports to get a head-to-head diff: exactly which destinations each one unlocks that the other doesn't.
check_transit_visa	Do you need a transit visa at your layover airport? Covers 200+ passport × layover-country combinations. Checks LHR, JFK, DXB, SIN, FRA, IST, DOH, NRT, ICN, YYZ, SYD, and 30+ others.

🌤️ Weather

Tool	What it does
get_weather	16-day live weather forecast for any coordinates. Falls back to 5-year historical data for dates beyond the forecast window.
best_month_to_visit	Ranks all 12 months for a location by weather quality, based on historical climate data.

⚠️ Safety & News

Tool	What it does
get_travel_advisory	US State Dept advisory level (1–4) and summary. Pulled from the live RSS feed.
list_advisories_by_level	All countries currently at or above a given advisory level.
get_travel_news	Scans Google News for recent disruptions: strikes, airport closures, entry bans, protests.

💰 Costs & Currency

Tool	What it does
get_cost_of_living	Daily budget estimates for 220 cities across budget, mid-range, and luxury tiers.
convert_currency	Live currency conversion via European Central Bank rates.
get_exchange_rates	Exchange rates for multiple currencies from a base currency.

🗺️ Planning & Scoring

Tool	What it does
plan_trip_package	The main orchestrator. Calls 8+ tools in parallel and returns a complete trip: flights, hotels, visa, weather, safety, activities, ground transport, cost estimate, and booking checklist.
plan_itinerary	Day-by-day itinerary with weather forecast and suggested activities for each day.
find_open_jaw	Plan a fly-in/overland/fly-out trip: land in city A, travel by train or bus, fly home from city B. Composes flight + ground transport search. Shows total cost vs a round-trip to city A only. Accepts city names or IATA codes.
score_destinations	Ranks destinations by a weighted combination of cost, weather, safety, and events.
compare_destinations	Side-by-side comparison of 2–5 destinations for the same dates.

🍜 Food & Nightlife

Tool	What it does
search_restaurants_bars	Real venues near a location from OpenStreetMap. Returns cuisine, price level, opening hours, distance, and links to Google Maps, Zomato, TripAdvisor, Yelp, OpenTable, Resy, and Untappd.

🌐 Smart Trip Tools

Tool	What it does
score_nomad_cities	Ranks cities for remote work across 6 dimensions: cost, safety, internet speed, weather, visa ease, and lifestyle. Configurable weights.
calculate_flight_carbon	CO2e footprint for any flight using ICAO/DEFRA 2024 factors with radiative forcing (RFI ×1.9). Per-passenger and total emissions, Gold Standard offset cost, and train/car comparison for short routes.

🎒 On the Ground

Tool	What it does
generate_packing_list	Packing list tailored to destination weather, activities, trip length, and budget level.
find_places	Viewpoints, beaches, hiking trails, coworking spaces, waterfalls, markets, and more from OpenStreetMap.
calculate_jet_lag	Jet lag severity with a science-based recovery schedule: pre-departure shift, melatonin timing, light exposure strategy.
get_language_phrasebook	Phrasebook for 17 languages with local script, romanized pronunciation, and audio tips.
get_stopover_guide	What to do during a layover at 10 major hubs. Includes transit visa check, in-airport activities, and city excursion options.
check_travel_health	Required and recommended vaccines, water safety, food safety, mosquito risk, altitude risk, and a pre-trip preparation timeline. Based on CDC and WHO 2024–2025 data.
search_ground_transport	Bus, train, and ferry options with booking links. Region-aware: Amtrak and Greyhound for the US, Trainline and BlaBlaCar for Europe, IRCTC for India, 12Go for Southeast Asia.
get_local_sim_guide	Best prepaid SIM card and eSIM for 25+ countries. Returns operator, cost, data allowance, where to buy, tethering policy, and duration-based advice (≤3 days → eSIM; longer → local SIM). Falls back to Airalo/Holafly for unlisted countries.

🏛️ Attractions & Info

Tool	What it does
search_activities	Attractions near a location from Wikidata. Filter by category: museums, parks, architecture, nightlife, food, historic, nature, and more.
get_local_events	Live events from Eventbrite: concerts, sports, festivals.
get_destination_info	Country basics: currency, official language, timezone, dialling code, driving side.
geocode	Converts a place name to coordinates.
verify_place	Confirms a place actually exists (catches AI hallucinations before they reach you).

🧠 Traveler Profile

Tool	What it does
get_traveler_profile	Loads your saved profile: home airports, passports, currency, interests, and trip history.
onboard_traveler	One-time setup. Saves your preferences so the AI uses them automatically in every future session.
update_traveler_profile	Update any field, manage credit cards in your portfolio, or log a completed trip.
get_trip_history	Your logged trip history.

🧳 Saved Trips (cross-session memory)

Persisted to ~/.wander_agent/trips.json. A trip carries an 8-item booking checklist (flights, hotel, visa, insurance, ground transport, advisory, packing, notify bank).

Tool	What it does
save_trip	Save a trip you're planning. Returns a trip_id and a fresh booking checklist.
list_my_trips	List saved trips with checklist progress. Filter by status (planning/booked/completed/cancelled).
get_trip_status	Full state + checklist progress for one trip, by id or destination.
update_trip	Change status/dates, tick checklist items, or shortlist a flight/hotel option onto the trip.
delete_trip	Remove a saved trip.

🔔 Fare Watching

Persisted to ~/.wander_agent/fare_watches.json. Records a baseline price and a price history per watched route.

Tool	What it does
watch_fare	Start watching a route with an optional target price. Captures a baseline on creation.
list_fare_watches	List watches with baseline / last / lowest price seen and status.
check_fare_watches	Re-price watched routes now. Returns buy-signal alerts: target_hit, price_drop, price_rise, no_change.
stop_fare_watch	Pause or delete a watch.

⚖️ Value Ranking

Tool	What it does
rank_trip_options	Scores a list of flight/trip options 0–100 on price plus stops, duration, refundability, baggage and hassle. Presets: cheapest / fastest / easiest / flexible / balanced. Flags hidden-city, split-ticket and self-transfer risk so the cheapest fare isn't blindly the winner.

💳 Credit Card Points & Miles

Static dataset covering 20 loyalty programs (Chase UR, Amex MR, Citi TYP, Capital One, Bilt, 11 airlines, 4 hotel chains), 9 popular credit cards with bonus categories, and 10 curated sweet-spot awards. Card portfolio saved to ~/.wander_agent/profile.json.

Tool	What it does
estimate_points_value	Is this award booking worth it? Calculates cents-per-point and compares against baseline valuations for the program. Returns excellent / good / fair / poor verdict.
find_transfer_partners	Shows all airline and hotel transfer partners for a bank program (Chase UR → United, Hyatt, BA, etc.) with transfer ratios and times. Sorted by partner value.
calculate_points_or_cash	Should you use points or pay cash for this booking? Factors in cpp value, opportunity cost of points, and how many points you'd earn back paying cash on a specific card.
estimate_points_earning	How many points a purchase earns on a given card. Covers 9 cards with bonus category multipliers (3x dining, 5x travel portal, 4x supermarkets, etc.).
find_sweet_spot_awards	Curated high-value redemptions: ANA first class via VA miles (16.7cpp), Singapore Suites (16.3cpp), Turkish business (8.9cpp), Hyatt all-inclusive (2.4cpp), and more. Filters by your programs, cabin, budget, or route.
compare_points_programs	Which of your points programs gives the best value for a specific booking? Compares estimated points cost, portal vs transfer value, best partner, and matching sweet spots. Uses your profile cards automatically.

---

Tool Rankings: Usefulness × X-Factor

Ranked by a combination of practical impact and uniqueness — things no OTA, no chatbot, and no other travel tool does.

Rank	Tool	Why it's here
🥇 1	find_split_ticket	OTAs are contractually prevented from showing this. Book two tickets via a hub instead of a through-ticket. 20–60% savings on many long-haul routes. The travel industry's open secret.
2	find_skiplagged_fares	Hidden-city ticketing. Buy a flight to city B with a layover in city A — exit in city A and never board the last leg. 40–60% off. Illegal per airline T&Cs but not against any law. Carry-on only.
3	plan_trip_package	One message → complete trip. Fires 8+ tools in parallel: flights, hotels, visa, weather, safety, activities, ground transport, cost estimate. The single best demo of what this agent can do.
4	find_cheapest_month	Scans 12 months, samples first Tuesday of each (statistically cheapest booking day). Returns months ranked by price with season labels. Shifting by 1–2 months = hundreds of dollars saved.
5	check_transit_visa	The one nobody thinks to check until it's too late. Do you need a visa just to change planes at Heathrow? At Frankfurt? 200+ passport × layover combinations. Catches the trip-killer before you book.
6	multi_origin_meetup	Three friends, three different cities. What's the cheapest city for all of them to meet? No OTA has a tool for this.
7	find_open_jaw	Fly into Rome, take a train to Paris, fly home from Paris. No OTA lets you compose this. Automatically prices both flights + the overland segment and compares vs a simple round-trip to Rome.
8	get_passport_power	Henley 2024 rank, visa-free %, regional breakdown. Dual-passport mode: exact set-diff of which destinations each passport unlocks. "Use your Indian passport for Thailand, your US passport for Brazil."
9	score_nomad_cities	6-dimension scoring for digital nomad decisions: cost, safety, internet speed, weather, visa ease, lifestyle. Configurable weights. "Score Bali vs Lisbon vs Tbilisi for 3 months, weight internet 3× above cost."
10	find_mistake_fares	Error fares and airline pricing mistakes from dedicated deal aggregators. Passive discovery — "are there any crazy cheap fares out of JFK right now?"
11	fare_calendar	Full price grid for a month. Up to 15 sampled days, cheapest day highlighted, day-of-week analysis (Tuesdays 18% cheaper on average), best/worst weeks.
12	cheap_anywhere_from	"Where can I fly cheapest from London right now?" Scans 114 airports. Discovery tool for spontaneous travelers.
13	find_destinations_by_budget	"I have $1,500 total for 7 nights, leaving from NYC — where can I actually go?" Returns ranked reachable destinations.
14	optimize_budget	Shifts departure ±7 days to find the cheapest flight + hotel combo. Same trip, different dates, lower price.
15	calculate_flight_carbon	ICAO/DEFRA 2024 emission factors with radiative forcing (RFI ×1.9). Per-person and total CO2e, Gold Standard offset cost at $18/tonne, train/car comparison for routes under 1,500km.
16	search_flights	Core engine. Parallel Google Flights + Kiwi.com. Checks nearby airports automatically.
17	check_visa_requirement	Most-asked travel question. Instant answer with official government apply link.
18	plan_itinerary	Day-by-day schedule with weather per day and activity suggestions.
19	score_destinations	Weighted rank: cost + weather + safety + upcoming events. "Best place to go in September with good weather, under $150/day, safety level 1."
20	visa_free_destinations	Full list of countries a passport can enter without a full embassy visa.
21	get_local_sim_guide	25+ countries. Best prepaid SIM vs eSIM, exact cost, where to buy, tethering, activation steps. Short trip = eSIM. Long trip = local SIM. Saves the first-hour scramble at every airport.
22	compare_destinations	Side-by-side: cost, weather, safety, visa requirements, flights — for 2–5 destinations, same dates.
23	search_ground_transport	Bus + train + ferry with real booking links. Region-aware. Often cheaper and more convenient than flying for routes under 500km.
24	check_travel_health	Required vaccines, recommended vaccines, water safety, food safety, mosquito risk, altitude risk, pre-trip timeline. CDC + WHO 2025 data.
25	get_travel_advisory	Live US State Dept level 1–4 with summary. Pulled from RSS — not cached stale data.
26	get_weather	16-day live forecast. Falls back to 5-year historical climate data for further-ahead dates.
27	find_aurora_destinations	Best spots for northern lights with live NOAA KP-index forecast + flight prices from your origin. Viral for the "bucket list" audience.
28	search_hotels	Hotel search with deep links to 9 booking sites. No prices shown directly (all hotel price APIs are paid), but all the links you need.
29	get_cost_of_living	Daily budget for 220 cities: budget / mid-range / luxury tiers.
30	best_month_to_visit	Climate-based ranking of all 12 months for a location. Based on 5 years of historical data.
31	get_stopover_guide	What to actually do during a long layover at DXB, SIN, IST, DOH, NRT, CDG, HKG, ICN, AMS, or HND. In-airport options + city excursion feasibility.
32	search_activities	Wikidata attractions by category: museums, parks, architecture, food, nightlife, historic, nature.
33	find_places	OpenStreetMap viewpoints, beaches, hiking trails, coworking spaces, waterfalls, hot springs, markets.
34	search_restaurants_bars	Real venues from OSM with 7 booking site links per result. Cuisine filter, price level, distance.
35	get_language_phrasebook	17 languages. Local script + romanized pronunciation + audio tips.
36	generate_packing_list	Tailored to destination weather, planned activities, trip length, and budget level.
37	get_local_events	Live Eventbrite events at destination: concerts, festivals, sports. Best for 0–60 day horizon.
38	get_travel_news	Google News scan for disruptions: strikes, closures, protests, entry bans.
39	calculate_jet_lag	Severity rating + science-based recovery: pre-trip sleep shifting, melatonin timing, light exposure schedule.
40	get_destination_info	Country basics: currency, language, timezone, dialling code, driving side.
41	list_advisories_by_level	All countries currently at Level 2, 3, or 4. Useful for insurance and risk-screening.
42	verify_flight_route	Confirms a route actually exists. Catches hallucinated itineraries before you book.
43	onboard_traveler	One-time setup: home airports, passports, currency, interests. Feeds every tool automatically.
44	get_traveler_profile	Load saved profile. Used automatically at session start.
45	update_traveler_profile	Update preferences or log a completed trip.
46	get_trip_history	Your logged trip history.
47	convert_currency	ECB live rate conversion.
48	get_exchange_rates	Multi-currency rates from a base currency.
49	geocode	Place name → latitude/longitude. Used internally by most tools.
50	verify_place	Confirms a place exists before building a trip around it. Anti-hallucination guardrail.
51	find_sweet_spot_awards	Curated outsized-value redemptions the points community swears by. ANA first (16.7cpp), Singapore Suites (16.3cpp), Turkish J (8.9cpp). Filtered by your card portfolio.
52	estimate_points_value	Cents-per-point calculator with verdict against 20+ program baselines. Catches bad redemptions before you burn points.
53	calculate_points_or_cash	Points or cash? Factors cpp, opportunity cost, and earning-back. The question every points traveler asks on every booking.
54	compare_points_programs	Which program gives best value for this booking? Cross-program comparison with sweet-spot matching.
55	find_transfer_partners	Maps bank currency → airline/hotel partners. Transfer ratios, times, and partner valuations.
56	estimate_points_earning	Points earned per dollar by card and category. 9 cards modeled.

---

Data sources

Source	What it provides	Key needed?
Google Flights (scraper)	Flight prices and airline names	No
Kiwi.com	Live bookable flight prices	No
Open-Meteo	Weather forecast and 5-year historical climate	No
Frankfurter (ECB)	Currency exchange rates	No
Wikidata SPARQL	Attractions and points of interest	No
OpenStreetMap Overpass	Restaurants, bars, beaches, viewpoints, hiking	No
US State Dept RSS	Travel advisories	No
Open-Meteo Geocoding	Coordinates for place names	No
RESTCountries	Country metadata	No
Secret Flying / The Flight Deal	Mistake fares and deals	No
NOAA Space Weather	Aurora KP-index forecast	No
Google News RSS	Travel disruption news	No
Skiplagged	Hidden-city fares	No (fragile scraper)
Rome2Rio / Omio	Ground transport options	No (fallback to deeplinks)
Eventbrite	Live local events	No
Foursquare Places v3	Restaurant/bar ratings and price levels	Optional (free tier)
Ticketmaster Discovery	Live event listings	Optional (free tier)
Static datasets	Visa requirements, cost of living, airport data, transit visa rules, SIM card data, Henley rankings, points/miles valuations	N/A

---

How much can you trust each number?

Most results carry a data_meta block so the AI can tell you how reliable a figure is before you book:

"data_meta": {
  "confidence": "scraped_live",
  "trust_score": 80,
  "trust_label": "Live scrape",
  "meaning": "Scraped from Google Flights just now. Real but can shift minute to minute.",
  "fetched_at": "2026-06-02T18:30:00+00:00",
  "source": "google_flights + kiwi.com"
}

Label	Trust	What it means
deeplink	95	Opens the live provider page — always current
live_api	90	Official API (ECB rates, NOAA)
live_rss	85	Live government feed (State Dept advisories)
live_forecast	85	Open-Meteo live weather
scraped_live	80	Real-time scrape — real but volatile
curated_snapshot	55	Hand-curated dataset — verify before booking
wikidata_fallback	50	Wikidata-derived
estimated	35	Modeled figure — rough guide only

---

Honest limitations

Flight prices: Google Flights scraper can break if Google changes their page structure. Kiwi prices are real and bookable. Both run in parallel — if one fails the other still returns results.

Split-ticket risk: find_split_ticket surfaces real savings but carries missed-connection risk. If your first flight is delayed the second airline won't wait and won't rebook you. The tool always returns a full risk disclosure list. Buy travel insurance that covers missed connections on separate tickets.

Hotel prices: Every hotel price API is paid. This tool returns hotel names and links to 9 booking sites where you can see real prices. No prices are shown directly.

Visa data: Static snapshot (updated 2024). Policies change — always verify with the official link in the response before you book anything. Do not rely on this for immigration decisions.

Transit visa data: Rules encoded as a static dataset covering 200+ combinations. Edge cases (nationalities with bilateral exemptions, recent policy changes) may be missing. Always verify with the airline or destination embassy.

Passport power data: Henley Index 2024 snapshot. Rankings shift year to year. Confirm with official sources before making nationality-based decisions.

SIM card data: Curated snapshot as of 2024-Q4. Prices and plans change frequently. Treat as guidance; verify before purchase.

Events: Scraped from Eventbrite. Best coverage for events 0–60 days ahead. Further-future events may not be listed yet.

Travel advisories: US State Dept only. Updated within 24–48 hours of official changes via RSS.

Health data: Curated snapshot from CDC Yellow Book and WHO 2024–2025 recommendations. Not a substitute for advice from a travel medicine clinic.

Ground transport: Rome2Rio data for route discovery. Actual prices and schedules must be confirmed on the booking sites — times and fares change.

Points/miles valuations: Baseline cpp values are editorial averages (TPG, NerdWallet, OMAAT). Actual redemption value depends on specific award availability, transfer bonuses, and dynamic pricing. Sweet spot awards assume saver-level availability. Card bonus categories reflect terms as of 2025-Q1 — issuers change these periodically.

Carbon calculations: ICAO/DEFRA 2024 emission factors with standard RFI multiplier (×1.9). Actual emissions vary by aircraft type, load factor, and routing. Use as an estimate, not an accounting figure.

---

Cloud deployment (Docker)

The included Dockerfile and railway.toml let you host this server in the cloud so you can connect to it from any device — not just the computer where you installed it.

You do not need this for normal local use. Install and run locally as described in Setup above.

If you want to self-host on Railway:

# Push to GitHub, then connect repo to Railway
# Set env vars in Railway dashboard if using optional API keys

The server switches from stdio (local) to HTTP automatically based on the WANDER_TRANSPORT environment variable.

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Count registered tools
grep -c "@mcp.tool()" src/wander_agent/server.py

Adding a tool:

1. Create src/wander_agent/tools/your_tool.py with an async function
2. Import it in src/wander_agent/server.py
3. Wrap with @mcp.tool() and an async wrapper function
4. Restart your AI client to pick up the new tool

CI: every push and PR to main runs the test suite on Python 3.10/3.11/3.12 and asserts the registered tool count.

Releases: publishing a GitHub release triggers the PyPI publish workflow (trusted publishing — no tokens). Bump version in pyproject.toml and server.json first.

---

License

MIT

mcp-name: io.github.VirajMishra1/wander-agent