الاتصال بخادم Validatar MCP

يوفّر Validatar خادم Model Context Protocol (MCP) يتيح لمساعدات الذكاء الاصطناعي وأدوات التطوير التفاعل مباشرة مع نسخة Validatar الخاصة بك. من خلال MCP، يمكنك تصفح الكتالوج، وإنشاء وتنفيذ الاختبارات، وتشغيل السكربتات، وإدارة البيانات الوصفية (metadata) — كل ذلك من داخل بيئة مدعومة بالذكاء الاصطناعي مثل Claude Code أو Cursor أو أي عميل متوافق مع MCP.

المتطلبات الأساسية

قبل الاتصال بخادم Validatar MCP:

• يجب أن تعمل نسخة Validatar لديك بإصدار يدعم MCP.
• يجب أن يمتلك حساب المستخدم لديك جلسة نشطة بصلاحيات مناسبة للأدوات التي تنوي استخدامها.
• تحتاج إلى عنوان URL الأساسي لنسخة Validatar الخاصة بك (مثل https://your-instance.cloud.validatar.com).
• يجب أن يدعم عميل الذكاء الاصطناعي لديك بروتوكول Model Context Protocol (MCP) عبر HTTP transport.

كيف يعمل MCP مع Validatar

بروتوكول Model Context Protocol هو معيار مفتوح يتيح لمساعدات الذكاء الاصطناعي التفاعل مع الأنظمة الخارجية من خلال مجموعة محددة من الأدوات. يطبّق Validatar خادم MCP يقوم بما يلي:

• يعمل عبر HTTP باستخدام نقل عديم الحالة (stateless transport).
• يوثّق الطلبات باستخدام بيانات جلسة Validatar الحالية الخاصة بك.
• يعرض مجموعة من أدوات القراءة والكتابة للتفاعل مع كتالوج البيانات والاختبارات والمشاريع والبيانات الوصفية.
• يتتبّع جميع عمليات الكتابة كإجراءات ذكاء اصطناعي (AI Actions) يمكن مراجعتها والتراجع عنها.

تهيئة الاتصال

نقطة النهاية (Endpoint)

يتوفر خادم MCP على العنوان التالي:

{your_validatar_instance_url}/core/mcp

بادئة /core هي مسار API الأساسي للتطبيق — وهي مطلوبة في جميع عناوين نقاط نهاية MCP.

المصادقة (Authentication)

يقوم خادم MCP بمصادقة الطلبات باستخدام رمز مستخدم Validatar (User Token) من نوع MCP. هذا الرمز ليس نفسه مفتاح API القياسي أو ملف تعريف ارتباط الجلسة (session cookie) — يجب عليك إنشاء رمز MCP مخصص في Validatar.

لإنشاء رمز MCP:

1. 1سجّل الدخول إلى نسخة Validatar الخاصة بك.
2. 2انتقل إلى إعدادات User Profile.
3. 3ضمن User Tokens، أنشئ رمزًا جديدًا واضبط نوعه (type) على MCP.
4. 4انسخ قيمة الرمز الذي تم إنشاؤه.

يتم تمرير الرمز إلى خادم MCP عبر ترويسة x-val-api-token:

x-val-api-token: <your-token>

أمثلة على تهيئة العملاء

Claude Code (سطر الأوامر CLI)

أسرع طريقة لإضافة خادم Validatar MCP إلى Claude Code هي باستخدام سطر الأوامر:

claude mcp add --transport http <your_validatar_instance_name> <your_validatar_instance_url>/core/mcp --header "x-val-api-token: <your-token>"

على سبيل المثال:

claude mcp add --transport http validatar-prod https://mycompany.cloud.validatar.com/core/mcp --header "x-val-api-token: abc123def456"

يقوم هذا بتسجيل الخادم في إعدادات Claude Code الخاصة بك ويجعل جميع أدوات Validatar MCP متاحة في جلساتك.

Claude Code (تهيئة يدوية)

بدلًا من ذلك، أضف الخادم مباشرة إلى ملف .claude/settings.json أو إعدادات المشروع:

{
  "mcpServers": {
    "validatar": {
      "type": "http",
      "url": "https://your-instance.cloud.validatar.com/core/mcp",
      "headers": {
        "x-val-api-token": "YOUR_MCP_TOKEN"
      }
    }
  }
}

Cursor

في ملف تهيئة MCP الخاص بـ Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "validatar": {
      "type": "http",
      "url": "https://your-instance.cloud.validatar.com/core/mcp",
      "headers": {
        "x-val-api-token": "YOUR_MCP_TOKEN"
      }
    }
  }
}

عميل MCP عام

يمكن لأي عميل متوافق مع MCP ويدعم نقل HTTP الاتصال. التهيئة المطلوبة هي:

التحقق من الاتصال

بعد التهيئة، تحقق من الاتصال بطلب من مساعد الذكاء الاصطناعي تنفيذ عملية قراءة بسيطة:

1. 1اطلب من المساعد سرد مشاريعك أو وصف مصدر بيانات معروف.
2. 2إذا نجح الاتصال، سيعيد المساعد نتائج من نسخة Validatar الخاصة بك.
3. 3إذا فشلت المصادقة، ستتلقى رسالة خطأ — تحقق من مفتاح API وعنوان النسخة (instance URL).

التحكم في الوصول إلى الأدوات

يمكن لمسؤولي Validatar التحكم في أي أدوات MCP متاحة لمستخدمين محددين من خلال التحكم في الوصول المستند إلى الرموز (token-based access control). إذا كانت إحدى الأدوات غير متاحة لك، تواصل مع مسؤول Validatar للتحقق من صلاحياتك.

تنقسم الأدوات إلى فئتين:

• أدوات القراءة فقط (Read-only tools) — تصفح عناصر الكتالوج، وسرد الاختبارات، والبحث في الوثائق.
• أدوات الكتابة (Write tools) — إنشاء الاختبارات، وتنفيذ السكربتات، وتحديث البيانات الوصفية، وإدارة المجلدات والمشاريع.

تتبع إجراءات الذكاء الاصطناعي والتراجع عنها

يتم تسجيل كل عملية كتابة تُنفَّذ عبر MCP كإجراء ذكاء اصطناعي (AI Action). يوفّر ذلك:

• سجل تدقيق كامل للتغييرات التي تمت عبر مساعدات الذكاء الاصطناعي.
• إمكانية التراجع عن أي تغيير بدأه الذكاء الاصطناعي باستخدام أداة revert_action.
• رؤية واضحة لما تم تغييره، ومتى، ومن قِبل أي جلسة مستخدم.

عند تنفيذ أداة كتابة بنجاح، تتضمن الاستجابة قيمة revert_action_key التي يمكن استخدامها للتراجع عن التغيير.

استكشاف الأخطاء وإصلاحها

الخطوات التالية

• راجع دليل MCP Tools Reference الكامل لفهم العمليات المتاحة.
• جرّب تصفح الكتالوج بطلب من المساعد وصف مصدر بيانات أو سرد الجداول في مخطط (schema).
• أنشئ أول اختبار لك بلغة طبيعية عن طريق وصف ما تريد التحقق منه.