Jinko MCP

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" }, "pending_booking": { "id": "bkg_xxx", "status": "awaiting_payment", "trip_id": "trip_xxx" } } 2. CHECK STATUS (status object): Retrieves booking status. If payment is authorized but fulfillment hasn't started, automatically triggers fulfillment. { "status": { "booking_id": "bkg_xxx" } } Returns: Full booking object with status, items, passengers, totals, payment info. 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 confir…

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 f…

Search flights between a known origin and destination using cached pricing. Use this tool whenever the user specifies BOTH where they are flying FROM and where they are flying TO. 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 has committed to EXACT dates — both a single departure date AND a single return date for one specific route. - Example: "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 only once route + both dates are locked in. - **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. Please fill as much as…

Live flight tool with two modes. EACH CALL HITS LIVE PRICING — not for loose or flexible date queries (use flight_calendar for those). 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). - Supports filters on the same call: direct_only, cabin_class, max_price, include_carriers, exclude_carriers, 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 17 to June 26" → { search: { origin: "PAR", destination: "NYC", departure_date: "2026-06-17", return_date: "2026-06-26" } } ✓ "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", direct_only: true, 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" } } ✓ 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", direct_only: true }, trip_id: "trip_xxx" } - Only ONE departure_date and at most ONE return_date. No arrays, n…

Rich metadata (gallery, facilities, policies, per-room details) for a single hotel — called by the hotel widget on fullscreen open. **Cost: 1 credit per call.**

Search live hotel inventory and rates worldwide. 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 }, { latitude + longitude (+ radius_km) }, or { place_id }. - checkin, checkout: YYYY-MM-DD - 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: filters are ignored (user named the property), and the response includes nearby_alternatives — up to 5 hotels within ~2km 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 }: unambiguous cities or well-known POIs only ("Paris", "Times Square"). Provider AI search returns 0 for islands ("Menorca", "Santorini", "Mykonos"), regions ("Tuscany", "Provence", "Bavaria"), countries, archipelagos. Do NOT use { query } for those. - { 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). - { latitude + longitude + radius_km }: when the destination is an area, island, or region with no obvious primary city. radius_km up to 50. - { place_id }: when you already have an upstream Place ID. If the user names something non-city (an island, region, archipelago, neighborhood), DO NOT pass it as { query } — pick…

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 } } 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": "+1-555-123-4567" } } } TRAVELER ENTRY OPTIONS: • { traveler_id: "id" } - Use pre-saved traveler • { traveler_id: "id", is_lead: true } - Pre-saved as lead • { identity: {...}, passport?: {...} } - Inline details WORKFLOW: 1. flight_calendar → Returns flights with offer_token 2. flight_search → Returns fare options with trip_item_token (offer_id encoded inside…