خادم MCP

خادم MCP الرسمي لـ CrispHive. وجّه Claude أو ChatGPT أو Cursor أو أي عميل MCP نحو CrispHive ليتمكّن من إدارة العملاء، وتصفّح كتالوج خدماتك، والتحقق من توفّر الجدولة الفعلي، وحجز الأعمال لنشاط تجاري ميداني الخدمة — كل نقطة نهاية REST في واجهة Developer API، مكشوفة كأداة.

https://api.crisphive.com/mcp

المتطلبات

أي عميل MCP يتحدّث مع الخوادم البعيدة عبر Streamable HTTP ويستطيع إرسال ترويسة مخصّصة — claude.ai وClaude Desktop وClaude Code وChatGPT وGemini CLI وCursor وVS Code وWindsurf وCline وZed وLM Studio وغيرها. النقل عديم الحالة (استجابات JSON صِرفة — لا SSE ولا جلسات) والخادم يكشف الأدوات فقط.

التثبيت

اختر عميلك أدناه لترى بالضبط كيفية ربطه:

# OAuth — you'll be prompted to authorize in the browser
claude mcp add --transport http crisphive https://api.crisphive.com/mcp

# …or pass an API key to skip the browser step
claude mcp add --transport http crisphive https://api.crisphive.com/mcp \
  --header "Authorization: Bearer chsk_test_YOUR_KEY"

المصادقة

تُصادَق الطلبات بمفتاح API سرّي يُرسَل كرمز حامل (bearer token) — المفتاح نفسه المستخدم في واجهة REST /v1 API. أنشئ المفاتيح من لوحة تحكم نشاطك التجاري في CrispHive. تحدّد بادئة المفتاح البيانات التي يعمل عليها الوكيل:

• chsk_live_… → البيانات الحيّة (الإنتاج).
• chsk_test_… → بيانات بيئة الاختبار (المعزولة). الوكيل الذي يحمل مفتاح اختبار لا يمكنه إطلاقًا المساس إلا ببيانات بيئة الاختبار — وهي الطريقة المُوصى بها لتركه يجرّب.

أبقِ المفتاح على الخادم وحمّله من البيئة — لا تُودِعه أبدًا ولا تشحن مفتاح chsk_ في تطبيق يعمل على جانب العميل.

OAuth 2.1 (بلا مفتاح API)

هل تبني موصّل claude.ai / ChatGPT — أو أي منتج يأتي فيه مستخدموك بنشاطهم التجاري الخاص في CrispHive؟ نقطة النهاية /mcp هي أيضًا خادم تفويض OAuth 2.1 كامل: يفوّض مالك النشاط التجاري وكيلك عبر شاشة موافقة، ولا يُنسخ أي مفتاح على الإطلاق. يشغّل العميل المتوافق مع MCP التدفق بأكمله تلقائيًا (لا تكتب عادةً أي كود OAuth)، ويُطلَق بواسطة رمز 401 يحمل WWW-Authenticate: Bearer resource_metadata="…":

من هناك، استدعِ /mcp مع Authorization: Bearer <access_token> — بشكل مطابق لمسار مفتاح API. الرمز مرتبط بنشاط المالك الموافِق ومنطقته وبيئته، فلا يستطيع الوكيل أبدًا الوصول إلى مستأجر آخر أو التبديل بين live↔sandbox. اطلب scope أضيق (رموز أذونات مفصولة بمسافات، مثل customers_view job_requests_view) لتقييد الوكيل؛ واحذفه للوصول الكامل إلى النشاط التجاري. تعيش رموز الوصول نحو ساعة واحدة — استخدم رمز التجديد لتبقى متصلًا.

الأدوات

هناك 22 أداة، واحدة لكل عملية في واجهة /v1 API العامة — بالأسماء نفسها لدوال SDK (listCustomers وcreateJobRequest و…)، مولَّدة من مواصفة OpenAPI نفسها بحيث لا يتباعد REST وMCP أبدًا. تُسطَّح معاملات المسار/الاستعلام وحقول متن الطلب في كائن وسيطات واحد لكل أداة.

• تُعيد كل أداة غلاف REST الخام — { error_code, message, data } — كنص؛ يفكّ الوكلاء data عند النجاح ويقرؤون error_code عند الفشل.
• المفاتيح المقيّدة تنطبق دون تغيير: المفتاح المحصور في customers_view يتلقّى 403 من أدوات الكتابة.
• تقبل أدوات الإنشاء (createCustomer وcreateJobRequest) وسيطًا اختياريًا باسم idempotency_key يُمرَّر كترويسة Idempotency-Key — مرّر القيمة نفسها عند إعادة المحاولة فلا تُنشئ إعادة المحاولة نسخة مكرّرة أبدًا.
• مُدخلات الترويسات وسيطات أيضًا: مثلًا تأخذ listJobRequestBookingWindows المعامل x_timezone (منطقة زمنية بمعيار IANA، تُرسَل كترويسة X-Timezone).
• تعلن كل أداة عن outputSchema وتُعيد structuredContent (الغلاف المُحلَّل) إلى جانب النص، فيتمكّن العملاء ذوو الأنواع المحدّدة من تخطّي إعادة التحليل.
• تُضبَط تلميحات السلوك لكل أداة — عمليات القراءة تحمل readOnlyHint وعمليات الحذف تحمل destructiveHint، فيتمكّن عملاء مثل Claude من السؤال قبل تنفيذ الإجراءات المدمِّرة.

يبدو تدفّق الوكيل النموذجي كالتالي:

listSkills / listJobTypes                → discover reference IDs
createCustomer                           → { customer_id }
listJobRequestBookingWindows             → offer only the returned windows
createJobRequest                         → booking created
getJobRequest / listJobRequestChanges    → track status

تقسيم الصفحات

تقبل أدوات السرد page / limit وتُعيد كائن meta (per_page وcurrent_page وtotal_pages)، فيتمكّن الوكيل من اجتياز مجموعات النتائج الكبيرة صفحةً تلو الأخرى.

حدود المعدّل

الطلبات محدودة المعدّل لكل مفتاح، ومشتركة مع REST: 240 في الدقيقة. عند غلاف 429، تراجَع وأعِد المحاولة.

الأخطاء

تُعيد كل أداة غلاف استجابة CrispHive (كنص وكـ structuredContent): تكون قيمة error_code هي 0 عند النجاح، أو سلسلة ثابتة عند الفشل (CUSTOMER_NOT_FOUND وAPI_KEY_INVALID و…). طابِق على الرمز، لا على نص الرسالة أبدًا. المفتاح غير الصالح أو المُبطَل يُعيد HTTP 401 (API_KEY_INVALID) — أصلِح الترويسة وأعِد الاتصال.

ملاحظات البروتوكول

• أرسِل عبر POST رسالة JSON-RPC 2.0 واحدة (أو دفعة من 20 كحدٍّ أقصى) لكل طلب؛ الاستجابات من نوع application/json، والإشعارات تُؤكَّد بـ 202.
• الخادم عديم الحالة — لا يُصدَر معرّف جلسة ولا يُشترط؛ وGET /mcp يُعيد 405 (لا يوجد بث دفعٍ من الخادم).
• يُتحقَّق من وسيطات المسار من نوع UUID قبل الإرسال — المعرّف الذي ليس UUID يُعيد خطأ أداة ضمن النطاق، لا عملية مختلفة أبدًا.
• مراجعات البروتوكول المقبولة: 2025-06-18 و2025-03-26 و2024-11-05.

التوثيق

• الأدلة — ابدأ من هنا للتعرّف على المفاهيم وتدفقات الحجز.
• مرجع API — كل نقطة نهاية ووسيط ومخطط.
• للذكاء الاصطناعي — مواصفة OpenAPI إضافة إلى موجّه تهيئة جاهز للّصق للمساعد.
• openapi.json — المواصفة القابلة للقراءة آليًا التي تُولَّد منها الأدوات.