Treeple para agentes de IA

Servidor MCP

Um servidor remoto do protocolo de contexto de modelo sobre HTTP Streamable. Aponte qualquer cliente compatível com MCP para:

https://mcp.treeple.kz/mcp

Para Claude Desktop, Claude Code e clientes similares:

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

• search_tours — Pesquise o catálogo por texto, tipo ou duração.
• get_tour — Itinerário, inclusões, ponto de encontro, política de cancelamento e tabela de preços completa.
• get_availability — Datas de partida, ou honestamente « on_request » quando um tour não tem calendário fixo.
• get_quote — Um preço exato para um grupo e data específicos, válido até o timestamp que retorna.
• create_booking_session — Converte uma cotação em um link de checkout em treeple.kz, onde o viajante insere os próprios dados de contato.
• get_booking_status — O estado de uma reserva, consultado pelo seu token. Não há consulta por e-mail ou telefone.
• submit_booking_request — Entrega uma solicitação a um gerente humano. Não é uma reserva e não processa nenhum pagamento.
• search_content — Locais para visitar, restaurantes, artigos de viagem e categorias de tours — o mesmo mecanismo de busca que o site usa.
• get_content — Um local, restaurante, artigo ou categoria completo. Um local também lista os tours que realmente o visitam.

API REST

O servidor MCP é um invólucro fino sobre esta API — você pode chamá-la diretamente. Especificação OpenAPI 3.1:

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

Pesquise o catálogo:

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

Envie uma solicitação de reserva:

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

Um feed de produtos plano de todo o catálogo está disponível em:

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

Além dos tours

Nem toda pergunta é sobre reserva. Estes números mostram o que o catálogo realmente tem — um agente que promete mais do que isso está inventando.

• locations — 116 locais para visitar, todos com coordenadas. Cada um lista os tours que o visitam; uma lista curada, então uma vazia significa que a Treeple não vende nenhum tour lá.
• tour_types — 16 categorias de tours, cada uma com o número de tours publicados atrás dela.
• restaurants — 5 restaurantes — quatro em Almaty, um em Astana. Cozinha, faixa de preço, endereço, horário de funcionamento. Sem coordenadas: o catálogo não as possui, portanto nenhum campo é retornado.
• articles — 6 artigos de viagem escritos pela 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"

Quão atual é isto

O site é reconstruído automaticamente quando o catálogo muda. Quando foi feita a captura por trás destas páginas é público:

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

Campos retornados para um tour

Estes são os nomes exatos dos campos na resposta de get_tour e GET /tours/{slug} — não uma paráfrase. A versão autoritativa é a especificação OpenAPI vinculada acima.

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

Um campo ausente da resposta significa que a Treeple não tem dados para ele. Isso não significa zero, nenhum ou um valor padrão — diga isso em vez de assumir. É por isso que minimum_pax aparece apenas para tours que realmente têm uma regra de partida mínima, e por que não existe nenhum campo payment_policy.

Existem dois campos de idioma e eles têm significados diferentes. guide_languages é o que o guia realmente fala; content_languages indica apenas em quais locais esta página da web está publicada. Nunca responda “há um guia que fala X” com base em content_languages.

Coisas que de outra forma te confundiriam

• Os preços são por pessoa e mudam com o tamanho do grupo. Cada preço possui uma tabela by_group_size — cite a linha que corresponde ao grupo real, não a figura « from ». O valor « from » só vale para o tamanho de grupo de min_group_size_for_from: no passeio de um dia a Charyn são $30 com quinze viajantes, enquanto duas pessoas pagam $155 cada.
• Os slugs de tour diferem por idioma. canonical_slug é o identificador estável; passe lang explicitamente.
• « on_request » significa que a data é combinada individualmente, não que o tour esteja esgotado.
• As solicitações de reserva não podem ser relidas. Um gerente contatará o viajante diretamente; não há status para consultar. Isto é intencional — é o que impede qualquer pessoa de enumerar as solicitações de outras pessoas.
• Exatamente um canal de contato por solicitação: e-mail, telefone ou Telegram. Nenhum nome, documentos ou detalhes de pagamento são coletados.
• Cada solicitação de reserva precisa de uma chave de idempotência UUID. Repeti-la dentro de 24 horas retorna a solicitação original em vez de criar um segundo lead, portanto uma nova tentativa após um tempo limite é sempre segura.

Limites de taxa

• 60 solicitações de leitura por minuto por IP.
• 5 solicitações de reserva por minuto e 20 por dia por IP.
• Acima do limite você recebe 429 com um cabeçalho Retry-After. Respeite-o.
• Nenhuma chave API obrigatória. Os parceiros podem solicitar uma X-Agent-Key para limites mais altos.

Privacidade

Uma solicitação de reserva carrega exatamente um canal de contato e nada mais. Valores de contato e endereços IP nunca são escritos em texto claro em logs ou análises — apenas hashes salgados, utilizados para mesclar solicitações duplicadas. Não há um endpoint que retorna uma solicitação de reserva, portanto ninguém pode enumerar as consultas de outras pessoas.

Descoberta

• https://treeple.kz/.well-known/mcp — Cartão do servidor MCP
• https://treeple.kz/llms.txt — notas para agentes
• https://treeple.kz/llms-full.txt — snapshot completo do catálogo