التهيئة

Matthias Rohmer
José Luis Zapata

يمكنك ضبط "أدوات مطوّري البرامج في Chrome المخصّصة للوكلاء" لتخصيص طريقة تفاعلها مع المتصفّح، والأدوات المفعَّلة، وطريقة معالجتها للبيانات.

يمكنك ضبط الخادم من خلال تمرير علامات سطر الأوامر في مصفوفة args لملف إعدادات عميل "بروتوكول سياق النموذج" (MCP). ويكون هذا عادةً ملف config.json.

على سبيل المثال، لتشغيل Chrome في وضع التشغيل بلا واجهة مستخدم رسومية واستخدام قناة Canary، استخدِم الإعدادات التالية:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless",
        "--channel=canary"
      ]
    }
  }
}

سيناريوهات الإعداد الشائعة

توضّح السيناريوهات التالية الطرق الشائعة لضبط "أدوات مطوّري البرامج في Chrome المخصّصة للوكلاء".

التشغيل في وضع التشغيل بلا واجهة مستخدم رسومية

لتنفيذ مهام في الخلفية بدون نافذة متصفّح مرئية، شغِّل Chrome في وضع بلا رأس (بدون واجهة مستخدم). أضِف العلامة --headless إلى وسيطات الخادم.

الاتصال بجلسة متصفّح حالية

بشكل تلقائي، تبدأ "أدوات مطوّري البرامج في Chrome المخصّصة للوكلاء" مثيل Chrome جديدًا. ومع ذلك، يمكنك ربط وكيلك بجلسة متصفّح حالية. ويُعدّ هذا الأمر مفيدًا إذا كان موظف الدعم بحاجة إلى التحقيق في مشكلة في جلسة بدأتها من قبل (على سبيل المثال، إذا كنت قد سجّلت الدخول من قبل).

يمكنك الاتصال بجلسة حالية بطريقتَين:

الاتصال التلقائي (الإصدار 144 من Chrome والإصدارات الأحدث)

إذا كنت تستخدم العلامة --autoConnect، يتصل خادم MCP تلقائيًا بمثيل Chrome نشط.

  1. في متصفّح Chrome الذي تستخدمه، انتقِل إلى chrome://inspect/#remote-debugging وفعِّل تصحيح الأخطاء عن بُعد.
  2. أضِف --autoConnect إلى إعدادات MCP: json "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
  3. عندما يحاول الوكيل الاتصال، يعرض Chrome مربّع حوار يطلب الإذن. انقر على سماح.

الاتصال اليدوي

إذا تعذّر عليك استخدام --autoConnect (على سبيل المثال، في بيئة معزولة)، يمكنك بدء تشغيل Chrome يدويًا باستخدام منفذ تصحيح الأخطاء والاتصال باستخدام --browser-url.

  1. ابدأ تشغيل Chrome من الوحدة الطرفية مع تفعيل تصحيح الأخطاء عن بُعد ودليل بيانات المستخدمين المخصّص.
    • macOS: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
    • Windows: shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable
    • Linux: shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
  2. اضبط الوكيل للاتصال بهذا المنفذ: json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

السماح بالوصول إلى الملفات خارج الدليل المؤقت

لا يمكن للأدوات التي تقرأ الملفات أو تكتبها (مثل حفظ لقطات الشاشة أو عمليات التتبُّع أو تحميل الإضافات) الوصول إلا إلى المسارات ضمن جذور مساحة العمل التي تم ضبطها. يستخدم الخادم المجلدات الجذر التي يوفّرها عميل MCP من خلال ميزة المجلدات الجذر في MCP، بالإضافة إلى أي أدلة يتم تمريرها باستخدام --filesystemRoot (الاسم المستعار --workspace). إذا لم يوفّر العميل المجلدات الجذر ولم يتم ضبط --filesystemRoot، سيقتصر الوصول إلى الملفات على الدليل المؤقت لنظام التشغيل. يتعذّر تنفيذ الطلبات المتعلقة بمسارات أخرى ويظهر الخطأ Access denied: ... is not within any of the configured workspace roots.

للسماح بالوصول إلى دليل مشروع، أضِف --filesystemRoot إلى وسيطات الخادم. يمكنك تكرار العلامة للسماح بأدلة متعددة:

"args": ["chrome-devtools-mcp@latest", "--filesystemRoot=/path/to/project"]

مرجع خيارات الإعداد

تدرج الأقسام التالية علامات الضبط المتاحة. للاطّلاع على أحدث الخيارات والتحديثات، يُرجى الرجوع إلى مستودع GitHub الخاص بأداة MCP في "أدوات مطوّري البرامج في Chrome".

خيارات الاتصال

استخدِم هذه الخيارات لضبط كيفية اتصال الخادم بمتصفّح Chrome.

علم النوع القيمة التلقائية الوصف
--autoConnect أو --auto-connect قيمة منطقية false يتم الاتصال تلقائيًا بنسخة من Chrome (الإصدار 144 أو الإصدارات الأحدث) تعمل على الجهاز. تتطلّب هذه السياسة تفعيل ميزة تصحيح الأخطاء عن بُعد باستخدام chrome://inspect/#remote-debugging.
‫--browserUrl أو --browser-url
-u		 سلسلة false الاتصال بمثيل Chrome قيد التشغيل وقابل للتصحيح (على سبيل المثال، http://127.0.0.1:9222).
‫--wsEndpoint أو --ws-endpoint
-w		 سلسلة false نقطة نهاية WebSocket للاتصال بمثيل Chrome قيد التشغيل (على سبيل المثال، ws://127.0.0.1:9222/devtools/browser/<id>). بديل لـ --browserUrl.
--wsHeaders أو --ws-headers سلسلة false عناوين مخصّصة لاتصال WebSocket بتنسيق JSON (على سبيل المثال، '{"Authorization":"Bearer token"}'). لا تعمل إلا مع --wsEndpoint.

خيارات فتح المتصفّح

تنطبق هذه الخيارات عندما يبدأ خادم MCP تشغيل Chrome.

علم النوع القيمة التلقائية الوصف
--headless قيمة منطقية false يتم تشغيل Chrome في وضع "بلا واجهة مستخدم رسومية".
--channel سلسلة stable تحدّد هذه السياسة قناة Chrome التي يجب استخدامها. الخيارات: canary وdev وbeta وstable
‫--executablePath أو --executable-path
-e		 سلسلة false المسار إلى ملف تنفيذي مخصّص في Chrome
--userDataDir أو --user-data-dir سلسلة الاطّلاع على الوصف مسار دليل بيانات المستخدم القيمة التلقائية هي $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE.
--isolated قيمة منطقية false تنشئ هذه السمة دليلاً مؤقتًا لبيانات المستخدم يتم تنظيفه تلقائيًا عند إغلاق المتصفّح.
--viewport سلسلة false الحجم الأولي لإطار العرض (على سبيل المثال، 1280x720). في وضع "بلا واجهة مستخدم رسومية"، يكون الحد الأقصى للحجم هو 3840x2160.
--proxyServer أو --proxy-server سلسلة false تم تمرير إعدادات الخادم الوكيل إلى Chrome.
--chromeArg أو --chrome-arg صفيف false وسيطات إضافية لتمريرها إلى Chrome
--ignoreDefaultChromeArg أو --ignore-default-chrome-arg صفيف false إيقاف الوسيطات التلقائية في Chrome بشكل صريح

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

استخدِم هذه الخيارات لإدارة إعدادات الأمان وخصوصية البيانات.

علم النوع القيمة التلقائية الوصف
--acceptInsecureCerts أو --accept-insecure-certs قيمة منطقية false يتم تجاهل الأخطاء المتعلقة بالشهادات الموقَّعة ذاتيًا والمنتهية الصلاحية. يجب استخدامه بحذر.
--blockedUrlPattern أو --blocked-url-pattern صفيف false يحظر هذا الإعداد الوصول إلى الشبكة من خلال حظر أنماط عناوين URL محدّدة (يستخدم URLPattern). يحظر عمليات التنقّل والموارد الفرعية.
--allowedUrlPattern أو --allowed-url-pattern صفيف false يحظر هذا الإعداد الوصول إلى الشبكة من خلال السماح فقط بأنماط عناوين URL محدّدة. تتطلّب هذه الميزة الإصدار 149 من Chrome أو إصدارًا أحدث.
--redactNetworkHeaders أو --redact-network-headers قيمة منطقية false يخفي عناوين الشبكة الحسّاسة قبل إرجاعها إلى العميل.
--usageStatistics أو --usage-statistics قيمة منطقية true تتيح هذه الإعدادات جمع إحصاءات الاستخدام لتحسين الأداة. يمكن أيضًا إيقافها باستخدام متغيّرات البيئة CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS أو CI.
--performanceCrux أو --performance-crux قيمة منطقية true يتم إرسال عناوين URL من عمليات تتبُّع الأداء إلى واجهة Google CrUX API لاسترجاع بيانات تجربة المستخدمين الفعليين.
--javascriptEvaluation أو --javascript-evaluation قيمة منطقية true اضبط السياسة على false لإيقاف تنفيذ JavaScript. عند إيقاف هذه الميزة، يتم إيقاف أدوات تقييم النصوص البرمجية، وإيقاف المَعلمة initScript الخاصة بالوظيفة navigate_page، ويُحظر الانتقال إلى عناوين URL الخاصة بـ javascript: أو data: أو vbscript:.
‫--filesystemRoot أو --filesystem-root
--workspace		 صفيف الدليل المؤقت لنظام التشغيل دليل يُسمح لأدوات الوصول إلى الملفات باستخدامه، بالإضافة إلى الجذور التي يوفّرها عميل MCP يمكن تحديدها أكثر من مرة. اطّلِع على السماح بالوصول إلى الملفات خارج الدليل المؤقت.
--allowUnrestrictedPaths أو --allow-unrestricted-paths قيمة منطقية false تم إيقافها نهائيًا: استخدِم --workspace=/ بدلاً منها. يؤدي هذا الإعداد إلى إيقاف قيود المسار التي تنطبق عندما لا يوفّر عميل MCP جذورًا.

فئات الميزات

يمكنك تفعيل مجموعات من الأدوات أو إيقافها باستخدام هذه العلامات.

علم النوع القيمة التلقائية الوصف
--categoryInput أو --category-input قيمة منطقية true تفعيل الأدوات ذات الصلة بالإدخال
--categoryNavigation أو --category-navigation قيمة منطقية true تفعيل الأدوات المرتبطة بالتنقل
--categoryEmulation أو --category-emulation قيمة منطقية true لتفعيل الأدوات المتعلّقة بالمحاكاة
--categoryNetwork أو --category-network قيمة منطقية true يتيح هذا الإعداد الأدوات ذات الصلة بالشبكة.
--categoryPerformance أو --category-performance قيمة منطقية true يتيح هذا الإعداد الأدوات المتعلّقة بالأداء.
--categoryDebugging أو --category-debugging قيمة منطقية true يتم تفعيل الأدوات المتعلّقة بتصحيح الأخطاء.
--categoryMemory أو --category-memory قيمة منطقية true تفعيل الأدوات ذات الصلة بالذاكرة
--categoryExtensions أو --category-extensions قيمة منطقية false يتيح هذا الإعداد الأدوات ذات الصلة بالإضافات. لا تتوفّر هذه الميزة إلا مع اتصال الأنبوب.
--categoryPwa أو --category-pwa قيمة منطقية false تتيح هذه السياسة تفعيل أدوات التشغيل الآلي لتطبيقات الويب التقدّمية (التثبيت والتشغيل وإلغاء التثبيت وحالة نظام التشغيل). وتتوافق مع اتصالات الأنابيب فقط.
--categoryExperimentalThirdParty أو --category-experimental-third-party قيمة منطقية false تتيح أدوات المطوّرين التابعة لجهات خارجية التي تعرضها الصفحة التي يتم فحصها.
--categoryExperimentalWebmcp أو --category-experimental-webmcp قيمة منطقية false تتيح هذه السمة تصحيح أخطاء أدوات WebMCP. تتطلّب هذه الميزة الإصدار 149 من Chrome أو إصدارًا أحدث مع تفعيل ميزات WebMCP.
--memoryDebugging أو --memory-debugging قيمة منطقية false تتيح هذه السياسة تفعيل أدوات تصحيح أخطاء الذاكرة.

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

استخدِم هذه الخيارات لتخصيص طريقة التقاط البرنامج المساعد للقطات الشاشة.

علم النوع القيمة التلقائية الوصف
--screenshotFormat أو --screenshot-format سلسلة false تتجاوز تنسيق الإخراج التلقائي (png). الخيارات: jpeg وpng وwebp. يتميّز التنسيقان jpeg وwebp بحجم أصغر، ما يساعد في تقليل حجم السياق في المحادثات مع الذكاء الاصطناعي.
--screenshotQuality أو --screenshot-quality الرقم false تتجاهل هذه السياسة جودة الضغط (من 0 إلى 100) في jpeg وwebp.
--screenshotMaxWidth أو --screenshot-max-width الرقم false الحد الأقصى للعرض بالبكسل ويتم تصغير لقطات الشاشة الأكبر حجمًا.
--screenshotMaxHeight أو --screenshot-max-height الرقم false الحد الأقصى للارتفاع بالبكسل يتم تصغير لقطات الشاشة الأكبر حجمًا.

خيارات تجريبية

استخدِم هذه الخيارات لتفعيل الميزات التجريبية التي لا تزال قيد التطوير.

علم النوع القيمة التلقائية الوصف
--experimentalDevtools أو --experimental-devtools قيمة منطقية false تتيح هذه السياسة التشغيل الآلي على أهداف "أدوات مطوّري البرامج".
--experimentalVision أو --experimental-vision قيمة منطقية false تتيح هذه السمة استخدام الأدوات المستندة إلى الإحداثيات (مثل click_at)، وتتطلّب عادةً نموذجًا لاستخدام الكمبيوتر يمكنه إنشاء إحداثيات دقيقة من خلال الاطّلاع على لقطات الشاشة.
--experimentalStructuredContent أو --experimental-structured-content قيمة منطقية false تُنشئ محتوًى منسّقًا ومنظَّمًا.
--experimentalIncludeAllPages أو --experimental-include-all-pages قيمة منطقية false ويشمل ذلك جميع أنواع الصفحات (مثل طرق عرض الويب والصفحات التي تعمل في الخلفية).
--experimentalScreencast أو --experimental-screencast قيمة منطقية false تتيح هذه السياسة استخدام أدوات تسجيل الشاشة (تتطلّب ffmpeg في PATH).
--experimentalFfmpegPath أو --experimental-ffmpeg-path سلسلة false المسار إلى الملف التنفيذي ffmpeg
--experimentalScreencastFps أو --experimental-screencast-fps الرقم false عدد اللقطات في الثانية لتسجيل شاشة العرض يمكن أن تؤدي القيم المنخفضة إلى تقليل الضغط على الذاكرة في الصفحات التي تنتج لقطات أسرع من قدرة ffmpeg على ترميزها.

خيارات أخرى

استخدِم هذه الخيارات لضبط التسجيل أو توجيه الصفحة أو خرائط المصدر أو لتفعيل مجموعة مبسطة من الأدوات.

علم النوع القيمة التلقائية الوصف
--slim قيمة منطقية false توفّر مجموعة صغيرة من ثلاث أدوات (التنقّل وتنفيذ النصوص البرمجية ولقطات الشاشة). مفيد للمهام الأساسية في المتصفّح
--pageIdRouting أو --page-id-routing قيمة منطقية true تتطلّب هذه الميزة استخدام pageId في الأدوات على مستوى الصفحة وتوجيه الطلبات حسب رقم تعريف الصفحة، وهو أمر مفيد لجلسات الوكلاء المتزامنة. استخدِم --no-page-id-routing لإيقافه.
--sourceMaps أو --source-maps قيمة منطقية true تتيح هذه السياسة استخدام خرائط المصدر في "أدوات مطوّري البرامج". استخدِم --no-source-maps لإيقافه.
--logFile أو --log-file سلسلة false المسار إلى ملف لكتابة سجلّات تصحيح الأخطاء فيه اضبط متغيّر البيئة NODE_DEBUG على * لتفعيل السجلّات المطوَّلة.
--config سلسلة false المسار إلى ملف إعداد JSON

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

يمكنك أيضًا استخدام متغيرات البيئة التالية لضبط الخادم:

  • ‫CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: في حال ضبطها، يتم إيقاف جمع إحصاءات الاستخدام (وهي تعادل --no-usage-statistics).
  • CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: في حال ضبطها، يتم إيقاف عمليات التحقّق الدورية من التحديثات.
  • CI: في حال ضبط هذه السياسة، يتم إيقاف جمع إحصاءات الاستخدام.
  • NODE_DEBUG: اضبط القيمة على * لتفعيل ميزة تسجيل سجلّ تصحيح الأخطاء المطوّل (تعمل بالتزامن مع --logFile).