Treeple для ИИ-агентов

MCP-сервер

Remote-сервер Model Context Protocol поверх 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 — Даты выездов — либо честное «под запрос», если расписания нет.
• get_quote — Точная цена под названный состав группы и дату, действует до указанного времени.
• create_booking_session — Превращает котировку в ссылку на оплату на treeple.kz, где путешественник сам оставляет контакт.
• get_booking_status — Состояние одной брони по её токену. Поиска по email или телефону нет.
• 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 — 6 статей, написанных 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"

Насколько это свежо

Сайт пересобирается автоматически, когда меняется каталог. Когда снят слепок, из которого сделаны эти страницы, видно публично:

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-ключ идемпотентности. Повтор с тем же ключом в течение суток возвращает исходную заявку, а не создаёт вторую, поэтому ретрай после таймаута безопасен.

Ограничения

• 60 запросов на чтение в минуту с одного IP.
• 5 заявок в минуту и 20 в сутки с одного IP.
• При превышении приходит 429 с заголовком Retry-After. Его нужно соблюдать.
• Ключ не требуется. Партнёры могут запросить X-Agent-Key для повышенных лимитов.

Приватность

Заявка содержит ровно один контакт и ничего больше. Контакт и IP никогда не попадают в логи и аналитику в открытом виде — только солёные хеши, нужные для склейки повторов. Эндпоинта, возвращающего заявку, не существует, поэтому перебрать чужие обращения невозможно.

Как нас найти

• https://treeple.kz/.well-known/mcp — карточка MCP-сервера
• https://treeple.kz/llms.txt — заметки для агентов
• https://treeple.kz/llms-full.txt — полный слепок каталога