بروتوكول سياق النموذج (MCP)

ما الذي يمكنه القيام به؟

WebdriverIO MCP هو خادم بروتوكول سياق النموذج (MCP) يمكّن مساعدي الذكاء الاصطناعي مثل Claude Desktop و Claude Code من أتمتة التفاعل مع متصفحات الويب وتطبيقات الجوال.

لماذا WebdriverIO MCP؟

• الأولوية للجوال: على عكس خوادم MCP المخصصة للمتصفح فقط، يدعم WebdriverIO MCP أتمتة تطبيقات iOS وAndroid الأصلية عبر Appium
• محددات عبر المنصات: يقوم اكتشاف العناصر الذكي بإنشاء استراتيجيات تحديد متعددة (معرّف الوصول، XPath، UiAutomator، شروط iOS) تلقائيًا
• نظام بيئي WebdriverIO: مبني على إطار عمل WebdriverIO المختبر جيدًا مع نظامه البيئي الغني من الخدمات والمراسلين

يوفر واجهة موحدة لـ:

• 🖥️ متصفحات سطح المكتب (Chrome - في وضع الواجهة أو الوضع غير المرئي)
• 📱 تطبيقات الجوال الأصلية (محاكيات iOS / محاكيات Android / الأجهزة الحقيقية عبر Appium)
• 📳 تطبيقات الجوال الهجينة (التبديل بين سياق الأصلي و WebView عبر Appium)

من خلال حزمة @wdio/mcp.

هذا يسمح لمساعدي الذكاء الاصطناعي بـ:

• إطلاق والتحكم في المتصفحات بأبعاد قابلة للتكوين، وضع بدون واجهة، وإمكانية التنقل الأولي الاختياري
• تصفح المواقع والتفاعل مع العناصر (النقر، الكتابة، التمرير)
• تحليل محتوى الصفحة عبر شجرة إمكانية الوصول واكتشاف العناصر المرئية مع دعم تقسيم الصفحات
• التقاط لقطات الشاشة محسّنة تلقائيًا (تغيير الحجم، ضغط إلى حد أقصى 1 ميجابايت)
• إدارة ملفات تعريف الارتباط للتعامل مع الجلسات
• التحكم في أجهزة الجوال بما في ذلك الإيماءات (النقر، التمرير، السحب والإفلات)
• تبديل السياقات في التطبيقات الهجينة بين الأصلي و webview
• تنفيذ البرامج النصية - JavaScript في المتصفحات، أوامر Appium للجوال على الأجهزة
• التعامل مع ميزات الجهاز مثل التدوير، لوحة المفاتيح، تحديد الموقع الجغرافي
• والكثير غير ذلك، راجع خيارات الأدوات و التكوين

معلومات

ملاحظة لتطبيقات الجوال تتطلب أتمتة الجوال تشغيل خادم Appium مع تثبيت برامج التشغيل المناسبة. انظر المتطلبات المسبقة للحصول على تعليمات الإعداد.

التثبيت

أسهل طريقة لاستخدام @wdio/mcp هي عبر npx بدون أي تثبيت محلي:

npx @wdio/mcp

أو تثبيته عالميًا:

npm install -g @wdio/mcp

الاستخدام مع Claude

لاستخدام WebdriverIO MCP مع Claude، قم بتعديل ملف التكوين:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

بعد إضافة التكوين، أعد تشغيل Claude. ستكون أدوات WebdriverIO MCP متاحة لمهام أتمتة المتصفح والجوال.

الاستخدام مع Claude Code

يكتشف Claude Code خوادم MCP تلقائيًا. يمكنك تكوينه في ملف .claude/settings.json أو .mcp.json الخاص بمشروعك.

أو أضفه إلى .claude.json عالميًا عن طريق تنفيذ:

claude mcp add --transport stdio wdio-mcp -- npx -y @wdio/mcp

تحقق منه عن طريق تشغيل أمر /mcp داخل claude code.

أمثلة البداية السريعة

أتمتة المتصفح

اطلب من Claude أتمتة مهام المتصفح:

"افتح Chrome وانتقل إلى https://webdriver.io"
"انقر على زر 'Get Started'"
"التقط لقطة شاشة للصفحة"
"ابحث عن جميع الروابط المرئية في الصفحة"

أتمتة تطبيقات الجوال

اطلب من Claude أتمتة تطبيقات الجوال:

"ابدأ تطبيق iOS الخاص بي على محاكي iPhone 15"
"انقر على زر تسجيل الدخول"
"اسحب لأعلى للتمرير لأسفل"
"التقط لقطة شاشة للشاشة الحالية"

القدرات

أتمتة المتصفح (Chrome)

الميزة	الوصف
إدارة الجلسات	تشغيل Chrome في وضع الواجهة/بدون واجهة مع أبعاد مخصصة وعنوان URL اختياري للتنقل
التنقل	الانتقال إلى عناوين URL
التفاعل مع العناصر	النقر على العناصر، كتابة النص، البحث عن العناصر بواسطة محددات مختلفة
تحليل الصفحة	الحصول على العناصر المرئية (مع تقسيم الصفحات)، شجرة الوصول (مع التصفية)
لقطات الشاشة	التقاط لقطات الشاشة (محسنة تلقائيًا إلى حد أقصى 1 ميجابايت)
التمرير	التمرير لأعلى/لأسفل بمقادير بكسل قابلة للتكوين
إدارة ملفات تعريف الارتباط	الحصول على وتعيين وحذف ملفات تعريف الارتباط
تنفيذ البرامج النصية	تنفيذ JavaScript مخصص في سياق المتصفح

أتمتة تطبيقات الجوال (iOS/Android)

الميزة	الوصف
إدارة الجلسات	تشغيل التطبيقات على المحاكيات أو الأجهزة الحقيقية
إيماءات اللمس	النقر، التمرير، السحب والإفلات
اكتشاف العناصر	اكتشاف العناصر الذكي مع استراتيجيات تحديد متعددة وتقسيم الصفحات
دورة حياة التطبيق	الحصول على حالة التطبيق (عبر execute_script للتنشيط/الإنهاء)
تبديل السياق	التبديل بين سياقات الأصلي و webview في التطبيقات الهجينة
التحكم في الجهاز	تدوير الجهاز، التحكم في لوحة المفاتيح
تحديد الموقع الجغرافي	الحصول على وتعيين إحداثيات GPS للجهاز
الأذونات	التعامل التلقائي مع الأذونات والتنبيهات
تنفيذ البرامج النصية	تنفيذ أوامر Appium للجوال (pressKey, deepLink, shell، إلخ)

المتطلبات المسبقة

أتمتة المتصفح

• يجب تثبيت Chrome على نظامك
• يتعامل WebdriverIO مع إدارة ChromeDriver الآلية

أتمتة الجوال

iOS

1. تثبيت Xcode من Mac App Store
2. تثبيت أدوات سطر أوامر Xcode:

   xcode-select --install

3. تثبيت Appium:

   npm install -g appium

4. تثبيت برنامج تشغيل XCUITest:

   appium driver install xcuitest

5. بدء خادم Appium:

   appium

6. للمحاكيات: افتح Xcode → Window → Devices and Simulators لإنشاء/إدارة المحاكيات
7. للأجهزة الحقيقية: ستحتاج إلى UDID للجهاز (معرّف فريد مكون من 40 حرفًا)

Android

1. تثبيت Android Studio وإعداد Android SDK
2. تعيين متغيرات البيئة:

   export ANDROID_HOME=$HOME/Library/Android/sdk
   export PATH=$PATH:$ANDROID_HOME/emulator
   export PATH=$PATH:$ANDROID_HOME/platform-tools

3. تثبيت Appium:

   npm install -g appium

4. تثبيت برنامج تشغيل UiAutomator2:

   appium driver install uiautomator2

5. بدء خادم Appium:

   appium

6. إنشاء محاكي عبر Android Studio → Virtual Device Manager
7. بدء تشغيل المحاكي قبل تشغيل الاختبارات

البنية

كيف يعمل

يعمل WebdriverIO MCP كجسر بين مساعدي الذكاء الاصطناعي وأتمتة المتصفح/الجوال:

┌─────────────────┐     MCP Protocol      ┌─────────────────┐
│  Claude Desktop │ ◄──────────────────►  │    @wdio/mcp    │
│  or Claude Code │      (stdio)          │     Server      │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                             WebDriverIO API
                                                   │
                    ┌──────────────────────────────┼──────────────────────────────┐
                    │                              │                              │
            ┌───────▼───────┐             ┌───────▼───────┐             ┌───────▼───────┐
            │    Chrome     │             │    Appium     │             │    Appium     │
            │   (Browser)   │             │     (iOS)     │             │   (Android)   │
            └───────────────┘             └───────────────┘             └───────────────┘

إدارة الجلسات

• نموذج الجلسة الفردية: يمكن أن تكون جلسة متصفح واحدة أو تطبيق واحد نشطة في وقت واحد
• حالة الجلسة يتم الحفاظ عليها عالميًا عبر استدعاءات الأدوات
• الفصل التلقائي: الجلسات ذات الحالة المحفوظة (noReset: true) تنفصل تلقائيًا عند الإغلاق

اكتشاف العناصر

المتصفح (الويب)

• يستخدم نصًا برمجيًا محسّنًا للمتصفح للعثور على جميع العناصر المرئية والقابلة للتفاعل
• يُرجع العناصر مع محددات CSS والمعرّفات والفئات ومعلومات ARIA
• يُصفي العناصر المرئية في منطقة العرض افتراضيًا

الجوال (التطبيقات الأصلية)

• يستخدم تحليل مصدر الصفحة XML بكفاءة (استدعاءين HTTP مقابل +600 للاستعلامات التقليدية)
• تصنيف العناصر الخاص بالمنصة لـ Android و iOS
• ينشئ استراتيجيات تحديد متعددة لكل عنصر:
  • معرّف الوصول (عبر المنصات، الأكثر استقرارًا)
  • معرّف المورد / سمة الاسم
  • مطابقة النص / التسمية
  • XPath (كامل ومبسط)
  • UiAutomator (Android) / Predicates (iOS)

بناء جملة المُحددات

يدعم خادم MCP استراتيجيات محددات متعددة. راجع المُحددات للحصول على وثائق مفصلة.

الويب (CSS/XPath)

# محددات CSS
button.my-class
#element-id
[data-testid="login"]

# XPath
//button[@class='submit']
//a[contains(text(), 'Click')]

# محددات النص (خاصة بـ WebdriverIO)
button=Exact Button Text
a*=Partial Link Text

الجوال (عبر المنصات)

# معرّف الوصول (موصى به - يعمل على iOS و Android)
~loginButton

# Android UiAutomator
android=new UiSelector().text("Login")

# iOS Predicate String
-ios predicate string:label == "Login"

# iOS Class Chain
-ios class chain:**/XCUIElementTypeButton[`label == "Login"`]

# XPath (يعمل على كلا المنصتين)
//android.widget.Button[@text="Login"]
//XCUIElementTypeButton[@label="Login"]

الأدوات المتاحة

يوفر خادم MCP 25 أداة لأتمتة المتصفح والجوال. راجع الأدوات للحصول على المرجع الكامل.

أدوات المتصفح

الأداة	الوصف
start_browser	تشغيل متصفح Chrome (مع URL أولي اختياري)
close_session	إغلاق أو فصل الجلسة
navigate	الانتقال إلى URL
click_element	النقر على عنصر
set_value	كتابة نص في حقل الإدخال
get_visible_elements	الحصول على العناصر المرئية/القابلة للتفاعل (مع تقسيم الصفحات)
get_accessibility	الحصول على شجرة الوصول (مع التصفية)
take_screenshot	التقاط لقطة شاشة (محسنة تلقائيًا)
scroll	تمرير الصفحة لأعلى أو لأسفل
get_cookies / set_cookie / delete_cookies	إدارة ملفات تعريف الارتباط
execute_script	تنفيذ JavaScript في سياق المتصفح

أدوات الجوال

الأداة	الوصف
start_app_session	تشغيل تطبيق iOS/Android
tap_element	النقر على عنصر أو إحداثيات
swipe	التمرير في اتجاه معين
drag_and_drop	السحب بين المواقع
get_app_state	التحقق مما إذا كان التطبيق قيد التشغيل
get_contexts / switch_context	تبديل السياق في التطبيقات الهجينة
rotate_device	التدوير إلى وضع عمودي/أفقي
get_geolocation / set_geolocation	الحصول على أو تعيين إحداثيات GPS
hide_keyboard	إخفاء لوحة المفاتيح على الشاشة
execute_script	تنفيذ أوامر Appium للجوال

التعامل التلقائي

الأذونات

افتراضيًا، يمنح خادم MCP تلقائيًا أذونات التطبيق (autoGrantPermissions: true)، مما يلغي الحاجة إلى التعامل اليدوي مع مربعات حوار الأذونات أثناء الأتمتة.

تنبيهات النظام

يتم قبول تنبيهات النظام (مثل "السماح بالإشعارات؟") تلقائيًا بشكل افتراضي (autoAcceptAlerts: true). يمكن تكوين هذا لتجاهلها بدلاً من ذلك باستخدام autoDismissAlerts: true.

التكوين

متغيرات البيئة

قم بتكوين اتصال خادم Appium:

المتغير	الافتراضي	الوصف
APPIUM_URL	127.0.0.1	اسم مضيف خادم Appium
APPIUM_URL_PORT	4723	منفذ خادم Appium
APPIUM_PATH	/	مسار خادم Appium

مثال مع خادم Appium مخصص

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"],
            "env": {
                "APPIUM_URL": "192.168.1.100",
                "APPIUM_URL_PORT": "4724"
            }
        }
    }
}

تحسين الأداء

تم تحسين خادم MCP للاتصال الفعال بمساعد الذكاء الاصطناعي:

• تنسيق TOON: يستخدم Token-Oriented Object Notation لاستخدام الحد الأدنى من الرموز
• تحليل XML: يستخدم اكتشاف عناصر الجوال استدعاءين HTTP (مقابل +600 بالطريقة التقليدية)
• ضغط لقطة الشاشة: يتم ضغط الصور تلقائيًا إلى حد أقصى 1 ميجابايت باستخدام Sharp
• تصفية منطقة العرض: يتم إرجاع العناصر المرئية فقط افتراضيًا
• تقسيم الصفحات: يمكن تقسيم قوائم العناصر الكبيرة لتقليل حجم الاستجابة

دعم TypeScript

تمت كتابة خادم MCP بلغة TypeScript ويتضمن تعريفات النوع الكاملة. إذا كنت تقوم بتوسيع أو دمج الخادم برمجيًا، فستستفيد من الإكمال التلقائي وسلامة النوع.

معالجة الأخطاء

تم تصميم جميع الأدوات مع معالجة قوية للأخطاء:

• يتم إرجاع الأخطاء كمحتوى نصي (لا يتم رميها أبدًا)، مما يحافظ على استقرار بروتوكول MCP
• تساعد رسائل الخطأ الوصفية في تشخيص المشكلات
• يتم الحفاظ على حالة الجلسة حتى عند فشل العمليات الفردية

حالات الاستخدام

ضمان الجودة

• تنفيذ حالات الاختبار المدعومة بالذكاء الاصطناعي
• اختبار الانحدار البصري باستخدام لقطات الشاشة
• تدقيق إمكانية الوصول عبر تحليل شجرة الوصول

استخراج البيانات من الويب

• التنقل في تدفقات متعددة الصفحات معقدة
• استخراج البيانات المنظمة من المحتوى الديناميكي
• التعامل مع المصادقة وإدارة الجلسات

اختبار تطبيقات الجوال

• أتمتة الاختبار عبر المنصات (iOS + Android)
• التحقق من سير عملية التسجيل
• اختبار الروابط العميقة والتنقل

اختبار التكامل

• اختبار سير العمل من البداية إلى النهاية
• التحقق من تكامل API + واجهة المستخدم
• فحوصات الاتساق عبر المنصات المتعددة

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

لا يمكن بدء تشغيل المتصفح

• تأكد من تثبيت Chrome
• تحقق من عدم استخدام أي عملية أخرى لمنفذ التصحيح الافتراضي (9222)
• جرب الوضع غير المرئي إذا حدثت مشاكل في العرض

فشل اتصال Appium

• تحقق من تشغيل خادم Appium (appium)
• تحقق من تكوين URL ومنفذ Appium
• تأكد من تثبيت برنامج التشغيل المناسب (appium driver list)

مشاكل محاكي iOS

• تأكد من تثبيت Xcode وتحديثه
• تحقق من توفر المحاكيات (xcrun simctl list devices)
• للأجهزة الحقيقية، تحقق من صحة UDID

مشاكل محاكي Android

• تأكد من تكوين Android SDK بشكل صحيح
• تحقق من تشغيل المحاكي (adb devices)
• تحقق من تعيين متغير البيئة ANDROID_HOME

الموارد

• مرجع الأدوات - قائمة كاملة بالأدوات المتاحة
• دليل المُحددات - توثيق بناء جملة المُحددات
• التكوين - خيارات التكوين
• الأسئلة الشائعة - الأسئلة المتكررة
• مستودع GitHub - الكود المصدري والمشكلات
• حزمة NPM - الحزمة على npm
• بروتوكول سياق النموذج - مواصفات MCP