Treeple per agenti IA

Server MCP

Un server Model Context Protocol remoto su HTTP Streamable. Indirizzare qualsiasi client abilitato MCP a:

https://mcp.treeple.kz/mcp

Per Claude Desktop, Claude Code e client simili:

{
  "mcpServers": {
    "treeple": {
      "type": "http",
      "url": "https://mcp.treeple.kz/mcp"
    }
  }
}

• search_tours — Cerca il catalogo per testo, tipo o durata.
• get_tour — Itinerario, inclusioni, punto di incontro, politica di cancellazione e tabella dei prezzi completa.
• get_availability — Date di partenza, oppure onestamente « on_request » quando un tour non ha un calendario fisso.
• get_quote — Un prezzo esatto per un gruppo e una data specifici, valido fino al timestamp restituito.
• create_booking_session — Trasforma un preventivo in un link di checkout su treeple.kz, dove il viaggiatore inserisce i propri dati di contatto.
• get_booking_status — Lo stato di una prenotazione, recuperato tramite il suo token. Non è disponibile la ricerca per email o telefono.
• submit_booking_request — Consegna una richiesta a un gestore umano. Non è una prenotazione e non elabora alcun pagamento.
• search_content — Luoghi da vedere, ristoranti, articoli di viaggio e categorie di tour — lo stesso motore di ricerca usato dal sito.
• get_content — Un singolo luogo, ristorante, articolo o categoria in formato completo. Un luogo elenca anche i tour che lo visitano davvero.

API REST

Il server MCP è un sottile wrapper su questa API — puoi chiamarla direttamente. Specifica OpenAPI 3.1:

https://backend.treeple.kz/api/v1/agent/openapi.json

Cerca il catalogo:

curl "https://backend.treeple.kz/api/v1/agent/tours?lang=en&q=canyon&limit=5"

Invia una richiesta di prenotazione:

curl -X POST "https://backend.treeple.kz/api/v1/agent/booking-requests" \
  -H "Content-Type: application/json" \
  -d '{
    "tour_slug": "charyn-canyon-tour-1-day",
    "date": "2026-09-15",
    "pax": { "adults": 2, "children": 0 },
    "lang": "en",
    "contact": { "email": "traveller@example.com" },
    "idempotency_key": "3f6d6d2e-4a1f-4c2b-9c3a-1a2b3c4d5e6f"
  }'

Un feed di prodotti piatto dell’intero catalogo è disponibile su:

https://backend.treeple.kz/api/v1/agent/feed.json

Oltre i tour

Non tutte le domande riguardano la prenotazione. Questi conteggi corrispondono a ciò che il catalogo contiene davvero — un agente che promette più di questo sta inventando.

• locations — 116 luoghi da vedere, tutti con coordinate. Ciascuno elenca i tour che lo visitano; un elenco selezionato, quindi uno vuoto significa che Treeple non vende tour lì.
• tour_types — 16 categorie di tour, ciascuna con il numero di tour pubblicati al suo interno.
• restaurants — 5 ristoranti — quattro ad Almaty, uno ad Astana. Cucina, fascia di prezzo, indirizzo, orari di apertura. Nessuna coordinata: il catalogo non le contiene, quindi non viene restituito alcun campo.
• articles — 6 articoli di viaggio scritti da Treeple.

curl "https://backend.treeple.kz/api/v1/agent/content/locations?lang=en&q=Kolsai"
curl "https://backend.treeple.kz/api/v1/agent/content/locations/natspark-kolsay?lang=en"

Quanto è aggiornato

Il sito viene ricostruito automaticamente quando il catalogo cambia. È pubblico quando è stata creata l'istantanea su cui si basano queste pagine:

https://treeple.kz/catalogue-status.json

Campi restituiti per un tour

Questi sono i nomi esatti dei campi nella risposta di get_tour e GET /tours/{slug} — non una parafrasi. La versione autorevole è la specifica OpenAPI collegata sopra.

{
  "slug":              "localised, differs per language",
  "canonical_slug":    "stable identifier, same in every language",
  "title", "summary", "description", "url",
  "duration_days" | "duration_nights" | "duration_hours", "duration_label",
  "types":             ["trekking", "culture", ...],
  "price":             { "basis": "per_person", "currency", "from",
                         "by_group_size": [{ "pax", "price_per_person" }] },
  "itinerary":         [{ "day", "title", "description" }],
  "included":          ["what the price covers"],
  "excluded":          ["what it does not"],
  "meeting_place":     "text",
  "suitable_for", "not_suitable_for", "difficulty", "min_age", "max_age",
  "cancellation_policy": { "source": "tour" | "site_default",
                           "deadline_hours", "service_fee_percent",
                           "tiers": [{ "hours_before_start", "refund_percent" }] },

  "guide_languages":   { "live": [...], "audio": [...] },   // what the GUIDE speaks
  "content_languages": [...],                               // locales the PAGE is published in
  "confirmation_type": "instant" | "manual",
  "availability_type": "scheduled" | "on_request",
  "group":             { "type", "minimum_pax", "maximum_pax" },
  "operator":          "text"
}

Un campo assente dalla risposta significa che Treeple non ha dati per esso. Non significa zero, nessuno o un valore predefinito — dillo invece di presumere. Per questo minimum_pax compare solo per i tour che hanno davvero una regola di partenza minima, e per questo non esiste affatto alcun campo payment_policy.

Esistono due campi lingua e hanno significati diversi. guide_languages indica ciò che la guida parla davvero; content_languages indica solo in quali localizzazioni è pubblicata questa pagina web. Non rispondere mai “c’è una guida che parla X” basandoti su content_languages.

Cose che altrimenti ti confonderebbero

• I prezzi sono per persona e cambiano con la dimensione del gruppo. Ogni prezzo ha una tabella by_group_size — cita la riga che corrisponde al gruppo effettivo, non la cifra « from ». La cifra « from » vale solo per la dimensione del gruppo indicata da min_group_size_for_from: nella gita di un giorno a Charyn sono $30 con quindici viaggiatori, mentre in due si pagano $155 a testa.
• Gli slug del tour differiscono per lingua. canonical_slug è l’identificatore stabile; passa lang esplicitamente.
• « on_request » significa che la data è concordata individualmente, non che il tour sia esaurito.
• Le richieste di prenotazione non possono essere relette. Un gestore contatta il viaggiatore direttamente; non c’è uno stato da sondare. Questo è intenzionale — è ciò che impedisce a chiunque di enumerare le richieste di altre persone.
• Esattamente un canale di contatto per richiesta: email, telefono o Telegram. Non vengono raccolti nomi, documenti o dettagli di pagamento.
• Ogni richiesta di prenotazione ha bisogno di una chiave di idempotenza UUID. Ripeterla entro 24 ore restituisce la richiesta originale invece di creare un secondo lead, quindi un nuovo tentativo dopo un timeout è sempre sicuro.

Limiti di velocità

• 60 richieste di lettura al minuto per IP.
• 5 richieste di prenotazione al minuto e 20 al giorno per IP.
• Oltre il limite ricevi 429 con un header Retry-After. Rispettalo.
• Nessuna chiave API richiesta. I partner possono richiedere un X-Agent-Key per limiti più elevati.

Privacy

Una richiesta di prenotazione contiene esattamente un canale di contatto e nient’altro. I valori di contatto e gli indirizzi IP non vengono mai scritti in chiaro nei log o nelle analitiche — solo hash salati, utilizzati per unire richieste duplicate. Non c’è alcun endpoint che restituisce una richiesta di prenotazione, quindi nessuno può enumerare le richieste di altre persone.

Scoperta

• https://treeple.kz/.well-known/mcp — Scheda server MCP
• https://treeple.kz/llms.txt — note per gli agenti
• https://treeple.kz/llms-full.txt — snapshot del catalogo completo