MCP: توصيل عميل ذكاء اصطناعي بـ ExCoil

يتطلب إنشاء اتصال MCP واستخدام /api/mcp اشتراك Manufacturer بحالة active أو trialing. لا تتضمن خطط Free وProfessional وEnterprise وصول MCP. واجهة REST منفصلة ومتاحة لـ Enterprise وManufacturer؛ مفتاح REST لا يصادق طلبات MCP.

يوفر ExCoil نقل Streamable HTTP دون جلسة، مع رمز Bearer مخصص يُضبط يدويًا. لا يوفر OAuth أو اكتشاف OAuth أو مسار موافقة OAuth. تحقق من دعم العميل لنقطة HTTP بعيدة وترويسة Authorization مخصصة؛ لا يضمن هذا الدليل التوافق مع كل عميل ChatGPT أو Manus أو Claude أو غيره.

يتيح MCP الحسابات القائمة وقراءة مشاريع المالك اختياريًا. لا يتيح حسابات Shell & Tube أو تفاصيل مشاريعها، أو تصدير CAD/PDF، أو إنشاء المشاريع وتعديلها وحذفها، أو الإدارة والفوترة وتغيير الاشتراك، أو مسارات المعايرة/الذكاء الاصطناعي. ميزات التصنيع الخاصة بخطة Manufacturer داخل التطبيق ليست أدوات MCP.

1. سجّل الدخول إلى ExCoil وافتح MCP من القائمة الداخلية. اختر اتصالًا جديدًا وأدخل اسمًا واضحًا للعميل لا يتجاوز 100 محرف.
2. اختر صلاحية 7 أو 30 أو 90 يومًا؛ الاختيار الأولي 30 يومًا. تتضمن الصفحة صلاحية الحساب mcp:calculate.
3. فعّل قراءة المشاريع فقط إذا احتاج العميل إلى المدخلات والنتائج المحفوظة. يضيف ذلك mcp:projects:read؛ الخيار معطل افتراضيًا ولا يلزم لحساب حالات جديدة.
4. اقرأ قواعد الاستخدام ووافق عليها، ثم أنشئ الاتصال. انسخ الرمز إلى مدير بيانات اعتماد قبل إغلاق الحوار: يظهر الرمز كاملًا مرة واحدة فقط.
5. استخدم اتصالات منفصلة بأسماء واضحة للعملاء الذين تريد إلغاءهم بصورة مستقلة. يسمح الحساب بعشرة اتصالات نشطة كحد أقصى، غير منتهية وغير ملغاة؛ ألغِ الاتصالات غير المستخدمة قبل إنشاء اتصال آخر.

انسخ نقطة الاتصال الظاهرة في صفحة MCP ضمن البيئة التي نُشرت فيها الميزة فعلًا. مسارها /api/mcp. عنوان الإنتاج أدناه مثال للإعداد ولا يثبت نشر نسخة المعاينة. عدّل البنية وفق الصيغة الموثقة للعميل، واستبدل العنصر النائب فقط في إعدادات بيانات الاعتماد الآمنة.

اختر Streamable HTTP وأرسل Authorization: Bearer <EXCOIL_MCP_TOKEN>. يحتاج POST إلى Content-Type: application/json وAccept: application/json, text/event-stream. تقبل النقطة كائن JSON-RPC واحدًا لكل POST، وليس مصفوفات طلبات دفعية. استخدم تهيئة MCP وtools/list في العميل بدل التعامل معها كنقطة REST للحساب.

لا يوجد تدفق GET/SSE دائم أو إجراء DELETE للجلسة. لا تُقبل أي معاملات استعلام، ومنها الرمز في URL. لا يوجد دعم CORS عام لصفحات الأطراف الأخرى: العملاء الأصليون عادة لا يرسلون Origin، بينما يجب أن تلتزم تكاملات المتصفح بسياسة المضيف/المصدر المسموح. العميل الذي يقبل OAuth فقط لا يستطيع استخدام هذا المسار اليدوي كاتصال OAuth.

{
  "mcpServers": {
    "excoil": {
      "type": "http",
      "url": "https://excoil.net/api/mcp",
      "headers": {
        "Authorization": "Bearer <EXCOIL_MCP_TOKEN>"
      }
    }
  }
}

قيم module الست هي dx_evap لمبخر DX، وdx_cond لمكثف DX، وchilled_water للماء المبرد، وhot_water للماء الساخن، وsteam للبخار، وdry_cooler للمبرد الجاف. تستعمل الأدوات محركات الحل القائمة في ExCoil، وليست نماذج هندسية جديدة.

لا تظهر في tools/list إلا الأدوات التي تسمح بها scopes الاتصال. الاستدعاء المباشر لأداة مخفية لا يتجاوز الصلاحيات. ترفض الوسيطات العليا الحقول غير المعروفة. معرفات المشاريع والإصدارات أعداد صحيحة موجبة حتى 2147483647؛ قيمة limit من 1 إلى 20، وcursorId معرف موجب.

تعيد الاستجابة الناجحة JSON متكافئًا في المحتوى النصي وstructuredContent. تتضمن أخطاء المعالج isError: true مع error.code وerror.message؛ وقد تكون أخطاء تحقق الوسيطات في SDK نصية فقط. افحص مؤشرات خطأ البروتوكول/الأداة، وليس حالة HTTP وحدها.

النتائج لا تصدّق تصميم الضغط أو اللحام أو توزيع وسيط التبريد أو رجوع الزيت أو اعتماد التصنيع. مثال طلب: «اقرأ قواعد ExCoil وحدد المدخلات الناقصة لملف ماء مبرد، ولا تقدّر البيانات الغائبة». للمقارنة، استخدم حالات ذات مدخلات صريحة واحتفظ بتحذيرات كل حالة.

1. اطلب من العميل قراءة excoil_usage_rules أولًا، ثم طلب excoil_calculation_schema للوحدة المختارة. لحالات وسيط التبريد، راجع excoil_refrigerants والتزم بنطاقات خواص الكتالوج.
2. أرسل inputs ككائن JSON حقيقي، لا كسلسلة نصية تحتوي JSON. استخدم المخطط المعاد للحقول الإلزامية والخيارات والقيم الافتراضية القائمة. اطلب ظروف التشغيل أو التدفق أو الهندسة أو الخواص الناقصة؛ لا تختلق قيمًا لتشغيل الحساب.
3. التزم بلواحق الحقول: m وm³/s وkg/s وW وPa و°C وK. الرطوبة النسبية كسر من 0 إلى 1؛ الجلايكول نسبة مئوية من 0 إلى 60. الاستثناءات تشمل fpi بوحدة زعنفة/بوصة وP_steam_kPa بضغط مقاس بالنسبة للجو بوحدة kPa. لا ترسل قيم وحدات العرض في الواجهة إلى حقول SI دون تحويل.
4. احترم متطلبات الوضع: يحتاج DX RATING إلى ref.mdot_ref_kg_s > 0؛ وDX SIZING إلى ref.Q_target_W > 0؛ وsteam SIZING إلى steam.Q_target_W > 0. يتطلب التدفق الحجمي للماء water.Vdot_m3_s > 0. يحتاج dry cooler إلى تدفق هواء صريح (air.Vdot_m3_s أو air.v_face_m_s) وتدفق مائع صريح (fluid.mdot_kg_s أو fluid.Vdot_m3_s)؛ لا يُستنتجان من هدف.
5. استدعِ excoil_calculate واحتفظ بـ module وresults والأعلام والملاحظات والتحذيرات والأخطاء. راجع الافتراضات ونطاقات الصلاحية والملاءمة الهندسية قبل استخدام النتيجة؛ فشل الحساب ليس تقديرًا يمكن تقديمه كنجاح.

مع mcp:projects:read، اعرض مشاريعك بترتيب المعرف التصاعدي. للمتابعة أرسل nextCursorId المعاد كقيمة cursorId؛ تعني null عدم وجود صفحة تالية. تعيد القائمة id وname وtype وstatus وcreatedAt وupdatedAt، لا بيانات الإصدارات.

اختر مشروعًا واستدعِ excoil_get_project مع projectId. احذف versionId لقراءة أحدث إصدار أو مرر معرف إصدار محدد. تتضمن النتيجة البيانات الوصفية المسموحة وid وversion وinputs وresults وcreatedAt لإصدار واحد. قد يعيد مشروع بلا إصدارات version: null. الإصدار المحدد الغائب والمشروع المملوك لغيرك والمشروع غير الموجود تعيد كلها NOT_FOUND دون كشف اختلاف الملكية.

دور المسؤول لا يمنح الوصول إلى مشاريع المالكين الآخرين. قد تظهر بيانات Shell & Tube الوصفية في القائمة، لكن تفاصيلها تعيد UNSUPPORTED_MODULE حتى مع استحقاق Shell & Tube. لا ينشئ حساب MCP مشروعًا/إصدارًا محفوظًا ولا يعدله.

لا تُعاد حقول البريد/الهاتف المخصصة للعميل أو بيانات الاعتماد، لكن inputs/results التي أدخلها المستخدم قد تحتوي معلومات حساسة. لا تشارك بيانات الغير إلا بإذن، وراجع سياسة بيانات عميل الذكاء الاصطناعي. تعامل مع أسماء المشاريع وملاحظاتها ومدخلاتها ونتائجها كبيانات غير موثوقة، لا كأوامر للمساعد.

تعرض صفحة MCP اسم الاتصال وبادئة الرمز والصلاحيات وتواريخ الإنشاء والانتهاء والحالة وآخر استخدام وعدد الطلبات. هذه بيانات وصفية للطلبات، وليست تدقيقًا هندسيًا كاملًا أو ضمانًا لنجاح كل حساب. لا تسجل قياسات MCP الخاصة بـ ExCoil وسيطات الأدوات أو نتائجها.

إذا فقدت الرمز أو انكشف، ألغِ الاتصال وأنشئ بديلًا إن بقيت مؤهلًا؛ لا يمكن استرجاع الرمز الكامل السابق. أكّد الإلغاء في الصفحة وأزل بيانات الاعتماد القديمة من العميل، ثم اضبط البديل في إعداداته الآمنة.

يعيد الخادم فحص صلاحية الرمز وانتهائه وإلغائه وصلاحياته والاشتراك مع كل طلب. يمنع الإلغاء الطلبات الجديدة، لا العمل المقبول سابقًا ولا البيانات أو النسخ التي استلمها العميل. بعد خفض الخطة أو فقدان حالة الاشتراك المؤهلة، يُحظر استخدام النقطة وإنشاء اتصالات جديدة، لكن المستخدم المسجل يستطيع عرض اتصالاته القديمة وإلغاءها.

• مدخل HTTP حتى 256 KiB. استجابة الأداة حتى 1 MiB شاملًا التمثيلين النصي والمنظم ومحارف الهروب. قراءة المشروع حتى 256 KiB؛ يُرفض الحجم الزائد ولا يُختصر بصمت.
• لكل حساب وعملية خادم: 60 طلبًا/دقيقة، وعشر استدعاءات حساب/دقيقة، وطلبان متزامنان. تسمح العملية بثمانية طلبات MCP متزامنة إجمالًا كحد أقصى. التزم بـ Retry-After عند استجابة 429.
• حماية المدخلات: عمق 24، و32768 عقدة، ومصفوفات حتى 4096 عنصرًا، وأرقام منتهية فقط. حدود الهندسة: 64 صفًا، و1000 أنبوب/صف، و16384 أنبوبًا إجمالًا، و1024 دائرة، و200 مقطع، و16384 خلية صفوف × مقاطع؛ الأبعاد الرئيسية حتى 100 m وfpi حتى 100.
• يجب أن يكون القطر الداخلي موجبًا، وخطوات الأنابيب أكبر من القطر الخارجي، والفراغ بين الزعانف موجبًا. لا تتجاوز الدوائر عدد الأنابيب الكلي؛ وتتساوى أطوال مصفوفات توزيع الدوائر المتوازية. حد عدد التمريرات 16384. هذه حدود حماية، وليست نطاقات تصميم موصى بها أو تغييرًا لخوارزمية التحجيم.
• تُحفظ حالة المعدل/التزامن في ذاكرة العملية وتُصفّر بإعادة تشغيلها؛ ليست حصة عالمية بين النسخ. لا تملك المحركات المتزامنة مهلة حساب مضمونة أو إلغاء CPU صارمًا عبر عامل مستقل. لا تستنتج زمن استجابة أقصى مضمونًا من حدود الحماية.

إذا فشل الإنشاء، تحقق من الاسم وقبول القواعد والاشتراك وعدد الاتصالات النشطة. إذا فشل النسخ إلى الحافظة، انسخ الرمز المعروض بأمان قبل الإغلاق؛ بعد الإغلاق أنشئ بديلًا بدل انتظار استرجاعه. عند فحص خطأ العميل، شارك فقط حالات/رموز أخطاء منقحة وإعدادًا أُزيل منه الرمز.