وكلاء البرمجة بالذكاء الاصطناعي بارعون في كتابة الكود، لكنهم كانوا دائمًا عُميًا تجاه أمر واحد: ما الذي يفعله الكود فعليًا داخل متصفح حقيقي. حين يصلح وكيلك خطأً في التخطيط أو يطارد صفحة بطيئة، فإنه يخمّن — لا يستطيع رؤية الـ DOM المُصيّر، ولا شلّال الشبكة، ولا أخطاء الـ console.

يأتي Chrome DevTools MCP ليُغلق هذه الحلقة. إنه خادم رسمي لبروتوكول سياق النموذج (MCP) من فريق Chrome، يمنح وكيل الذكاء الاصطناعي تحكّمًا برمجيًا مباشرًا بنسخة Chrome حقيقية: التنقّل بين الصفحات، النقر على العناصر، تسجيل تتبّعات الأداء، فحص طلبات الشبكة، قراءة رسائل الـ console، والتقاط لقطات الشاشة — كل ذلك من داخل Claude أو Cursor أو Gemini CLI أو أي عميل يدعم MCP.

في هذا الدرس ستُعدّ Chrome DevTools MCP، وتربطه بوكيلك، وتشغّل سير عمل تصحيح حقيقية: تشخيص صفحة بطيئة عبر تتبّع الأداء، وإعادة إنتاج استدعاء شبكة فاشل، وإصلاح خطأ في الـ console من البداية إلى النهاية.

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

قبل البدء، تأكّد من توفّر:

Node.js (إصدار LTS الحالي) وnpm مُثبَّتين
متصفح Chrome مستقر حديث (أو أحدث)
عميل ذكاء اصطناعي يدعم MCP: Claude Code أو Cursor أو VS Code Copilot أو Gemini CLI
إلمام أساسي بملفات إعداد JSON وبمفاهيم أدوات مطوري المتصفح (الشبكة، الـ console، الأداء)

لا حاجة لتثبيت عام — يعمل الخادم عبر npx.

ماذا ستتعلّم

بنهاية هذا الدليل ستكون قادرًا على:

تثبيت وإعداد Chrome DevTools MCP في عميل الذكاء الاصطناعي لديك
فهم مجموعة الأدوات الكاملة: التنقّل، أتمتة الإدخال، الأداء، الشبكة، والتصحيح
إجراء تدقيق أداء موجّه وقراءة الرؤى التي يكشفها وكيلك
إعادة إنتاج وإصلاح أخطاء الشبكة والـ console في حلقة آلية
ربط الخادم بنسخة Chrome قيد التشغيل أصلًا لتصحيح جلسة التطوير الخاصة بك

كيف يعمل

يكشف Chrome DevTools MCP بروتوكول أدوات مطوري Chrome (CDP) كمجموعة من أدوات MCP. خلف الكواليس يستخدم Puppeteer لقيادة نسخة Chrome، ثم يترجم استدعاءات أدوات الوكيل إلى أوامر CDP.

التدفّق بسيط:

يقرّر وكيل الذكاء الاصطناعي أنه يحتاج رؤية شيء ما في المتصفح.
يستدعي أداة MCP مثل navigate_page أو performance_start_trace.
ينفّذ الخادم الإجراء في Chrome ويعيد نتائج مُهيكلة — لقطة DOM، ملخّص تتبّع، قائمة طلبات شبكة.
يقرأ الوكيل تلك النتائج ويقرّر خطوته التالية.

ولأن الوكيل يعمل على صفحة حيّة، يستطيع التحقّق من إصلاحاته بنفسه بدلًا من التخمين.

الخطوة 1: أضف خادم MCP إلى عميلك

يُنشَر الخادم باسم chrome-devtools-mcp على npm. لا تثبّته عالميًا أبدًا — يشغّله العميل عند الطلب عبر npx.

Claude Code

أضفه بأمر واحد:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

أو حرّر إعداد MCP يدويًا (~/.claude.json أو ملف المشروع .mcp.json):

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

Cursor / VS Code / Gemini CLI

تستخدم جميع عملاء MCP الصيغة نفسها. ضع هذا في ملف إعدادات MCP الخاص بالعميل (في Cursor هو ~/.cursor/mcp.json، وفي Gemini CLI هو ~/.gemini/settings.json):

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

يُنزّل التشغيل الأول الحزمة وقد يُطلق نسخة Chrome جديدة، لذا قد يستغرق أول استدعاء أداة بضع ثوانٍ. تكون الاستدعاءات التالية سريعة لأن جلسة المتصفح تبقى مفتوحة.

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

أعد تشغيل عميلك، ثم اطلب من الوكيل أمرًا بسيطًا:

افتح صفحة جديدة، انتقل إلى https://example.com، وأخبرني بعنوان الصفحة.

إذا كان الخادم مربوطًا بشكل صحيح، سيستدعي الوكيل new_page ثم navigate_page ثم يقرأ لك العنوان. وسترى أيضًا نافذة Chrome تظهر.

الخطوة 2: افهم مجموعة الأدوات

يكشف Chrome DevTools MCP مجموعة أدوات واسعة (نحو 58 أداة). نادرًا ما تستدعيها يدويًا — يختارها الوكيل — لكن معرفة الفئات تساعدك على كتابة أوامر أفضل.

الفئة	أدوات تمثيلية	ماذا تفعل
التنقّل	`new_page`, `navigate_page`, `list_pages`, `select_page`, `close_page`, `wait_for`	فتح علامات التبويب وتبديلها وإدارتها
أتمتة الإدخال	`click`, `fill`, `fill_form`, `hover`, `type_text`, `press_key`, `upload_file`, `handle_dialog`	قيادة الصفحة كمستخدم
الأداء	`performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`	تسجيل وتحليل تتبّعات الأداء
الشبكة	`list_network_requests`, `get_network_request`	فحص كل طلب تُصدره الصفحة
التصحيح	`take_snapshot`, `take_screenshot`, `evaluate_script`, `list_console_messages`, `lighthouse_audit`	قراءة الـ DOM، تشغيل JS، قراءة الـ console، تدقيق الجودة
المحاكاة	`emulate`, `resize_page`	خنق المعالج/الشبكة، تغيير حجم منفذ العرض
الذاكرة	`take_heapsnapshot` وأدوات فحص الكومة	اصطياد تسرّبات الذاكرة

تستحق أداتان اهتمامًا خاصًا:

take_snapshot تعيد تمثيلًا نصيًا مُهيكلًا لشجرة إمكانية الوصول للصفحة. هذا ما يقرأه الوكيل لفهم التخطيط وإيجاد العناصر — وهو أرخص بكثير من لقطة الشاشة ويوفّر مراجع عناصر ثابتة للنقر.
evaluate_script تشغّل أي كود JavaScript في سياق الصفحة وتعيد النتيجة. هذه هي مخرج الوكيل الاحتياطي لقراءة أي حالة لا تغطّيها الأدوات المخصّصة.

الخطوة 3: أجرِ تدقيق أداء

هنا يتألّق Chrome DevTools MCP. بدلًا من أن تفتح أنت أدوات المطورين وتسجّل تتبّعًا وتحدّق في مخطّط اللهب، يفعل وكيلك ذلك ويشرح النتيجة.

جرّب هذا الأمر على صفحة تريد تحليلها:

انتقل إلى http://localhost:3000، وسجّل تتبّع أداء أثناء إعادة تحميل الصفحة،
ثم أخبرني بقيمة Largest Contentful Paint وأهم الفرص لجعل الصفحة أسرع.

سيشغّل الوكيل عادةً هذا التسلسل:

1. navigate_page  → http://localhost:3000
2. performance_start_trace (reload: true)
3. performance_stop_trace
4. performance_analyze_insight  → "LCPBreakdown"

أداة performance_analyze_insight هي المفتاح. لا تُلقي ببيانات التتبّع الخام — بل تعيد رؤى مُسمّاة (تفصيل LCP، الطلبات المُعيقة للتصيير، إزاحات التخطيط، مهام الخيط الرئيسي الطويلة) مع أرقام محدّدة. يقرأها وكيلك ويُنتج قائمة مُرتّبة بالأولوية، مثلًا:

LCP يبلغ 4.2 ثانية، يهيمن عليه ملف أنماط مُعيق للتصيير
مهمة طويلة بطول 600 مللي ثانية تحجب الخيط الرئيسي أثناء الإماهة
ثلاث صور تفتقر إلى أبعاد صريحة، ما يسبّب إزاحة في التخطيط

الآن يمكنك المتابعة: "أصلح ملف الأنماط المُعيق للتصيير وأعد تشغيل التتبّع للتأكّد من تحسّن LCP." يحرّر الوكيل كودك، ويعيد التحميل، ويعيد التتبّع، ويتحقّق — حلقة كاملة مُغلقة.

ادمج تتبّع الأداء مع emulate لمحاكاة جهاز بطيء. اطلب من الوكيل "خنق المعالج 4 أضعاف وخنق الشبكة إلى Slow 4G قبل التتبّع" لاصطياد المشكلات التي يُخفيها حاسوبك السريع.

الخطوة 4: صحّح طلبات الشبكة

حين يفشل استدعاء API أو يُعيد بيانات خاطئة، يستطيع وكيلك فحص الطلبات الفعلية بدلًا من التخمين.

انتقل إلى http://localhost:3000/dashboard، ثم اعرض كل طلبات الشبكة الفاشلة
وأرني نص استجابة أي طلب أعاد حالة 4xx أو 5xx.

يستدعي الوكيل list_network_requests للحصول على القائمة الكاملة، ويُرشّح الفشلة، ثم يستدعي get_network_request على كل طلب مشبوه لقراءة الترويسات والحالة ونص الاستجابة. اكتشاف نموذجي:

GET /api/user/profile → 401 Unauthorized
الترويسات المفقودة في الطلب: Authorization
الاستجابة: { "error": "Missing bearer token" }

من هنا يستطيع الوكيل تتبّع الخطأ رجوعًا إلى كودك — ربما لم يُرفَق رمز المصادقة على جانب العميل — يصلحه، يعيد التحميل، ويتأكّد أن الطلب يعيد الآن 200.

الخطوة 5: أصلح خطأ console من البداية إلى النهاية

أخطاء الـ console هي أكثر إشارة كان الوكيل أعمى عنها سابقًا. الآن يقرأها مباشرة.

افتح http://localhost:3000، اعرض أي أخطاء console، اعثر على السبب الجذري في
قاعدة الكود، أصلحه، ثم أعد التحميل وتأكّد من نظافة الـ console.

الحلقة التي يشغّلها الوكيل:

1. navigate_page → localhost:3000
2. list_console_messages → يجد: "TypeError: Cannot read properties of
   undefined (reading 'map') at ProductList.tsx:24"
3. (يقرأ ProductList.tsx، يجد أن products قد تكون undefined قبل حسم الجلب)
4. (يحرّر الملف ليحرس بـ `products?.map(...)`)
5. navigate_page (إعادة تحميل)
6. list_console_messages → نظيف

دورة الملاحظة ← الإصلاح ← التحقّق هذه هي الهدف الكامل من منح الوكيل عينين في المتصفح. لا يعلن الوكيل النصر بناءً على تخمين أبدًا؛ بل يتأكّد على الصفحة الحيّة.

الخطوة 6: اتصل بجلسة Chrome الحالية لديك

افتراضيًا يُطلق الخادم نسخة Chrome معزولة خاصة به. أحيانًا تريد أن يصحّح الوكيل الجلسة ذاتها التي سجّلت الدخول إليها أصلًا — بيئة تطويرك مع الكوكيز والتخزين المحلّي والمصادقة جاهزة.

أولًا، أطلق Chrome مع تفعيل التصحيح عن بُعد:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222
 
# Linux
google-chrome --remote-debugging-port=9222

ثم وجّه الخادم إليه عبر علامة --browser-url:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url",
        "http://127.0.0.1:9222"
      ]
    }
  }
}

الآن يعمل الوكيل على متصفحك الحقيقي المُصادَق عليه. استخدم هذا بحذر — يستطيع الوكيل التفاعل مع أي شيء في تلك العلامات.

علامات سطر الأوامر المفيدة

مرّر هذه في مصفوفة args لضبط سلوك الخادم:

العلامة	الغرض
`--headless`	تشغيل Chrome بلا نافذة مرئية (مناسب لـ CI)
`--isolated`	استخدام ملف تعريف مؤقت جديد يُنظَّف عند الخروج
`--channel canary`	استخدام Chrome Canary أو Dev أو Beta أو Stable
`--browser-url <url>`	الاتصال بنسخة Chrome قيد التشغيل أصلًا
`--executable-path <path>`	الإشارة إلى ملف Chrome تنفيذي مخصّص
`--viewport 1280x720`	تحديد حجم نافذة ثابت
`--slim`	كشف الأدوات الأساسية الثلاث فقط (تكلفة رموز أقل)
`--no-usage-statistics`	إلغاء الاشتراك في القياس عن بُعد المجهول

إعداد عملي مناسب لـ CI:

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

اختبار إعدادك

تحقّق من سلسلة العمل كاملة بأمر واحد من البداية إلى النهاية:

افتح https://web.dev، خذ لقطة snapshot للصفحة، شغّل تدقيق Lighthouse،
ولخّص درجات الأداء وإمكانية الوصول.

ينتج عن الإعداد الصحيح: نافذة Chrome تُفتح، لقطة DOM مُهيكلة، استدعاء lighthouse_audit، وملخّص قابل للقراءة بدرجات رقمية. إن لم يحدث شيء، انتقل إلى استكشاف الأخطاء.

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

يقول الوكيل إنه لا يملك أدوات متصفح. تأكّد من أن خادم MCP مدرَج ومتصل. في Claude Code شغّل claude mcp list؛ يجب أن يظهر المُدخل كمتصل. أعد تشغيل العميل بعد تحرير الإعداد.

npx يفشل أو يتعلّق في أول تشغيل. شغّل npx -y chrome-devtools-mcp@latest --help مباشرة في طرفيتك لإظهار الخطأ الحقيقي. غالبًا يكون إصدار Node قديمًا جدًا — استخدم إصدار LTS حالي.

Chrome لا يُطلق. تأكّد من أن Chrome مُثبَّت وبإصدار مستقر حديث. إن كان لديك إصدارات متعدّدة، ثبّت واحدًا بـ --channel أو --executable-path.

--browser-url يرفض الاتصال. يجب تشغيل Chrome بـ --remote-debugging-port=9222 قبل اتصال الوكيل، ويجب استخدام المنفذ نفسه في العلامة.

استهلاك الرموز مرتفع. اللقطات والتتبّعات كبيرة. استخدم --slim للأتمتة البسيطة، وفضّل take_snapshot على take_screenshot حين تحتاج البنية فقط، واطلب من الوكيل فحص طلبات محدّدة بدلًا من إلقاء قائمة الشبكة الكاملة.

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

ادمج هذا مع خادم بروتوكول سياق النموذج تبنيه بنفسك لكشف الحالة الداخلية لتطبيقك إلى جانب أدوات المتصفح.
أضف اختبارات Playwright الشاملة كي تُثبَّت الإصلاحات التي يتحقّق منها وكيلك في المتصفح عبر CI.
استكشف وكلاء أتمتة المتصفح مع Stagehand للتحكّم بالمتصفح على مستوى أعلى مدفوع بالنيّة.

الخلاصة

يحوّل Chrome DevTools MCP وكيل الذكاء الاصطناعي لديك من مُولّد كود إلى مُولّد كود يستطيع رؤية عمله بنفسه. بكشفه للتنقّل وتتبّع الأداء وفحص الشبكة والـ console كأدوات MCP، يتيح للوكيل إغلاق حلقة الملاحظة ← الإصلاح ← التحقّق دون أن تفتح أنت أدوات المطورين يدويًا أبدًا.

ابدأ صغيرًا: اربطه بعميلك، اطلب منه تحليل صفحة بطيئة واحدة، وراقبه يكشف رؤى محدّدة. ما إن يصبح بإمكان وكيلك قراءة المتصفح، يتوقّف التصحيح عن كونه لعبة تخمين.