خادم MCP (claude.ai / Claude Desktop / Code / Cursor) - وثائق Entity Enricher

خادم MCP (Claude Desktop / Code / Cursor)

يأتي Entity Enricher مزوّدًا بخادم Model Context Protocol مضمّن على /api/mcp — اعرض قائمة مخططاتك، وأثرِ كيانًا، وافحص النتيجة، وعالِج تحذير تصنيف كل ذلك من داخل محادثة Claude واحدة. دون الحاجة إلى محرّر لسير العمل.

لماذا MCP، بينما يوجد بالفعل n8n + Make؟

شكل مختلف، وحالة استخدام مختلفة. يغلّف موصّلا n8n وMake واجهة الـ API من أجل أتمتة سير العمل: المشغّلات، والتشغيلات المجدولة، والمسارات متعددة الخطوات، والحالة الدائمة. أما MCP فيغلّفها من أجل المحادثة التفاعلية: الأسئلة الفورية، وعمليات الإثراء الاستكشافية، والتوضيحات اللاحقة. سير العمل ذو طابع الدُفعات، والمحادثات ذات طابع الحوار — يختلف السطح وتختلف تجربة المستخدم.

الميزة الأبرز التي لا يفتحها سوى MCP: استئناف التصنيف التفاعلي. عندما يرفض مُصنِّف ما قبل التشغيل كيانك (مثلاً طلبت إثراء "Titan" مقابل مخطّط لكوكب، لكن Titan قمر)، يضطر n8n/Make إلى الإلغاء التلقائي لأنهما غير تفاعليين. أما MCP فيُظهِر التحذير إلى Claude، فيطلب منك Claude التأكيد، وعند "نعم" تُعاد الأداة دون المُصنِّف. لا فشل في منتصف المسار، ولا إعادة تشغيل من البداية.

البدء السريع

الخيار 1 — OAuth (مُوصى به)

لأجل claude.ai وClaude Code وCursor وأي عميل MCP يدعم مسار OAuth القياسي. لا حاجة لإنشاء مفتاح API أو لصقه — إذ يكتشف العميل خادم التفويض تلقائيًا.

  1. أضف Entity Enricher كموصِّل (في claude.ai: Settings → Connectors → Add custom connector، أو اختره من الدليل) باستخدام الرابط https://entityenricher.ai/api/mcp/.
  2. يفتح متصفحك شاشة الموافقة الخاصة بـ Entity Enricher — سجّل الدخول إن لزم الأمر ثم انقر Authorize. ويعمل الاتصال نيابةً عنك بدورك الخاص.
  3. يمكنك إدارة الاتصال أو إلغاؤه في أي وقت من API Keys → Connected Apps — ويؤدي الإلغاء إلى قطع الوصول فورًا.

الخيار 2 — مفتاح API (تهيئة JSON ثابتة)

للعملاء الذين يُضبطون عبر ملف JSON بدلًا من تسجيل دخول تفاعلي (Claude Desktop وContinue وZed).

  1. 1. إنشاء مفتاح API
    في واجهة الويب لـ Entity Enricher: الإعدادات ← مفاتيح API ← مفتاح وصول جديد للمؤسسة. اختر دورًا (مشغّل للقراءة غالبًا، محرِّر لإنشاء/تعديل المخططات، مالك للتحكم الكامل). انسخ قيمة ent_… — فهي تُعرض مرة واحدة فقط.
  2. 2. سجّل في عميل MCP الخاص بك

    بالنسبة إلى Claude Desktop، عدّل ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) أو %APPDATA%\Claude\claude_desktop_config.json (Windows):

    {
  "mcpServers": {
    "entityenricher": {
      "url": "https://entityenricher.ai/api/mcp/",
      "headers": { "X-API-Key": "ent_your_key_here" }
    }
  }
}

    أعد تشغيل Claude Desktop. يعمل المقتطف نفسه مع Claude Code وCursor وContinue وZed — أي عميل متوافق مع MCP.

جرّبه

في محادثة جديدة: "اعرض مخططات Entity Enricher الخاصة بي، ثم أثرِ Sanofi وفق مخطط شركة الأدوية باستخدام Claude Sonnet." يكتشف Claude الأدوات تلقائيًا، ويختار الأداة المناسبة، ويطلب منك تأكيد اختيار النموذج والمخطط، ويبث النتيجة ضمن المحادثة.

الأدوات

تغطي 29 أداة كامل مساحة الإثراء وتأليف المخططات. سلوكها مطابق لنقاط نهاية REST التي تغلّفها (التحقق نفسه، والفوترة نفسها، وحدود الخطة نفسها) — وعندما تحصل واجهة الويب على إصلاح، يحصل MCP عليه أيضًا. أما العمل الطويل الأمد (الإثراء بالدفعات، وتوليد العينات، وتشغيل المعايير المرجعية) فيتم بشكل غير متزامن: تُرجع أداة البدء job_id، ويستطلع Claude get_job_status، ثم يجلب المخرجات المحفوظة من سجلاتك بمجرد اكتمال المهمة.

الفئةأداةالوصف
الاكتشافlist_modelsعرض نماذج LLM المتاحة + profile_limits الخاصة بخطتك حتى يضبط Claude معدله ذاتيًا قبل بلوغ HTTP 402.
المخططاتlist_schemasعرض مخططات JSON المحفوظة في مؤسستك، المثبّتة أولًا.
المخططاتget_schemaجلب المحتوى الكامل للمخطط باستخدام UUID.
المخططاتgenerate_sampleولّد كيان عيّنة واقعيًا من وصف نوع الكيان — الخطوة الأولى الطبيعية قبل توليد المخطط. مع المرفقات، قد يتوقف المخطِّط التفاعلي مؤقتًا لطرح أسئلة توضيحية.
المخططاتcreate_schema_from_sampleولّد مخطط JSON من قاموس كيان عيّنة عبر LLM، مع إمكانية الاستناد إلى مستندات مصدرية مرفوعة (attachment_ids). تُحفظ النتيجة تلقائيًا.
المخططاتedit_schemaتعديل مخطط موجود باللغة الطبيعية. يعيد محتوى جديدًا + 5 اقتراحات للمتابعة.
المخططاتsave_schemaاحفظ مخططًا ألّفه Claude مباشرة — دون استدعاء LLM، ودون تكلفة، مع التحقق على جانب الخادم.
المخططاتupdate_schemaأعد تسمية مخطط محفوظ أو استبدل محتواه أو أعد وسمه أو ثبّته دون استدعاء LLM.
المخططاتdelete_schemaاحذف مخططًا محفوظًا حذفًا مؤقتًا حسب UUID.
الإثراءenrich_entityإثراء متعدد النماذج مع دمج تلقائي اختياري. يقبل قائمة attachment_ids اختيارية. تُعيد حالات عدم تطابق التصنيف استجابة غير خاطئة حتى يتمكّن Claude من مطالبة المستخدم بالتأكيد وإعادة المحاولة.
الإثراءstart_batch_enrichmentأثرِ ما يصل إلى 100 كيان بشكل غير متزامن — خط معالجة كامل لكل كيان مع دمج تلقائي. يُرجع job_id؛ وتصل النتائج إلى سجلاتك.
الإثراءfetch_entitiesاجلب مصفوفة JSON من الكيانات من خادم REST API خارجي على جانب الخادم (مصادقة bearer / api_key / basic) — يقترن بالإثراء بالدفعات.
الإثراءretry_expertisesأعد تشغيل نطاقات الخبرة الفاشلة فقط من سجلٍ ما، مع دمج القيم المستردة مجددًا — دون دفع مجدد مقابل ما نجح بالفعل.
الإثراءmerge_recordsادمج سجلين أو أكثر من السجلات الموجودة في نتيجة مدموجة واحدة — بناءً على القواعد أو باستخدام نموذج تحكيم LLM.
المهامget_job_statusاستطلع أي مهمة غير متزامنة (دفعة، توليد عينة، تشغيل معيار مرجعي): عدّادات التقدّم، والملخصات النهائية، وأسئلة التوضيح المعلّقة.
المهامcancel_jobألغِ مهمة معلّقة أو قيد التشغيل أو موقوفة مؤقتًا.
المهامanswer_job_questionأجب عن أسئلة التوضيح لمهمة موقوفة مؤقتًا واستأنفها — الجزء التفاعلي من generate_sample.
المعايير المرجعيةlist_benchmark_scenariosاعرض سيناريوهات المعايير المرجعية المحفوظة لديك (اختبارات إثراء قابلة لإعادة الاستخدام).
المعايير المرجعيةget_benchmark_scenarioسيناريو واحد مع نتائجه المسجَّلة لكل نموذج (الجودة / التكلفة / السرعة).
المعايير المرجعيةcreate_benchmark_scenarioأنشئ سيناريو: مخطط + كيان ثابت + استراتيجية + حَكَم تسجيل. يتطلب دور المالك + خطة تتضمن المعايير المرجعية.
المعايير المرجعيةupdate_benchmark_scenarioحدّث تعريف اختبار السيناريو أو إعداد التسجيل الخاص به؛ تُوسم النتائج الموجودة بأنها قديمة.
المعايير المرجعيةset_benchmark_referenceاحفظ المخرَج المرجعي الذهبي وضع علامة عليه بأنه مُتحقَّق منه — مطلوب قبل التشغيل.
المعايير المرجعيةdelete_benchmark_scenarioاحذف سيناريو ونتائجه.
المعايير المرجعيةrun_benchmarkشغّل سيناريو على قائمة نماذج محددة، أو على كل نموذج نشط للمزوّدين المختارين، أو على جميع النماذج النشطة — تُسجَّل كل نتيجة تلقائيًا مقابل المرجع.
السجلاتlist_recordsتصفّح السجلات السابقة مع عوامل تصفية حسب النوع والنجاح والنموذج والمهمة، وبحث نصي حر.
السجلاتget_recordمخرجات منظّمة كاملة + أخطاء التحقق لسجلّ واحد.
السجلاتget_statsإحصائيات مجمَّعة للمؤسسة: الإجماليات، ومعدل النجاح، والرموز، والتكلفة.
المرفقاتupload_attachmentرفع ملف base64 (filename، content_base64، media_type؟) وإرجاع معرّف المرفق الخاص به لاستخدامه في enrich_entity.
المرفقاتdelete_attachmentحذف مرفق حسب المعرّف — خطوة تنظيف مفيدة بعد الإثراء.

الموارد

تتيح الموارد لـ Claude تصفّح البيانات دون استهلاك استدعاء أداة — إذ يتعامل معها عميل LLM كأنها ملفات. ويُعرض كلا نوعَي الموارد بصيغة Markdown لعرض مضمَّن منخفض التكلفة.

قالب URIالوصف
enricher://schemas/{schema_id}مخطط محفوظ معروض بصيغة Markdown — ترويسة بيانات وصفية + GeneratedJsonSchema ككتلة JSON محاطة بأسوار.
enricher://records/{record_id}سجل إثراء سابق معروض بصيغة Markdown — بيانات وصفية + مخرجات منظَّمة + أخطاء تحقق.

الميزة الأبرز: استئناف التصنيف التفاعلي

عندما تطلب من enrich_entity استخدام نموذج تصنيف ولا تتطابق الكينونة مع نوع المخطط، تُعيد الأداة استجابة غير مخطئة مع تفاصيل مُهيكلة. يقرؤها Claude، ويُظهر لك سبب القرار، و(بعد تأكيدك) يعيد المحاولة باستخدام force_after_classification_warning=true — الذي يُسقط المُصنِّف عند إعادة المحاولة.

{
  "success": false,
  "error_code": "classification_warning",
  "message": "Pre-flight classification rejected the entity. ...",
  "classification": {
    "status": "mismatch",
    "reasoning": "Titan is a moon of Saturn, not a planet.",
    "confidence": 0.97
  },
  "job_id": "..."
}

يُلغي n8n وMake تلقائياً في هذه الحالة لأنهما لا يستطيعان سؤال المستخدم في منتصف سير العمل. أما MCP فيستطيع، وهذا الفرق الوحيد هو سبب وجود الموصّل.

يُشغِّل التفاعل نفسه تدفقًا ثانيًا: عندما يعمل generate_sample مع مستندات مصدرية، قد يتوقف مخطِّطه مؤقتًا لطرح أسئلة توضيحية بنيوية. ينقلها Claude إليك ويستأنف المهمة باستخدام answer_job_question — جولة تلو الأخرى، حتى يتم توليد العينة.

رموز الأخطاء

تُسقَط أخطاء الأدوات في قواميس منظّمة تحتوي على حقل error_code حتى يتمكّن Claude من مطابقة الأنماط بدلًا من تحليل النص الحر. تُطابَق طبقة HTTP بوضوح: 402 → خطأ في الحصة أو الرصيد، 422 → تحذير تصنيف، 504 → انتهاء المهلة، 502 → فشل LLM أعلى المصدر.

error_codeمتى
invalid_requestمعرّف UUID غير صالح، أو وسائط متنافية (schema_id + target_schema)، أو فشل التحقق من صحة نص الطلب.
prompt_limit_reachedاستُنفدت حصة الموجّهات اليومية / الأسبوعية / الشهرية (HTTP 402). يتضمّن المحتوى الفترة والحدّ والمستخدَم والمطلوب.
insufficient_creditsالمؤسسة قد فعّلت الفوترة لكن رصيدها منخفض جدًا لبدء المهمة (HTTP 402). يتضمن المتن الرصيد ورابط الشراء.
model_limit_exceededتم طلب عدد نماذج أكبر مما تسمح به الخطة (HTTP 402). يردّد الحد الأقصى والعدد المطلوب.
language_limit_exceededتم طلب عدد لغات أكبر مما تسمح به الخطة (HTTP 402).
concurrent_job_limit_reachedعدد كبير جدًا من مهام الإثراء النشطة لهذه المؤسسة. انتظر أو قم بترقية الخطة.
classification_warning⚡ ليست خطأً: رفض المصنّف التمهيدي الكيان. تحمل الاستجابة سياق التصنيف كي يتمكن Claude من طلب التأكيد من المستخدم وإعادة المحاولة باستخدام force_after_classification_warning=true.
benchmarks_not_in_planتتطلب أدوات المعايير المرجعية دور المالك وخطة تتضمن معايير النماذج المرجعية (HTTP 403).
enrichment_timeoutتجاوزت المهمة timeout_seconds. نقترح تقليل عدد النماذج أو تقسيم الكيان.
schema_generation_timeoutتجاوز توليد المخطط timeout_seconds.
schema_generation_failedخطأ في LLM المصدر أثناء توليد المخطط (HTTP 502).
cancelledأُلغيت المهمة أثناء التشغيل (HTTP 499).
not_foundمعرّف المخطط أو السجل غير موجود في مؤسستك.
http_errorمعالج شامل لأخطاء HTTP التي لا تحتوي على نص تفاصيل مهيكل.

إغفالات متعمَّدة

انظر أيضًا