Treeple للوكلاء الذين يعملون بالذكاء الاصطناعي

خادم MCP

خادم 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 — تواريخ المغادرة، أو بصراحة « on_request » عندما لا يكون لدى الرحلة تقويم ثابت.
• get_quote — سعر دقيق لمجموعة محددة وتاريخ محدد، صالح حتى الطابع الزمني الذي يعيده.
• create_booking_session — يحوّل عرض السعر إلى رابط دفع على treeple.kz، حيث يُدخل المسافر بيانات التواصل الخاصة به.
• get_booking_status — حالة حجز واحد، تُسترجع عبر رمزه. لا يوجد بحث عبر البريد الإلكتروني أو الهاتف.
• submit_booking_request — يسلم طلب إلى مدير بشري. ليست حجز وليست معالجة دفع.
• search_content — أماكن للزيارة، مطاعم، مقالات سفر وفئات جولات — نفس محرك البحث الذي يستخدمه الموقع.
• get_content — مكان واحد، مطعم، مقال أو فئة بالكامل. كما يعرض المكان الجولات التي تزوره فعليًا.

API REST

خادم 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 — اذكر الصف المطابق للمجموعة الفعلية.
• تختلف رحلة الأثار حسب اللغة. canonical_slug هو معرف مستقر؛ تمرير lang بشكل صريح.
• « on_request » يعني أن التاريخ يتم ترتيبه بشكل فردي وليس أن الرحلة مباعة.
• لا يمكن إعادة قراءة طلبات الحجز. يتصل مدير بالمسافر مباشرة؛ لا توجد حالة للاستطلاع. هذا مقصود — إنه ما يمنع أي شخص من تعداد طلبات الآخرين.
• قناة اتصال واحدة بالضبط لكل طلب: بريد إلكتروني أو هاتف أو Telegram. لا يتم جمع الأسماء أو المستندات أو تفاصيل الدفع.
• يحتاج كل طلب حجز إلى مفتاح idempotency UUID. تكراره خلال 24 ساعة يعيد الطلب الأصلي بدلاً من إنشاء عملية بيع ثانية، لذا فإن إعادة المحاولة بعد انتهاء المهلة الزمنية آمنة دائماً.

حدود معدل

• 60 طلب قراءة في الدقيقة لكل IP.
• 5 طلبات حجز في الدقيقة و20 في اليوم لكل IP.
• فوق الحد، تحصل على 429 برأس Retry-After. احترمها.
• لا يلزم مفتاح API. يمكن للشركاء طلب X-Agent-Key للحصول على حدود أعلى.

الخصوصية

يحمل طلب الحجز قناة اتصال واحدة بالضبط ولا شيء آخر. لا تُكتب قيم الاتصال وعناوين IP أبداً في النصوص في السجلات أو التحليلات — فقط hashes المملحة، المستخدمة لدمج الطلبات المكررة. لا توجد نقطة نهاية تعيد طلب حجز، لذا لا يمكن لأحد تعداد استفسارات الآخرين.

الكشف

• https://treeple.kz/.well-known/mcp — بطاقة خادم MCP
• https://treeple.kz/llms.txt — ملاحظات للوكلاء
• https://treeple.kz/llms-full.txt — لقطة الكتالوج الكاملة