Treeple ЖИ-агенттерге

MCP-сервер

Streamable HTTP үстіндегі Model Context Protocol remote-сервері. Кез келген 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 — Шығу күндері — немесе кесте болмаса, адал «сұраныс бойынша».
• 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"

Бұл қаншалықты жаңартылған

Сайт каталог өзгерген сайын автоматты түрде қайта құрылады. Осы беттерге негіз болған snapshot қашан алынғаны ашық көрсетіледі:

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

Тур бойынша қайтарылатын өрістер

Бұл — get_tour және GET /tours/{slug} жауабындағы өрістердің нақты атаулары, мазмұндама емес. Ақиқат көзі — жоғарыда сілтеме берілген OpenAPI спецификациясы.

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

Жауапта өріс болмаса, Treeple-де ол бойынша дерек жоқ дегені. Бұл нөл де, «жоқ» та, әдепкі мән де емес — ойдан шығармай, солай деп айтыңыз. Сондықтан minimum_pax тек ең аз топ ережесі шынымен бар турларда келеді, ал payment_policy өрісі мүлдем жоқ.

Тіл өрісі екеу және олар әртүрлі нәрсені білдіреді. guide_languages — гид шын мәнінде сөйлейтін тілдер; content_languages — тек осы беттің қай локальдерде жарияланғаны. «X тілінде сөйлейтін гид бар ма» деген сұраққа ешқашан content_languages бойынша жауап бермеңіз.

Әдетте қателесетін тұстар

• Баға бір адамға есептелген және топ мөлшеріне байланысты өзгереді. Әр жауапта by_group_size кестесі бар — «бастап» мәнін емес, нақты топқа сәйкес жолды айтыңыз. «Бастап» мәні тек min_group_size_for_from көрсеткен топ мөлшерінде жарамды: бір күндік Шарында бұл он бес адам болғанда $30, ал екеу болса — адам басына $155.
• Тур слагтары тілге қарай әртүрлі. Тұрақты идентификатор — canonical_slug; тілді анық беріңіз.
• «on_request» дегеніміз күн жеке келісіледі дегенді білдіреді, орын жоқ дегенді емес.
• Өтінімді кері оқу мүмкін емес. Менеджер саяхатшымен өзі байланысады, сұрап отыратын мәртебе жоқ. Бұл әдейі жасалған: дәл осылай бөгде өтінімдерді іріктеу мүмкін болмайды.
• Бір өтінімге дәл бір байланыс: email, телефон немесе Telegram. Есім, құжат және төлем деректері жиналмайды.
• Әр өтінімге UUID идемпотенттік кілті қажет. Тәулік ішінде сол кілтпен қайталау екінші өтінім жасамай, бастапқысын қайтарады, сондықтан таймаудтан кейінгі қайталау қауіпсіз.

Шектеулер

• Бір IP-ден минутына 60 оқу сұрауы.
• Бір IP-ден минутына 5 және тәулігіне 20 өтінім.
• Шектен асқанда Retry-After тақырыбымен 429 келеді. Оны сақтау керек.
• Кілт талап етілмейді. Серіктестер жоғары шектеулер үшін X-Agent-Key сұрай алады.

Құпиялылық

Өтінімде дәл бір байланыс бар, басқа ештеңе жоқ. Байланыс пен IP логтар мен аналитикаға ешқашан ашық түрде түспейді — тек қайталауларды біріктіруге қажет тұздалған хештер. Өтінімді қайтаратын эндпоинт жоқ, сондықтан бөгде өтініштерді іріктеу мүмкін емес.

Бізді қалай табуға болады

• https://treeple.kz/.well-known/mcp — MCP-сервер картасы
• https://treeple.kz/llms.txt — агенттерге арналған жазбалар
• https://treeple.kz/llms-full.txt — каталогтың толық сурауы