خادم MCP

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

تبحث عن النظرة العامة وأمثلة الموجّهات والاتصال بنقرة واحدة؟ راجع Crisphive MCP لـ Claude.

إنّه خادم بعيد مُستضاف — لا شيء لتثبيته أو تشغيله. وجّه عميلك إلى نقطة النهاية أدناه لتصبح متصلًا.

https://api.crisphive.com/mcp

جرّب هذه أولًا

اتصل (يكفي مفتاح sandbox من نوع chsk_test_) ثم الصق أيًا من هذه المطالبات مباشرة في وكيلك — تظهر المطالبات نفسها في كل قوائم Crisphive، لذا هذه هي تجربة التشغيل الأولى نفسها في كل مكان (تبقى المطالبات بالإنجليزية):

إنشاء مهمة — “Schedule a 2-hour HVAC job at 145 Laurier Ave W tomorrow for Marie Tremblay, 613-555-0142.” createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest
إدراج حالة طارئة — “Emergency plumbing job now at 99 Bank St for David Okafor (613-555-0198) — show me what gets rescheduled.” listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule
مخطط اليوم — “Outline my day tomorrow and flag anything at risk.” listJobRequests → getTechnicianSchedule
اكتشاف التوافر — “Find 3 hours this week for a bike ride with my wife without risking any jobs.” getTechnicianSchedule → يستنتج الوكيل الفسحة المتاحة في الجدول

الطلب نفسه، بلغتك

لا يهم المحرّكَ من يتحدث — المنسّق أو المالك أو المطوّر يقودون الأدوات نفسها. إليك الطلبات نفسها بصياغة كل دور كما يكتبها فعلًا (تبقى المطالبات بالإنجليزية):

حالة الاستخدام	المنسّق (المشغّل)	مالك النشاط	المطوّر
إنشاء مهمة	Schedule a 2-hour HVAC maintenance job at 145 Laurier Ave W tomorrow afternoon for Marie Tremblay (613-555-0142) and assign the closest available technician.	Book a 2-hour HVAC maintenance visit tomorrow afternoon at 145 Laurier Ave W for Marie Tremblay, 613-555-0142, with whoever can get there with the least drive time.	Create a job: 2h duration, location 145 Laurier Ave W, skill=HVAC_MAINT, window=tomorrow 12:00–17:00, customer=Marie Tremblay, phone=613-555-0142. Assign nearest qualified tech and return the placement rationale.
إدراج حالة طارئة	Insert an emergency P0 job right now at 99 Bank Street for David Okafor (613-555-0198) — burst pipe, needs a licensed plumber — and show me what gets rescheduled to make room.	David Okafor (613-555-0198) has a burst pipe emergency at 99 Bank Street. Get a licensed plumber there now and tell me which customers get bumped and how it affects today’s commitments.	Insert a P0 job now at 99 Bank St, customer=David Okafor, phone=613-555-0198, skill=PLUMBER_LICENSED. Run cascade reschedule and return the dual plan: jobs moved, new ETAs, and total SLA impact.
مخطط اليوم	Outline my schedule for tomorrow, flagging any tight travel windows or jobs at risk of running over.	Give me a plain-English rundown of tomorrow across all my crews — where the risks are, and whether we’re overcommitted anywhere.	Return tomorrow’s schedule for my crew as an ordered timeline with travel legs, slack per job, and any constraint violations or at-risk SLAs flagged.
اكتشاف التوافر	Find a 3-hour window in my work week when I can go on a bike ride with my wife without putting any jobs at risk.	When this week can I go on a bike ride with my wife without anything on the schedule slipping?	Query my week for a contiguous 3h personal block that keeps all jobs feasible — no SLA breaches, no cascade required. Return candidate windows ranked by schedule slack.
مطابقة المهارة ووقت التنقل	Which of my technicians certified for gas fitting are free Thursday morning within 20 minutes of Kanata?	Do I have anyone qualified for gas fitting who could realistically cover a Kanata job Thursday morning without wrecking their route?	List technicians with cert=GAS_FITTING, available Thursday 08:00–12:00, travel time ≤20 min to Kanata. Include current utilization per tech.

كيف يعمل

كل موجّه أعلاه يسلك المسار نفسه: يحوّل Claude اللغة الطبيعية إلى استدعاءات أدوات، ويقود خادم MCP واجهة REST API العامة نفسها التي يستخدمها أي عميل آخر، ويحسب مُحلِّل (solver) حتمي الجدول — بلا أي LLM داخل نواة التحسين. تتزامن النتائج مع نظام السجلات لدى النشاط التجاري.

مسار الموجّه عبر Crisphive: Claude، خادم MCP، واجهة REST API، المُحلِّل الحتمي، ونظام السجلات لدى مدير العمليات الميدانية.

المتطلبات

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

التثبيت

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

Run one command. Omit the header to authorize in your browser (OAuth), or pass an API key to skip the browser step:

# 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_ في تطبيق يعمل على جانب العميل.

هل تتصل بـ /mcp بمفتاح API؟ تنطبق مدة صلاحية المفتاح نفسها — تُختار عند الإنشاء (30 يومًا افتراضيًا، ومن 1 حتى 365)، وثابتة طوال عمر المفتاح. راجع المصادقة للاطلاع على إجراء التجديد.

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

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

الخطوة	الطلب
1. اكتشاف المورد	`GET /.well-known/oauth-protected-resource` (RFC 9728) → عنوان URL لخادم التفويض
2. اكتشاف الـ AS	`GET /.well-known/oauth-authorization-server` (RFC 8414) → نقاط النهاية؛ PKCE `S256` مطلوب؛ المنح `authorization_code` + `refresh_token`
3. التسجيل	`POST /oauth/register` (RFC 7591 التسجيل الديناميكي للعميل) → `client_id` (عميل عام، بلا سر — إذ إن PKCE هو الإثبات)
4. التفويض	`GET /oauth/authorize?…` — يسجّل مالك النشاط التجاري الدخول إلى Crisphive ويوافق
5. التبادل	`POST /oauth/token` (`grant_type=authorization_code` و`code` و`code_verifier`) → `{ access_token, refresh_token, expires_in }`
6. التجديد	`POST /oauth/token` (`grant_type=refresh_token`) → زوج رموز مُدوَّر (رمز التجديد القديم يُستخدم مرة واحدة فقط)

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

عمر الاتصال

يخضع اتصال MCP لساعتين مستقلتين. الوكيل المستخدم يوميًا لا يُفصل أبدًا وفق جدول؛ أمّا المنسي فتنتهي صلاحيته من تلقاء نفسه.

نافذة الخمول — 30 يومًا. يُصدر كل تجديد للرمز رمز تجديد جديدًا صالحًا لمدة 30 يومًا أخرى. واصل استخدام الاتصال فيتمدّد إلى ما لا نهاية؛ وتوقّف 30 يومًا فينقضي.
الحد الأقصى المطلق — 90 يومًا. بصرف النظر عن النشاط، ينتهي الاتصال بعد 90 يومًا من موافقة مالك النشاط التجاري عليه. يمكن للنشاط ضبط هذه المدة على أي قيمة من 1 إلى 365 يومًا لكل اتصال ضمن Developers → MCP connections؛ ويُحسب العدّ التنازلي من الموافقة الأصلية، لا من التغيير.

عند نفاد أيٍّ من الساعتين يفشل التجديد ويجب أن يوافق المالك على التطبيق مجددًا من شاشة الموافقة. تعامل مع أي فشل في التجديد على أنه «أعد بدء تدفق التفويض»، لا كخطأ قابل لإعادة المحاولة أبدًا. يُرسَل بريد إلكتروني إلى مالكي النشاط التجاري ومسؤوليه قبل 14 يومًا من انتهاء صلاحية الاتصال — فإعادة الموافقة تتطلب حضور المالك في متصفح، لذا يأتي التحذير أبكر مما هو للمفاتيح.

رموز التجديد أحادية الاستخدام: يُعيد كل تجديد رمزًا جديدًا، وتقديم رمز مُستخدم سابقًا يُبطل الاتصال بأكمله باعتباره اشتباهًا بسرقة الرمز. خزّن دائمًا أحدث رمز تجديد استلمته فقط.

الأدوات

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

المجموعة	الأدوات
العملاء مزامنة CRM، وعمليات CRUD كاملة	`listCustomers` · `createCustomer` · `getCustomer` · `updateCustomer` · `deleteCustomer`
الحجوزات الحجز والنقل والتتبّع	`listJobRequests` · `createJobRequest` · `getJobRequest` · `getJobRequestTimeline` · `listJobRequestBookingWindows` · `listJobRequestChanges` · `listCrewCandidates` · `listMatchingSlots` · `confirmJobRequest` · `updateJobPriority` · `quoteJobRequest` · `previewJobRequestMove` · `commitJobRequestMove` · `previewEmergencyReschedule` · `listEmergencyCandidates` · `commitEmergencyReschedule` · `listNearbyTechnicians` · `getTechnicianSchedule`
الكتالوج بيانات مرجعية + المهارات	`listJobTypes` · `getJobType` · `listSkills` · `listSkillCategories` · `listSkillsByCategory` · `listServiceAreas` · `getServiceArea` · `listTechnicianSkills` · `replaceTechnicianSkills`
الفريق والأسطول القائمة والعلاقات والأسطول	`listTechnicians` · `getTechnician` · `createTechnician` · `updateTechnician` · `deleteTechnician` · `listTechnicianAvailability` · `getTechnicianAvailability` · `replaceTechnicianBuddies` · `replaceTechnicianLeads` · `replaceTechnicianServiceAreas` · `replaceTechnicianVehicles` · `listVehicles` · `getVehicle` · `listBusinessGroups`

تُعيد كل أداة غلاف 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) — أصلِح الترويسة وأعِد الاتصال. المفتاح الذي تجاوز مدة صلاحيته يُعيد 401 مع API_KEY_EXPIRED — أنشئ مفتاحًا بديلًا. واتصال OAuth الذي انقضت منحته يُعيد OAUTH_GRANT_EXPIRED — أعد تشغيل تدفق التفويض من شاشة الموافقة.

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

أرسِل عبر 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 — المواصفة القابلة للقراءة آليًا التي تُولَّد منها الأدوات.