Jinko MCP Server

Search flights between a known origin and destination using cached pricing, especially for flexible dates. WHEN TO USE THIS TOOL (CRITICAL): - The user provides both an origin AND a destination (city or airport) - Examples: "Paris to Barcelona", "JFK to CDG", "London to NYC for a weekend" - Supports loose / flexible dates: single dates, date arrays, date ranges, stay_days - ALSO the right tool for "cheapest flight", "best flight", "find me a flight", "cheapest date" phrasings — this tool returns the cheapest cached itineraries for the given route and window. WHEN TO USE find_destination INSTEAD: - The user does NOT specify a destination: "Where should I go from Paris?", "Best deals from NYC" - The user wants inspiration: "Beach destinations from London", "Cheap flights from SF" WHEN TO USE flight_search INSTEAD: - The user wants live pricing on one specific route with an exact departure date. For a round trip, also require an exact return date; one-way trips need no return date. - Examples: "Paris → NYC one-way on June 17", "Paris → NYC, June 17 → June 26" - flight_search hits live pricing (each call has a cost) and is the step immediately before booking. Use it once the route and required travel dates are locked. - **TRIP-CONTEXT DATES COUNT AS EXACT.** If a trip is already in context with a HOTEL, the hotel's check-in and check-out ARE the exact departure/return dates the user wants — even if they don't restate the dates in the message. In that case use flight_search (not flight_calendar) with the hotel's check-in as departure_date and check-out as return_date. Examples: cart has hotel May 8 → May 10 in Madrid; user says "add a flight from Paris" → flight_search with PAR→MAD, dep=2026-05-08, ret=2026-05-10. The trip cross-sell hint confirms this — when it points you at flight_search, follow it. IMPORTANT: All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates. Use departure_dates for specific days or departure_date_ranges for a window. There is no departure_date parameter. Origin and destination: send the city code when the user named a city (Paris → PAR, New York → NYC) and the airport code when they named an airport (JFK, CDG). A code that names a multi-airport city covers every airport of that city; any other code is that one airport. LAX, MIA and LAS are both a city code and that city's main airport, so they are read as the city here — this tool has no type field; flight_search has origin_type / destination_type to pin one airport. ROUTE SEARCH: - Use exact 3-letter IATA airport codes or IATA city code for both origin and destination - Date ranges OR stay duration for flexible trip planning - Natural trip duration (stay_days) instead of exact return dates - By default, please search roundtrip flights unless user specifies one-way. Use trip_type="oneway" ONLY when the user explicitly asks for a one-way trip USE CASES: ✓ "Find flights from JFK to CDG next month" - route + flexible date range ✓ "Fly from LA to Tokyo for a week in December" - uses departure_date_ranges + stay_days ✓ "Paris to Barcelona for a weekend in April" - route + loose window ✓ "Cheapest flight from ORD to LHR in June" - route + loose month window ✓ "Direct business-class flight NYC → LON next month" - route with preferences Flow: flight_calendar → (user picks) → flight_search (price_check with offer_token) → trip → book. Or, for precise dates: skip flight_calendar and go straight to flight_search search mode. The widget displays flights in a scrollable carousel with options to view detailed itineraries. Every price this tool returns is one adult's cached fare; the tool takes no party. To price the whole party, price-check the offer using flight_search with price_check and the travellers' counts in traveler_counts. **Cost: 1 credit per call.**

Live flight tool with two modes. Provide exactly one of "search" or "price_check". Set the unused one to null or leave it out; for a route search, send "price_check": null. EACH CALL HITS LIVE PRICING — it prices ONE exact date pair, so any loose, open or flexible date query belongs to flight_calendar instead. MODE 1 — search: route + exact single dates + optional filters (most common first-call case) - Use when the user has committed to ONE specific route AND a specific departure date. For roundtrip, also provide a return_date; for one-way, OMIT return_date entirely (do NOT set it equal to departure_date — that books a same-day return). - ROUTE CODES: the city code when the user named a city, the airport code when they named an airport. Untyped, a code that names a multi-airport city is searched as the city and any other code as the airport; LAX, MIA and LAS are both a city code and that city's main airport, so they are read as the city unless you send origin_type / destination_type "airport". - Supports the full shop filter set on the same call: trip_type, max_stops, cabin_class, max_price (whole-trip budget for all passengers), limit, include_carriers / exclude_carriers, single_carrier_only, departure/arrival (and return_*) time ranges, connection_time_min/max_minutes, max_total_duration_minutes, refundable_only, changeable_only, checked_bag_included, via_airports / exclude_via_airports, aircraft_types, origin_alternate_airports / destination_alternate_airports, nearby_airports, same_connection/origin/turnaround_airport_only, origin_type, destination_type. - **Trip-context dates count as exact.** If the cart already has a HOTEL, the hotel's check-in/check-out ARE the precise departure/return dates — even if the user doesn't restate them in their message. Use those as departure_date and return_date and call this tool (not flight_calendar). Forward the trip_id on the call. - Examples: ✓ "Paris to NYC, June 1 to June 10" → { search: { origin: "PAR", destination: "NYC", departure_date: "2027-06-01", return_date: "2027-06-10" } } ✓ "Paris to Rome June 19 to 27, direct only, business class" → { search: { origin: "PAR", destination: "ROM", departure_date: "2026-06-19", return_date: "2026-06-27", max_stops: 0, cabin_class: "business" } } ✓ "JFK → CDG August 5 to 12, Air France only, under $800" → { search: { origin: "JFK", origin_type: "airport", destination: "CDG", destination_type: "airport", departure_date: "2026-08-05", return_date: "2026-08-12", include_carriers: ["AF"], max_price: 800 } } ✓ "Paris to LA June 3, one way" → { search: { origin: "PAR", destination: "LAX", departure_date: "2026-06-03" } } — the user named the city, so untyped LAX is right: it is the Los Angeles CITY and returns other Los Angeles airports too (Ontario, ONT) ✓ "Paris to LAX June 3, one way" → { search: { origin: "PAR", destination: "LAX", destination_type: "airport", departure_date: "2026-06-03" } } — the user named the airport ✓ "Paris to Rome June 19 to 27, at most one stop, refundable, bag included" → { search: { origin: "PAR", destination: "ROM", departure_date: "2026-06-19", return_date: "2026-06-27", max_stops: 1, refundable_only: true, checked_bag_included: true } } ✓ Cart has hotel in Madrid May 8 → May 10; user says "add a flight from Paris, directs only" → { search: { origin: "PAR", destination: "MAD", departure_date: "2026-05-08", return_date: "2026-05-10", max_stops: 0 }, trip_id: "trip_xxx" } - A search takes ONE origin/destination pair, ONE departure_date and at most ONE return_date — no date arrays, no date ranges. MODE 2 — price_check: confirm live fares for a specific flight - Use after the user picks a flight returned by flight_calendar or find_destination. Pass the offer_token. - Schema: { "price_check": { "offer_token": "..." } } WHEN NOT TO USE (route to flight_calendar instead): - "Cheapest flight in June" (loose month window) - "Paris to NYC next week" (loose window — 7 days) - "Best weekend to fly to Rome in spring" (no anchor date — the tool would have to pick one) - "Paris to Rome June 19 to 27, give or take a day" / "±2 days" / "a day or two either side of the 19th" (a soft window around the anchors — however narrow, this tool cannot widen a date) - Any OPEN date RANGE that implies multiple candidate departure/return pairs the user has not narrowed - CARRY THE FILTERS BACK: flight_calendar takes only direct_only, cabin_class, max_price and the time windows — refundable_only, changeable_only, checked_bag_included, max_stops and the carrier lists are NOT in its input, and price_check re-applies none of them (JIN-245). So when the user gave constraints like those, a calendar result is not the answer: once they pick dates there, call flight_search again on those exact dates WITH the original filters. The calendar budget is per adult: flight_calendar's max_price caps a one-adult fare; a whole-party budget is divided by adults only for a loose pre-filter. This tool's max_price covers the whole trip for all passengers — send the user's whole-trip figure unchanged, or for a per-person figure multiply by the number of passengers. Never carry the calendar budget across as max_total; flight_search refuses that name. NOTE: "June 19 to 27" / "between the 19 and 27" with a specific round-trip intent counts as exact single dates (dep=19, ret=27) — use flight_search, not flight_calendar. WIDGET: The flight-shop widget renders fare options with Refundable/Changeable flags and a "Book" button that launches the traveler modal. Both search and price_check modes populate this widget. FILTERS (search mode): - Every filter that narrows the results (cabin on the longest segment, stops, price, airlines, times, connections, fare conditions, aircraft) is applied exactly as sent: no returned itinerary breaks one. Options that widen a search (alternate or nearby airports) are searched where the source supports them, and sources search at most 9 via_airports per leg. An empty result carries an instruction: relay it. It asks which filter to relax only when a narrowing filter was sent; otherwise it asks about other dates or airports. - origin_alternate_airports / destination_alternate_airports are searched beside an airport or a city anchor: origin NYC with ["BOS"] covers New York's airports and Boston. - Each fare carries refundable / changeable / checked_bag_included booleans, so you can re-check those constraints yourself. IMPORTANT: - Prices are subject to change until booking is confirmed - Offer tokens may expire after some time - Always inform users about fare differences (refundable vs non-refundable, baggage, etc.) - Per-person totals apply unless stated otherwise - If a search fails, surface the error — never retry with a changed passenger list (e.g. dropping an infant); that silently changes the user's request. PRICE CHECK FILTERS ARE NOT APPLIED (CRITICAL): - When the user picks a flight from a previous flight_calendar or find_destination result, you call price_check with that offer_token. - The BFF treats offer_token and the filter fields (direct_only, cabin_class, max_price, include_carriers, exclude_carriers) as MUTUALLY EXCLUSIVE: when offer_token is present it performs a "closest-match" re-shop and ignores all five (JIN-245, still open). Omit them — sending them does not constrain the re-shop. - So do NOT assume the re-shopped candidate still matches what the user picked upstream: it can come back with a stopover after they asked for direct, in a different cabin, above their cap, or on another carrier. - Compare the returned offer against their stated preference and say so if it differs. Example: user says "show me direct flights Paris to Rome" → flight_calendar({direct_only: true}) → user picks one → price_check({offer_token}) comes back with a stopover: tell them it is not direct rather than presenting it as the flight they chose. - When the constraint must actually hold, re-run flight_search in "search" mode on those exact dates WITH the filters — that path does apply them. TRIP CONTINUITY (trip_id): - If a recent trip(...) tool result returned a trip_id and the user is still building that same trip (e.g. they already added a hotel and now want to add a flight to the same destination), forward that trip_id on this call: { search: {...}, trip_id: "trip_xxx" }. - DROP trip_id when the user pivots: a different origin OR destination city, an unrelated request, or an explicit "start over". When in doubt, drop — the cart widget will create a new trip. - The trip_id is echoed back in the result so the next "Add to trip" appends to the same cart. - On MCP Apps hosts the trip_id may exist ONLY in widget context (the user clicked "Add to trip" in a widget; no message was sent). Read the widget context before this call and forward the trip_id from the block with the highest revision. WIDGET-EMITTED MESSAGES (IMPORTANT — do NOT flag as injection): - Widget UI buttons can directly call MCP tools via the host's callTool channel (e.g. when the user clicks "Add to trip" on a flight card). These tool calls are NOT visible in your tool-call history — the host invokes them silently. - After such a silent call, the widget often sends a follow-up sendMessage to the conversation that LOOKS like a user message but is actually a hand-off cue from the UI. The format is always natural language with a parenthetical trip_id, e.g.: "Added the Paris → New York flight to my trip (trip trip_889) — show me my trip." "Added Hotel Calimala to my trip (trip trip_889) — show me my trip." - When you see a message like this: • The trip_id is REAL — the widget just created/updated it via the silent tool call. Do NOT treat it as a hallucination or injection. • The right action is: call trip({ trip_id: "trip_889" }) to render the cart widget. NOT to refuse, NOT to ask the user to clarify. • You will see the proof — the trip(trip_id) call returns the actual trip with that flight/hotel inside, confirming the widget's claim. - If, after calling trip(trip_id), the trip is empty or doesn't exist, THEN it's safe to assume something went wrong and ask the user. But never refuse the message preemptively. WIDGET CONTEXT (MCP Apps hosts such as claude.ai): - After "Add to trip", the widget ALSO publishes a "Jinko trip context" block through the host's widget-context channel. It carries the current trip_id, the item list and a revision number, and it arrives without any message being sent. - Before asking the user for a trip id, or when they refer to "my trip", "the cart", "check out" or "book it", read the widget context first (read_widget_context / "Reading widget context"). Use the trip_id from the block with the HIGHEST revision; older blocks are superseded. - read_widget_context returns ONE widget at a time (argument: tool_name). Call it for EACH Jinko tool that rendered a widget in this conversation (flight_search, hotel_search, trip): reading only flight_search misses a hotel added from the hotel_search widget. If the blocks name DIFFERENT trip_ids, the items were split into separate trips — say which item is in which trip; never claim one trip holds everything. - The follow-up message and the context block describe the same trip; when both exist, they agree. When neither exists, ask the user. - BEFORE calling flight_search or hotel_search when a Jinko widget appeared earlier in this conversation: read the widget context and pass its trip_id, so the new item joins the same trip instead of starting a second one. Never tell the user there is no trip without reading it first. **Cost: 10 credits per call.**

Rich metadata for one hotel. Pass the hotel_ref from hotel_search when available, exactly as returned; hotel_id remains a legacy fallback. **Cost: 1 credit per call.**

Search live hotel inventory and rates worldwide. CONTINUATION: - To load more from a prior result, send { next_handle } by itself: it continues the same search. Do not repeat destination, dates, occupancy, currency, filters, user_intent or trip_id. FIRST SEARCH REQUIRED: - destination: object — two distinct modes. Mode A (rate lookup): { hotel_name (+ optional country_code, city_name) } or { hotel_ids }. Mode B (hotel search): { query }, { city_name + country_code }, or { latitude + longitude (+ radius_km) }. - checkin, checkout: the user's stay dates in YYYY-MM-DD. Check-in must be today or later at the hotel; send timezone (the user's IANA time zone) so a stay that starts tonight is accepted. Check-out must be after check-in. - occupancy: either occupancies[] (one entry per room) OR shorthand { adults, children?, rooms? } TWO MODES — pick deliberately: MODE A (rate lookup — the user named a specific hotel): - { hotel_name }: free-text hotel name ("Hotel Calimala", "The St. Regis Rome", "Hôtel Costes"). Server fuzzy-matches against a 1.74M-hotel catalog. ALWAYS pair with country_code AND city_name when known — lookup precision drops sharply on common names without scope. Returns 422 HOTEL_NAME_LOW_CONFIDENCE if no candidate scores ≥ 0.7; see "ERROR HANDLING" below. - { hotel_ids }: re-shop a known set (from a prior search result). In Mode A: property filters (min_rating, min_star_rating, max_star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids) do not apply: the named hotel is priced as if they were not sent (the user named the property). The same holds when a query is read as one hotel. filters.max_budget_per_night applies. The response includes nearby_alternatives — up to 40 hotels within ~3km of the matched property in the same response shape so the user can compare. MODE B (hotel search — the user is exploring a destination): - { query }: a natural-language destination (city, POI, island or region). The platform parses it once into city + country or coordinates and applies shared location normalization; raw query text is never sent to a supplier. - { city_name + country_code }: when the user named a city, even if ambiguous. Best when the destination has a primary city ("Mahón, ES" for Menorca; "Florence, IT" for Tuscany). Spell the city as an English-language booking site would — "Munich"/"Florence"/"Rome"/"Vienna", NOT "München"/"Firenze"/"Roma"/"Wien" — but keep the local form where that IS the international one ("Regensburg", "Nürnberg", "Lyon"), and never an archaic exonym ("Leghorn", "Ratisbon"). When the user wrote the city in another language, translate it for this field only; keep their spelling when you talk back to them. - { latitude + longitude + radius_km }: when exact coordinates and the desired area are already known; radius_km is the half-side of the square searched, up to 50. FIRST SEARCH OPTIONAL: - currency, guest_nationality - filters: { min_rating, min_star_rating, max_star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results } — Mode B only - filters.facility_ids / filters.hotel_type_ids take NAMES ("pool", "spa", "parking"; "hostel", "ryokan", "chalet") — the accepted names are listed on each parameter. For a facility the user requires, send that one name. A name outside the list is rejected with the accepted names. Every property filter is applied as sent. - filters.max_budget_per_night: per-night per-room price cap (request currency) for "under $150/night" asks — works in BOTH modes. Hotels whose CHEAPEST rate fits are kept with ALL their rates, on every page. WORKFLOW: 1. Call hotel_search with the destination, dates, and occupancy. 2. Each rate in the response includes an htl_* offer_id (the trip_item_token). 3. Pass the chosen htl_* token to trip(add_item) to build a cart. 4. Hotels work alongside flights in the same cart (single Stripe checkout). When the user's intent is given, hotels are ordered by how well each hotel matches the stated intent; a hotel may carry recommendationScore (0 to 1; not a guest rating) and distanceKm, its straight-line distance from the search center, in structuredContent; the text prints them on the hotel's "AI ranking" and distance lines. structuredContent also carries search metadata. ERROR HANDLING — 422 HOTEL_NAME_LOW_CONFIDENCE (Mode A only): When { hotel_name } fuzzy lookup finds no candidate ≥ 0.7, the response body is: { "error": { "code": "HOTEL_NAME_LOW_CONFIDENCE", "message": "...", "top_candidates": [{hotel_id, name, city, score}], "suggested_retry": { "destination": {...} } } } This is ACTIONABLE, not fatal: 1. Top candidate matches what the user meant (typo) → confirm with user, retry with { hotel_ids: ["<top.hotel_id>"] }. 2. None fit → ask "I couldn't pin down 'X' — search all hotels in <city>?" then retry with suggested_retry.destination. 3. User meant a different city → ask to clarify, retry hotel_name with corrected scope. Never silently auto-pick a low-confidence candidate. ERROR HANDLING — 422 DESTINATION_LOW_CONFIDENCE (Mode B city_name+country_code only): When the city has no exact catalog group but close trigram candidates exist, top_candidates are CITIES ({city, country_code, hotel_count, score}), not hotels. If the top candidate is obviously the user's typo, confirm and retry with that candidate's city_name + country_code (it resolves exactly — it is the group's canonical label); if several fit, ask the user which; never say the city has no hotels. destination_resolution is present on every successful search and says HOW the destination resolved. When the text response opens with a "Searched: …" line, the match was fuzzy or fell back to a literal string, the resolved city differs from what was asked, or the platform located a place that is not a city (an island, region, district, landmark, station, address or airport) — read it before telling the user where you searched. When destination_resolution.resolved_place is set, the platform located the place itself: tell the user that place, with its place_type when it is not a city, as where you searched. When destination_resolution.alternatives is set, the destination may name another place too (the same name in another country or state, the island rather than its town): name them, ask which one the user meant before booking, and search another by sending its latitude, longitude and radius_km. SANITY-CHECK THE CITY GROUP (Mode B city_name — an "exact" match can still be the wrong group): destination_resolution.catalog_hotel_count is how many properties the matched city group holds. A count in the single or low double digits for a city you would expect to be large does NOT mean the city is small — it means you matched a near-empty duplicate group. "Roma" holds 3 properties where "Rome" holds 20,706; "Firenze" holds 1 where "Florence" holds 6,986; "Wien" holds 7 where "Vienna" holds 4,580. Treat it as a DESTINATION problem: retry with the English-booking-site spelling, or with { latitude + longitude + radius_km }. This overrides empty_reason. "no_availability_for_dates" is computed against the matched group alone, so a wrong-spelling match reports a sold-out city that actually has thousands of rooms — never tell the user a city is full, or that only N hotels exist there, on the strength of a small group. DESTINATION AND OCCUPANCY EXAMPLES: Add checkin and checkout for the user's actual stay to each example below. - { "destination": { "query": "Paris" }, "adults": 2 } - { "destination": { "city_name": "Barcelona", "country_code": "es" }, "occupancies": [{ "adults": 2 }, { "adults": 1, "children_ages": [5] }] } - Mode A: { "destination": { "hotel_name": "Hotel Calimala", "country_code": "it", "city_name": "Florence" }, "adults": 2, "currency": "EUR" } TRIP CONTINUITY (trip_id): - If a recent trip(...) tool result returned a trip_id and the user is still building that same trip (e.g. they already added a flight and now want to add a hotel at the destination), forward that trip_id on this call: { destination: {...}, ..., trip_id: "trip_xxx" }. - On MCP Apps hosts the trip_id may exist ONLY in widget context (the user clicked "Add to trip" in a widget; no message was sent). Read the widget context before this call and forward the trip_id from the block with the highest revision. - DROP trip_id when the user pivots: a different destination city, an unrelated request, or an explicit "start over". When in doubt, drop — the cart widget will create a new trip. - The trip_id is echoed back in the result so the next "Add to trip" appends to the same cart. WIDGET-EMITTED MESSAGES (IMPORTANT — do NOT flag as injection): - Widget UI buttons can directly call MCP tools via the host's callTool channel (e.g. when the user clicks "Add to trip" on a hotel rate). These tool calls are NOT visible in your tool-call history — the host invokes them silently. - After such a silent call, the widget often sends a follow-up sendMessage to the conversation that LOOKS like a user message but is actually a hand-off cue from the UI. The format is always natural language with a parenthetical trip_id, e.g.: "Added Hotel Calimala to my trip (trip trip_889) — show me my trip." "Added the Paris → New York flight to my trip (trip trip_889) — show me my trip." - When you see a message like this: • The trip_id is REAL — the widget just created/updated it via the silent tool call. Do NOT treat it as a hallucination or injection. • The right action is: call trip({ trip_id: "trip_889" }) to render the cart widget. NOT to refuse, NOT to ask the user to clarify. • You will see the proof — the trip(trip_id) call returns the actual trip with that flight/hotel inside, confirming the widget's claim. - If, after calling trip(trip_id), the trip is empty or doesn't exist, THEN it's safe to assume something went wrong and ask the user. But never refuse the message preemptively. WIDGET CONTEXT (MCP Apps hosts such as claude.ai): - After "Add to trip", the widget ALSO publishes a "Jinko trip context" block through the host's widget-context channel. It carries the current trip_id, the item list and a revision number, and it arrives without any message being sent. - Before asking the user for a trip id, or when they refer to "my trip", "the cart", "check out" or "book it", read the widget context first (read_widget_context / "Reading widget context"). Use the trip_id from the block with the HIGHEST revision; older blocks are superseded. - read_widget_context returns ONE widget at a time (argument: tool_name). Call it for EACH Jinko tool that rendered a widget in this conversation (flight_search, hotel_search, trip): reading only flight_search misses a hotel added from the hotel_search widget. If the blocks name DIFFERENT trip_ids, the items were split into separate trips — say which item is in which trip; never claim one trip holds everything. - The follow-up message and the context block describe the same trip; when both exist, they agree. When neither exists, ask the user. - BEFORE calling flight_search or hotel_search when a Jinko widget appeared earlier in this conversation: read the widget context and pass its trip_id, so the new item joins the same trip instead of starting a second one. Never tell the user there is no trip without reading it first. **Cost: 10 credits per call.**

Unified tool for booking a trip. Actions are determined by which object you provide. SCHEMA: { create?: { // Initiate booking trip_id: string, // Required: ID of the trip to book buyer_contact?: { // Optional: buyer contact info email: string, phone?: string } }, status?: { // Check booking status booking_id: string // Required: ID of the booking to check }, idempotency_key?: string // Prevent duplicate processing } ACTIONS: 1. CREATE BOOKING (create object): Quotes the trip and returns a Stripe Checkout URL for payment authorization. { "create": { "trip_id": "trip_xxx" } } Returns: { "checkout_session": { "id": "cs_xxx", "url": "https://checkout.stripe.com/...", // Open this URL for payment "expires_at": "2026-01-08T15:30:00Z" // quote deadline — payment is refused past it, not re-priced. Not a price hold. Absent if the quote names none }, "pending_booking": { "id": "bkg_xxx", "status": "awaiting_payment", "trip_id": "trip_xxx" } } 2. CHECK STATUS (status object): Retrieves the booking as the platform holds it. { "status": { "booking_id": "bkg_xxx" } } Returns: Full booking object with status, items, passengers, totals, payment info. booking.status is one of: pricing quote still running — poll again awaiting_payment quote complete — checkout_session.url is where the customer pays processing paid — the platform is booking with the suppliers; poll again confirmed / partially_confirmed / failed / cancelled the outcome, with booking_reference, booked_items and documents No checkout URL is returned once the trip is paid: never ask the customer to pay again from processing or a terminal status. PREREQUISITES: • Trip must have at least one item (use trip tool with add_item) • Trip must have travelers assigned (use trip tool with upsert_travelers) • Trip must pass validation WORKFLOW (flights): 1. flight_calendar → offer_token 2. flight_search → trip_item_token 3. trip(add_item) → trip created 4. trip(upsert_travelers) → travelers set 5. book(create={trip_id}) → checkout URL WORKFLOW (hotels): 1. hotel_search → htl_* offer_id 2. trip(add_item, trip_item_token=htl_*) → trip created 3. trip(upsert_travelers) → travelers set 4. book(create={trip_id}) → checkout URL Flights and hotels can be in the same trip (single checkout). After book(create), poll with book(status={booking_id}) for confirmation. EXAMPLES: 1. Create booking: { "create": { "trip_id": "trip_xyz789" } } 2. Create booking with buyer contact: { "create": { "trip_id": "trip_xyz789", "buyer_contact": { "email": "[email protected]", "phone": "+15551234567" } } } 3. Check booking status: { "status": { "booking_id": "bkg_xxx" } } **Cost: 1 credit per call.**

Discover travel destinations when the user does NOT know where to go. This is a destination EXPLORATION tool. WHEN TO USE THIS TOOL (CRITICAL): - The user does NOT specify a destination: "Where should I go?", "Best deals from NYC" - The user wants inspiration based on criteria: "Beach destinations", "Somewhere warm", "Cheap flights from SF" - The user wants to compare multiple destination options from their origin - The user previously asked for destination recommendations and wants pricing for those options WHEN NOT TO USE THIS TOOL — USE flight_calendar INSTEAD: - The user specifies BOTH an origin AND a destination → use flight_calendar - Examples that should use flight_calendar, NOT this tool: • "Flights from Paris to Barcelona" → flight_calendar • "Find me a flight from JFK to CDG" → flight_calendar • "Cheapest flight from LA to Miami in June" → flight_calendar • "Paris to BCN for a weekend in April" → flight_calendar • "What are the cheapest dates to go to NYC from Paris?" → flight_calendar - If the user names a specific city/airport as destination, that means they KNOW where to go → flight_calendar IMPORTANT - DATES: All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates. Please fill as much as possible search parameters based on user intent to get best results. IMPORTANT - RE-CALL THIS TOOL when the user: - Asks for a different type of destination (beach, city trip, ski, etc.) - Asks for different dates while still exploring - The user is already in fullscreen mode in the widget CORE FUNCTIONALITY: - REQUIRED: User's origin location (LLM identifies ALL nearby airports) - OPTIONAL: Destination filtering by specific airports/cities OR omit for global discovery mode - Destination Discovery Mode: When destinations is omitted/empty, searches ALL destinations globally - Flexible dates and stay durations for exploring options - Filter by budget, direct flights preference, and locale - By default, please search roundtrip flights unless user specifies one-way AIRPORT IDENTIFICATION - CRITICAL: LLM MUST identify and recommend ALL relevant airports for user's origin location: - "New York": ["JFK", "LGA", "EWR"] - "London": ["LHR", "LGW", "STN", "LTN", "LCY"] - "Paris": ["CDG", "ORY"] - "Tokyo": ["NRT", "HND"] - "Chicago": ["ORD", "MDW"] - "Los Angeles": ["LAX"] - "San Francisco": ["SFO"] DESTINATION FILTERING - INTELLIGENT INTERPRETATION: Destinations can be specified using IATA airport codes OR city codes (3 letters). You can mix both types: - Airport codes: ["JFK", "CDG", "LHR"] - searches specific airports - City codes: ["NYC", "LON", "PAR"] - searches all airports in those cities - A code a city shares with its main airport (LAX, MIA, LAS) is read as the CITY: every airport of it DESTINATION LIST - CRITICAL: When users mention criteria that imply a type of destination, the LLM MUST generate the appropriate list: - "Sunny places in winter": ["MIA","MCO","SAN","PHX","HNL","CUN","PUJ","PTY","LIM","GIG"] - "Somewhere in Asia": ["NRT","HND","ICN","PVG","PEK","HKG","SIN","BKK","KUL","MNL"] - "Beach destinations": ["MIA","SAN","HNL","CUN","PUJ","SJU","NAS","MBJ"] - "European capitals": ["LHR","CDG","FRA","MAD","FCO","AMS","BRU","VIE","PRG","CPH"] If no filtering is specified ("anywhere", "surprise me"), leave destinations empty for global discovery. TYPICAL USE CASES: 1. "Where should I travel from NYC next month?" → origins: ["JFK","LGA","EWR"], destinations: [] 2. "I want to go somewhere warm from Chicago for a week in December" → origins: ["ORD","MDW"], destinations: [warm destinations] 3. "Best weekend getaways from Boston?" → origins: ["BOS"], destinations: [] 4. "Beach vacation from Seattle in summer under $600" → origins: ["SEA"], destinations: [beach destinations] IMPORTANT: Always provide ALL airports for origins to maximize search results. Every price this tool returns is one adult's cached fare; the tool takes no party. To price the whole party, price-check the offer using flight_search with price_check and the travellers' counts in traveler_counts. **Cost: 1 credit per call.**

Unified tool for managing a trip (shopping cart). Supports flights and hotels in the same cart. Actions are determined by which objects you provide. SCHEMA: { trip_id?: string, // Existing trip ID (omit to create new) offer_id?: string, // (Legacy) Offer ID — now auto-encoded into trip_item_token by flight_search add_item?: { ... }, // Add a flight or hotel to the trip remove_item?: { ... }, // Remove an item from the trip upsert_travelers?: { ... }, // Set travelers (replaces all) idempotency_key?: string // Prevent duplicate processing } ACTIONS: 1. ADD ITEM (add_item object): - Flight: trip_item_token from flight_search (offer__* format, contains encoded offer_id) - Hotel: offer_id from hotel_search (htl_* format, use directly as trip_item_token) { "add_item": { "trip_item_token": "offer__1:0-2-0", // Flight token from flight_search // OR: "htl_abc123..." // Hotel token from hotel_search "traveler_ids": ["traveler_1", "traveler_2"] // Optional: associate travelers } } MULTI-ROOM HOTEL (rooms array — one booking, one reference): When the user wants MULTIPLE ROOMS for ONE hotel stay (same hotel, same check-in/check-out), make ONE add_item call with the rooms array — do NOT add the same hotel twice as separate items when the user wants one reservation. Each entry carries that room's htl_* rate token from hotel_search (e.g. one rate per requested occupancy). 2–8 rooms; for a single room use trip_item_token instead. rooms and trip_item_token are mutually exclusive. Hotel tokens only; not every hotel rate can be booked this way, and one that cannot is refused when it is added. { "add_item": { "rooms": [ { "trip_item_token": "htl_rate_room1", "traveler_ids": ["traveler_1", "traveler_2"] }, { "trip_item_token": "htl_rate_room2", "traveler_ids": ["traveler_3"] } ] } } 2. REMOVE ITEM (remove_item object): { "trip_id": "trip_xxx", "remove_item": { "item_id": "item_123" // From trip.trip_items[].id } } 3. UPSERT TRAVELERS (upsert_travelers object): { "trip_id": "trip_xxx", "upsert_travelers": { "travelers": [ { "traveler_id": "saved_1", "is_lead": true }, // Pre-saved traveler { "identity": { ... } } // Or inline details ], "contact": { // Optional trip contact "email": "[email protected]", "phone": "+15551234567" } } } TRAVELER ENTRY OPTIONS: • { traveler_id: "id" } - Use pre-saved traveler • { traveler_id: "id", is_lead: true } - Pre-saved as lead • { identity: {...}, passport?: {...} } - Inline details PHONE NUMBERS: • International format with a leading + and the country code, e.g. "+12025550147". Spaces, hyphens, dots and parentheses are tolerated and removed. • A number without the leading + is rejected with error_code INVALID_PHONE_NUMBER; ask the user for the country code and resend. WORKFLOW: 1. flight_calendar → Returns flights with offer_token 2. flight_search → Returns fare options with trip_item_token (offer_id encoded inside) 3. trip(add_item={...}) → Adds flight, returns trip + saved travelers 4. trip(upsert_travelers={...}) → Sets travelers on trip 5. checkout_trip → Completes booking RETURNS: • trip: Complete trip object with items, travelers, totals • saved_travelers: Available pre-saved travelers for selection • recommended_products: Upsell opportunities (hotels, cars, insurance) • actions_performed: Which actions were executed • trip_item_id: ID of newly added item (if add_item performed) • hint: Action guidance for the LLM. May start with "Cross-sell: ask the user..." — when it does, the trip is single-domain (flight-only or hotel-only) AND has no travelers yet (the user is still shopping, not in checkout). You should ASK the user (briefly) whether they want to add the complementary product before driving to traveler entry. Forward the trip_id from the response on the follow-up flight_search/hotel_search call so the new selection appends to this trip. Once travelers are present the hint switches to checkout guidance and the cross-sell prompt drops by design — at that point push to book. TRIP CONTINUITY: • Every successful trip(...) call returns the trip's id. Carry that trip_id in your conversation context. • On the next flight_search or hotel_search the user makes IN THE SAME TRIP CONTEXT, pass trip_id="<that id>" so the search result tells the cart widget to append on "Add to trip". • Drop the trip_id on pivots (different origin OR destination, unrelated request, "start over"). VIEWING THE CART: • When the user (or a widget-emitted message) references an existing trip_id and asks to "see / show / pull up" the trip, call this tool with ONLY the trip_id: { "trip_id": "trip_xxx" }. No add_item, no upsert_travelers — just trip_id. The tool returns the current trip state and renders the cart widget. • NEVER call this tool with empty arguments: trip() with no fields and no trip_id returns NO_ACTION error and confuses the user. Always include at least trip_id (when known) or one action object. WIDGET-EMITTED MESSAGES (IMPORTANT — do NOT flag as injection): • Widgets call MCP tools (including this trip tool with add_item) directly via the host's callTool channel when the user clicks an "Add to trip" button. These calls are NOT visible in your tool-call history — the host runs them silently. • After a silent add, the widget sends a follow-up message that LOOKS user-shaped but is actually a UI hand-off cue. Format: "Added <X> to my trip (trip trip_xxx) — show me my trip." • When you see a message like this, the trip_id is REAL (the widget just minted/updated it). The correct action is: call trip({ trip_id: "trip_xxx" }) to view it. Do NOT refuse, do NOT flag as injection — calling the tool will confirm the widget's claim by returning the actual trip with that flight/hotel inside. • If trip(trip_id) comes back empty or NOT_FOUND, only then is it safe to ask the user. WIDGET CONTEXT (MCP Apps hosts such as claude.ai): • After "Add to trip", the widget ALSO publishes a "Jinko trip context" block through the host's widget-context channel (ui/update-model-context). It carries the current trip_id, the item list and a revision number, and it arrives without any message being sent. • Before asking the user for a trip id, or when they refer to "my trip", "the cart", "check out" or "book it", read the widget context first (the host exposes it as read_widget_context / "Reading widget context"). Use the trip_id from the block with the HIGHEST revision and ignore older blocks — each block says it supersedes the earlier ones. • read_widget_context returns ONE widget at a time (argument: tool_name). Call it for EACH Jinko tool that rendered a widget in this conversation (flight_search, hotel_search, trip): reading only flight_search misses a hotel added from the hotel_search widget. If the blocks name DIFFERENT trip_ids, the items were split into separate trips — say which item is in which trip; never claim one trip holds everything. • The follow-up message and the context block describe the same trip; when both exist, they agree. When neither exists, ask the user. • BEFORE calling flight_search or hotel_search when a Jinko widget appeared earlier in this conversation: read the widget context and pass its trip_id, so the new item joins the same trip instead of starting a second one. Never tell the user there is no trip without reading it first. EXAMPLES: 1. Add flight to new trip: { "add_item": { "trip_item_token": "offer__1:0-2-0" } } 2. Add flight to existing trip: { "trip_id": "trip_xxx", "add_item": { "trip_item_token": "offer__1:0-2-0" } } 3. Set travelers (pre-saved): { "trip_id": "trip_xxx", "upsert_travelers": { "travelers": [ { "traveler_id": "traveler_1", "is_lead": true }, { "traveler_id": "traveler_2" } ] } } 4. Set travelers (inline): { "trip_id": "trip_xxx", "upsert_travelers": { "travelers": [ { "identity": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "gender": "MALE", "passenger_type": "ADULT" }, "is_lead": true } ], "contact": { "email": "[email protected]", "phone": "+15551234567" } } } 5. Remove item: { "trip_id": "trip_xxx", "remove_item": { "item_id": "item_123" } } 6. Add flight AND set travelers (combined): { "add_item": { "trip_item_token": "offer__1:0-2-0" }, "upsert_travelers": { "travelers": [ { "traveler_id": "traveler_1", "is_lead": true } ] } } } **Cost: 1 credit per call.**