الإعدادات

تُوثّق هذه الصفحة جميع خيارات الإعداد لخادم WebdriverIO MCP.

إعدادات خادم MCP

يتم إعداد خادم MCP من خلال ملفات إعدادات Claude Desktop أو Claude Code.

الإعداد الأساسي

نظام macOS

قم بتعديل ~/Library/Application Support/Claude/claude_desktop_config.json:

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

نظام Windows

قم بتعديل %APPDATA%\Claude\claude_desktop_config.json:

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

Claude Code

قم بتعديل ملف .claude/settings.json في مشروعك:

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

---

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

قم بإعداد اتصال خادم Appium والإعدادات الأخرى عبر متغيرات البيئة.

اتصال Appium

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

مثال باستخدام متغيرات البيئة

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

---

خيارات جلسة المتصفح

الخيارات المتاحة عند بدء جلسة متصفح عبر أداة start_browser.

headless

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: false

تشغيل Chrome في وضع بدون واجهة (بدون نافذة متصفح مرئية). مفيد لبيئات CI/CD أو عندما لا تحتاج لرؤية المتصفح.

windowWidth

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 1920
• النطاق: 400 - 3840

عرض نافذة المتصفح الأولي بالبكسل.

windowHeight

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 1080
• النطاق: 400 - 2160

ارتفاع نافذة المتصفح الأولي بالبكسل.

navigationUrl

• النوع: string
• إلزامي: لا

عنوان URL للانتقال إليه فورًا بعد بدء المتصفح. هذا أكثر كفاءة من استدعاء start_browser متبوعًا بـ navigate بشكل منفصل.

مثال: بدء المتصفح والانتقال في استدعاء واحد:

Start Chrome and navigate to https://webdriver.io

---

خيارات جلسة تطبيقات الهاتف المحمول

الخيارات المتاحة عند بدء جلسة تطبيق محمول عبر أداة start_app_session.

خيارات المنصة

platform

• النوع: string
• إلزامي: نعم
• القيم: iOS | Android

منصة الهاتف المحمول المراد أتمتتها.

platformVersion

• النوع: string
• إلزامي: لا

إصدار نظام التشغيل للجهاز/المحاكي (مثل 17.0 لنظام iOS، 14 لنظام Android).

automationName

• النوع: string
• إلزامي: لا
• القيم: XCUITest (iOS)، UiAutomator2 | Espresso (Android)

محرك الأتمتة المراد استخدامه. القيمة الافتراضية هي XCUITest لنظام iOS وUiAutomator2 لنظام Android.

خيارات الجهاز

deviceName

• النوع: string
• إلزامي: نعم

اسم الجهاز أو المحاكي المراد استخدامه.

أمثلة:

• محاكي iOS: iPhone 15 Pro, iPad Air (5th generation)
• محاكي Android: Pixel 7, Nexus 5X
• الجهاز الحقيقي: اسم الجهاز كما يظهر في نظامك

udid

• النوع: string
• إلزامي: لا (مطلوب لأجهزة iOS الحقيقية)

معرف الجهاز الفريد. مطلوب لأجهزة iOS الحقيقية (معرف من 40 حرفًا) وموصى به لأجهزة Android الحقيقية.

للعثور على UDID:

• iOS: قم بتوصيل الجهاز، افتح Finder/iTunes، انقر على الجهاز → الرقم التسلسلي (انقر للكشف عن UDID)
• Android: قم بتشغيل adb devices في المحطة الطرفية

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

appPath

• النوع: string
• إلزامي: لا*

مسار ملف التطبيق المراد تثبيته وتشغيله.

الصيغ المدعومة:

• محاكي iOS: مجلد .app
• جهاز iOS حقيقي: ملف .ipa
• Android: ملف .apk

*يجب توفير إما appPath أو noReset: true للاتصال بتطبيق قيد التشغيل بالفعل.

appWaitActivity

• النوع: string
• إلزامي: لا (Android فقط)

النشاط المراد انتظاره عند بدء التطبيق. إذا لم يتم تحديده، سيتم استخدام نشاط التطبيق الرئيسي.

مثال: com.example.app.MainActivity

خيارات حالة الجلسة

noReset

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: false

الحفاظ على حالة التطبيق بين الجلسات. عندما تكون true:

• يتم الحفاظ على بيانات التطبيق (حالة تسجيل الدخول، التفضيلات، إلخ.)
• ستقوم الجلسة بالانفصال بدلاً من الإغلاق (تبقي التطبيق قيد التشغيل)
• مفيد لاختبار رحلات المستخدم عبر جلسات متعددة
• يمكن استخدامها بدون appPath للاتصال بتطبيق قيد التشغيل بالفعل

fullReset

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: true

إعادة ضبط التطبيق بالكامل قبل الجلسة. عندما تكون true:

• iOS: يقوم بإلغاء تثبيت التطبيق وإعادة تثبيته
• Android: يمسح بيانات التطبيق والذاكرة المؤقتة
• مفيد للبدء بحالة نظيفة

اضبط fullReset: false مع noReset: true للحفاظ على حالة التطبيق بشكل كامل.

مهلة الجلسة

newCommandTimeout

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 60

المدة (بالثواني) التي سينتظر فيها Appium أمرًا جديدًا قبل افتراض أن العميل قد أغلق وإنهاء الجلسة. قم بزيادة هذه القيمة لجلسات تصحيح الأخطاء الأطول.

أمثلة:

• 60 - القيمة الافتراضية، مناسبة لمعظم عمليات الأتمتة
• 300 - 5 دقائق، لتصحيح الأخطاء أو العمليات الأبطأ
• 600 - 10 دقائق، للاختبارات طويلة المدة

خيارات المعالجة الآلية

autoGrantPermissions

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: true

منح أذونات التطبيق تلقائيًا عند التثبيت/التشغيل. عندما تكون true:

• يتم منح الأذونات تلقائيًا للكاميرا والميكروفون والموقع وما إلى ذلك
• لا حاجة للتعامل اليدوي مع مربعات حوار الأذونات
• تبسيط الأتمتة من خلال تجنب النوافذ المنبثقة للأذونات

لنظام Android فقط

يؤثر هذا الخيار بشكل أساسي على Android. يجب التعامل مع أذونات iOS بشكل مختلف بسبب قيود النظام.

autoAcceptAlerts

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: true

قبول تنبيهات النظام (مربعات الحوار) التي تظهر أثناء الأتمتة تلقائيًا.

أمثلة على التنبيهات المقبولة تلقائيًا:

• "السماح بالإشعارات؟"
• "يرغب التطبيق في الوصول إلى موقعك"
• "السماح للتطبيق بالوصول إلى الصور؟"

autoDismissAlerts

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: false

رفض (إلغاء) تنبيهات النظام بدلاً من قبولها. لها الأولوية على autoAcceptAlerts عند تعيينها إلى true.

تجاوز إعدادات خادم Appium

يمكنك تجاوز اتصال خادم Appium على أساس كل جلسة:

appiumHost

• النوع: string
• إلزامي: لا

اسم مضيف خادم Appium. يتجاوز متغير البيئة APPIUM_URL.

appiumPort

• النوع: number
• إلزامي: لا

منفذ خادم Appium. يتجاوز متغير البيئة APPIUM_URL_PORT.

appiumPath

• النوع: string
• إلزامي: لا

مسار خادم Appium. يتجاوز متغير البيئة APPIUM_PATH.

---

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

خيارات لأداة get_visible_elements.

elementType

• النوع: string
• إلزامي: لا
• القيمة الافتراضية: interactable
• القيم: interactable | visual | all

نوع العناصر المراد إرجاعها:

• interactable: الأزرار والروابط وحقول الإدخال وغيرها من العناصر القابلة للنقر
• visual: الصور و SVG والعناصر المرئية
• all: كل من العناصر التفاعلية والمرئية

inViewportOnly

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: true

إرجاع العناصر المرئية فقط ضمن منفذ العرض الحالي. عند تعيينها إلى false، ترجع جميع العناصر في تسلسل العرض (مفيدة للعثور على العناصر خارج الشاشة).

includeContainers

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: false

تضمين عناصر الحاويات/التخطيط في النتائج. عندما تكون true:

حاويات Android المضمنة:

• ViewGroup, FrameLayout, LinearLayout
• RelativeLayout, ConstraintLayout
• ScrollView, RecyclerView

حاويات iOS المضمنة:

• View, StackView, CollectionView
• ScrollView, TableView

مفيدة لتصحيح مشاكل التخطيط أو فهم تسلسل العرض.

includeBounds

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: false

تضمين حدود/إحداثيات العنصر (x, y, width, height) في الاستجابة. قم بتعيينها إلى true من أجل:

• التفاعلات المستندة إلى الإحداثيات
• تصحيح أخطاء التخطيط
• تحديد موضع العناصر المرئية

خيارات تقسيم الصفحات

للصفحات الكبيرة ذات العناصر العديدة، استخدم تقسيم الصفحات لتقليل استخدام الرموز:

limit

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 0 (غير محدود)

الحد الأقصى لعدد العناصر المراد إرجاعها.

offset

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 0

عدد العناصر التي يتم تخطيها قبل إرجاع النتائج.

مثال: الحصول على العناصر 21-40:

Get visible elements with limit 20 and offset 20

---

خيارات شجرة إمكانية الوصول

خيارات لأداة get_accessibility (للمتصفح فقط).

limit

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 100

الحد الأقصى لعدد العقد المراد إرجاعها. استخدم 0 للحصول على عدد غير محدود (غير موصى به للصفحات الكبيرة).

offset

• النوع: number
• إلزامي: لا
• القيمة الافتراضية: 0

عدد العقد التي يتم تخطيها لتقسيم الصفحات.

roles

• النوع: string[]
• إلزامي: لا
• القيمة الافتراضية: كل الأدوار

تصفية أدوار إمكانية الوصول المحددة.

الأدوار الشائعة: button, link, textbox, checkbox, radio, heading, img, listitem

مثال: الحصول على الأزرار والروابط فقط:

Get accessibility tree filtered to button and link roles

namedOnly

• النوع: boolean
• إلزامي: لا
• القيمة الافتراضية: true

إرجاع العقد التي لها اسم/تسمية فقط. تصفية الحاويات المجهولة وتقليل الضوضاء في النتائج.

---

خيارات لقطة الشاشة

خيارات لأداة take_screenshot.

outputPath

• النوع: string
• إلزامي: لا

المسار حيث يتم حفظ ملف لقطة الشاشة. إذا لم يتم توفيره، يتم إرجاع بيانات الصورة المشفرة بـ base64.

التحسين التلقائي

تتم معالجة لقطات الشاشة تلقائيًا لتحسينها للاستهلاك في نموذج اللغة الكبير (LLM):

التحسين	القيمة	الوصف
الحد الأقصى للأبعاد	2000 بكسل	الصور الأكبر من 2000 بكسل يتم تصغير حجمها
الحد الأقصى لحجم الملف	1 ميجابايت	يتم ضغط الصور للبقاء أقل من 1 ميجابايت
التنسيق	PNG/JPEG	PNG مع أقصى ضغط؛ JPEG إذا لزم الأمر للحجم

يضمن هذا التحسين إمكانية معالجة لقطات الشاشة بكفاءة دون تجاوز حدود الرموز.

---

سلوك الجلسة

أنواع الجلسات

يتتبع خادم MCP أنواع الجلسات لتوفير الأدوات والسلوك المناسب:

النوع	الوصف	الفصل التلقائي
browser	جلسة متصفح Chrome	لا
ios	جلسة تطبيق iOS	نعم (إذا كان noReset: true أو لا يوجد appPath)
android	جلسة تطبيق Android	نعم (إذا كان noReset: true أو لا يوجد appPath)

نموذج الجلسة الفردية

يعمل خادم MCP بنموذج جلسة واحدة:

• يمكن أن تكون هناك جلسة متصفح واحدة أو جلسة تطبيق واحدة نشطة في وقت واحد
• بدء جلسة جديدة سيؤدي إلى إغلاق/فصل الجلسة الحالية
• يتم الحفاظ على حالة الجلسة عالميًا عبر استدعاءات الأدوات

الفصل مقابل الإغلاق

الإجراء	detach: false (إغلاق)	detach: true (فصل)
المتصفح	يغلق Chrome تمامًا	يبقي Chrome قيد التشغيل، يفصل WebDriver
تطبيق الجوال	ينهي التطبيق	يبقي التطبيق قيد التشغيل في الحالة الحالية
حالة الاستخدام	حالة نظيفة للجلسة التالية	الحفاظ على الحالة، الفحص اليدوي

---

اعتبارات الأداء

تم تحسين خادم MCP للتواصل الفعال مع نموذج اللغة الكبير (LLM) باستخدام تنسيق TOON (Token-Oriented Object Notation)، مما يقلل من استخدام الرموز عند إرسال البيانات إلى Claude.

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

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

أتمتة الأجهزة المحمولة

• تحليل مصدر صفحة XML يستخدم 2 من طلبات HTTP فقط (مقابل +600 لاستعلامات العناصر التقليدية)
• محددات معرف الوصول هي الأسرع والأكثر موثوقية
• محددات XPath هي الأبطأ - استخدمها فقط كملاذ أخير
• inViewportOnly: true (افتراضيًا) يقلل بشكل كبير من عدد العناصر
• تقسيم الصفحات (limit و offset) يقلل من استخدام الرموز للشاشات ذات العناصر العديدة
• includeBounds: false (افتراضيًا) يحذف بيانات الإحداثيات ما لم تكن هناك حاجة إليها

نصائح استخدام الرموز

الإعداد	التأثير
inViewportOnly: true	يصفي العناصر خارج الشاشة، مما يقلل من حجم الاستجابة
includeContainers: false	يستبعد عناصر التخطيط (ViewGroup، إلخ)
includeBounds: false	يحذف بيانات x/y/width/height
limit مع تقسيم الصفحات	معالجة العناصر في دفعات بدلاً من دفعة واحدة
namedOnly: true (إمكانية الوصول)	يصفي العقد المجهولة

---

إعداد خادم Appium

قبل استخدام أتمتة الأجهزة المحمولة، تأكد من تكوين Appium بشكل صحيح.

الإعداد الأساسي

# تثبيت Appium عالميًا
npm install -g appium

# تثبيت السائقين
appium driver install xcuitest    # iOS
appium driver install uiautomator2  # Android

# بدء الخادم
appium

تكوين خادم مخصص

# بدء بمضيف ومنفذ مخصصين
appium --address 0.0.0.0 --port 4724

# بدء مع تسجيل
appium --log-level debug

# بدء مع مسار أساسي محدد
appium --base-path /wd/hub

التحقق من التثبيت

# التحقق من السائقين المثبتة
appium driver list --installed

# التحقق من إصدار Appium
appium --version

# اختبار الاتصال
curl http://localhost:4723/status

---

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

خادم MCP لا يبدأ التشغيل

1. تحقق من تثبيت npm/npx: npm --version
2. حاول تشغيله يدويًا: npx @wdio/mcp
3. تحقق من سجلات Claude Desktop للأخطاء

مشاكل اتصال Appium

1. تأكد من تشغيل Appium: curl http://localhost:4723/status
2. تحقق من تطابق متغيرات البيئة مع إعدادات خادم Appium
3. تأكد من أن جدار الحماية يسمح بالاتصالات على منفذ Appium

الجلسة لا تبدأ

1. المتصفح: تأكد من تثبيت Chrome
2. iOS: تحقق من توفر Xcode والمحاكيات
3. Android: تحقق من ANDROID_HOME وتشغيل المحاكي
4. مراجعة سجلات خادم Appium للحصول على رسائل خطأ مفصلة

انتهاء مهلة الجلسات

إذا انتهت مهلة الجلسات أثناء تصحيح الأخطاء:

1. زيادة newCommandTimeout عند بدء الجلسة
2. استخدم noReset: true للحفاظ على الحالة بين الجلسات
3. استخدم detach: true عند الإغلاق للحفاظ على تشغيل التطبيق