AI एजेंटों के लिए Treeple

Treeple कजाखस्तान में निर्देशित पर्यटन चलाता है। यह पृष्ठ बताता है कि कैसे एक AI एजेंट कैटलॉग पढ़ सकता है और एक यात्री की ओर से एक मानव को बुकिंग अनुरोध सौंप सकता है। कोई पंजीकरण नहीं, कोई API कुंजी नहीं, कोई OAuth नहीं।

MCP सर्वर

Streamable HTTP पर एक दूरस्थ मॉडल संदर्भ प्रोटोकॉल सर्वर। किसी भी MCP-सक्षम क्लाइंट को यहां निर्देशित करें:

https://mcp.treeple.kz/mcp

Claude Desktop, Claude Code और समान क्लाइंटों के लिए:

{
  "mcpServers": {
    "treeple": {
      "type": "http",
      "url": "https://mcp.treeple.kz/mcp"
    }
  }
}
  • search_tours — पाठ, प्रकार या अवधि के आधार पर कैटलॉग खोजें।
  • get_tour — यात्रा कार्यक्रम, शामिलियाँ, बैठक बिंदु, रद्दीकरण नीति और पूर्ण मूल्य सारणी।
  • get_availability — प्रस्थान की तारीखें, या ईमानदारी से « on_request » जब किसी दौरे का कोई निश्चित कैलेंडर न हो।
  • get_quote — एक नामित समूह और तारीख के लिए सटीक मूल्य, जो उसके लौटाए गए टाइमस्टैम्प तक वैध रहता है।
  • create_booking_session — Treeple.kz पर एक कोट को चेकआउट लिंक में बदलता है, जहाँ यात्री अपने संपर्क विवरण दर्ज करता है।
  • get_booking_status — एक बुकिंग की स्थिति, उसके टोकन से देखी गई। ईमेल या फ़ोन से कोई खोज उपलब्ध नहीं है।
  • submit_booking_request — एक अनुरोध को एक मानव प्रबंधक के पास सौंपता है। बुकिंग नहीं है और कोई भुगतान प्रक्रिया नहीं करता है।
  • search_content — देखने योग्य स्थान, रेस्टोरेंट, यात्रा लेख और टूर श्रेणियाँ — वही खोज इंजन जिसे साइट उपयोग करती है।
  • get_content — एक स्थान, रेस्टोरेंट, लेख या श्रेणी पूरी जानकारी के साथ। एक स्थान उन टूरों को भी सूचीबद्ध करता है जो वास्तव में वहाँ जाते हैं।

REST API

MCP सर्वर इस API के ऊपर एक पतला आवरण है — आप इसे सीधे कॉल कर सकते हैं। OpenAPI 3.1 विनिर्देश:

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

कैटलॉग खोजें:

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

बुकिंग अनुरोध जमा करें:

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"
  }'

पूरी कैटलॉग का एक सपाट उत्पाद फीड यहाँ उपलब्ध है:

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

टूरों से आगे

हर सवाल बुकिंग के बारे में नहीं होता। ये संख्या वही हैं जो कैटलॉग में वास्तव में मौजूद हैं — इससे अधिक का वादा करने वाला एजेंट मनगढ़ंत बात कर रहा है।

  • locations — देखने के लिए 116 स्थान, सभी निर्देशांकों के साथ। प्रत्येक में वे टूर सूचीबद्ध हैं जो वहाँ जाते हैं; एक चयनित सूची, इसलिए खाली सूची का मतलब है कि Treeple वहाँ कोई टूर नहीं बेचता।
  • tour_types — 16 टूर श्रेणियाँ, जिनमें से प्रत्येक के पीछे प्रकाशित टूरों की संख्या दी गई है।
  • restaurants — 5 रेस्तरां — चार अल्माटी में, एक अस्ताना में। व्यंजन, मूल्य सीमा, पता, खुलने का समय। कोई निर्देशांक नहीं: कैटलॉग में वे उपलब्ध नहीं हैं, इसलिए कोई फ़ील्ड नहीं लौटाई जाती।
  • articles — Treeple द्वारा लिखे गए 6 यात्रा लेख।
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"

यह कितना नया है

कैटलॉग बदलते ही साइट अपने-आप फिर से बनाई जाती है। इन पृष्ठों के पीछे लिया गया स्नैपशॉट कब लिया गया था, यह सार्वजनिक है:

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

टूर के लिए लौटाए गए फ़ील्ड

ये get_tour और GET /tours/{slug} के response में exact field names हैं — कोई paraphrase नहीं। प्रामाणिक संस्करण ऊपर दिए गए OpenAPI specification में है।

{
  "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"
}

जो field response में absent है, उसका मतलब है कि Treeple के पास उसके लिए कोई data नहीं है। इसका मतलब zero, none, या default नहीं है — कृपया ऐसा ही बताएं, अनुमान न लगाएं। इसलिए minimum_pax केवल उन tours के लिए दिखता है जिनमें वास्तव में minimum-departure rule होता है, और payment_policy field बिल्कुल नहीं है।

दो language fields मौजूद हैं और उनका मतलब अलग है। guide_languages वह है जो guide वास्तव में बोलता है; content_languages केवल यह बताता है कि यह web page किन locales में प्रकाशित है। कभी भी content_languages से यह न बताएं कि “क्या कोई guide X बोलता है”।

चीजें जो अन्यथा आपको भ्रमित करेंगी

  • कीमतें प्रति व्यक्ति हैं और समूह के आकार के साथ बदलती हैं। प्रत्येक मूल्य एक by_group_size तालिका है — वास्तविक समूह से मेल खाने वाली पंक्ति का हवाला दें, « from » आकृति नहीं। « from » आंकड़ा केवल min_group_size_for_from वाले समूह आकार पर लागू होता है: चारिन के एक-दिवसीय दौरे में यह पंद्रह यात्रियों पर $30 है, जबकि दो लोग $155 प्रति व्यक्ति देते हैं।
  • पर्यटन की गतिविधियाँ भाषा के अनुसार भिन्न होती हैं। canonical_slug स्थिर पहचानकर्ता है; lang को स्पष्ट रूप से पास करें।
  • « on_request » का अर्थ है कि तारीख को व्यक्तिगत रूप से व्यवस्थित किया जाता है, न कि दौरा बेच दिया गया हो।
  • बुकिंग अनुरोधों को वापस नहीं पढ़ा जा सकता है। एक प्रबंधक यात्री से सीधे संपर्क करता है; कोई स्थिति पोल करने के लिए नहीं है। यह जानबूझकर है — यह है जो किसी को दूसरों के अनुरोधों की गणना करने से रोकता है।
  • प्रति अनुरोध बिल्कुल एक संपर्क चैनल: ईमेल, फोन या Telegram। कोई नाम, दस्तावेज़ या भुगतान विवरण एकत्र नहीं किए जाते हैं।
  • प्रत्येक बुकिंग अनुरोध के लिए एक UUID idempotency कुंजी की आवश्यकता होती है। इसे 24 घंटे के भीतर दोहराएं तो दूसरा लीड बनाने के बजाय मूल अनुरोध लौटाता है, इसलिए समय सीमा के बाद एक पुन: प्रयास हमेशा सुरक्षित है।

दर सीमा

  • प्रति IP प्रति मिनट 60 पढ़ने के अनुरोध।
  • प्रति IP प्रति मिनट 5 बुकिंग अनुरोध और प्रति दिन 20।
  • सीमा से अधिक आप को Retry-After हेडर के साथ 429 मिलता है। इसका सम्मान करें।
  • कोई API कुंजी आवश्यक नहीं है। भागीदार उच्च सीमा के लिए X-Agent-Key का अनुरोध कर सकते हैं।

गोपनीयता

एक बुकिंग अनुरोध बिल्कुल एक संपर्क चैनल ले जाता है और कुछ नहीं। संपर्क मान और IP पते कभी भी लॉग या विश्लेषण में स्पष्ट पाठ में नहीं लिखे जाते हैं — केवल नमकीन हैश, डुप्लिकेट अनुरोधों को विलय करने के लिए उपयोग किया जाता है। कोई समापन बिंदु नहीं है जो एक बुकिंग अनुरोध लौटाता है, इसलिए कोई भी दूसरों की पूछताछ की गणना नहीं कर सकता है।

खोज

सवाल, या किसी साथी एकीकरण के लिए उच्च दर सीमा की आवश्यकता है? को लिखो support@treeple.kz.