پیکربندی

Matthias Rohmer
José Luis Zapata

می‌توانید Chrome DevTools برای عامل‌ها را پیکربندی کنید تا نحوه تعامل آن با مرورگر، ابزارهای فعال‌شده، و نحوه مدیریت داده‌ها را سفارشی‌سازی کنید.

سرور را با ارسال پرچم‌های خط فرمان در آرایه args فایل پیکربندی کارخواه «پروتکل بافتار مدل» (MCP) پیکربندی کنید. این معمولاً فایل config.json است.

برای مثال، برای اجرای Chrome در حالت بدون سر و استفاده از کانال Canary، از پیکربندی زیر استفاده کنید:

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

سناریوهای پیکربندی متداول

سناریوهای زیر روش‌های رایج پیکربندی Chrome DevTools برای عامل‌ها را شرح می‌دهد.

اجرا در حالت بدون سر

برای انجام وظایف پس‌زمینه‌ای بدون پنجره مرورگر نمایان، Chrome را در حالت بدون سر (بدون واسط کاربر) اجرا کنید. پرچم --headless را به آرگومان‌های سرورتان اضافه کنید.

اتصال به جلسه مرورگر موجود

به‌طور پیش‌فرض، DevTools برای عامل‌ها نمونه Chrome جدیدی را شروع می‌کند. بااین‌حال، می‌توانید نماینده‌تان را به جلسه مرورگر موجود متصل کنید. این ویژگی زمانی مفید است که نماینده شما نیاز داشته باشد مشکلی را در جلسه‌ای که قبلاً شروع کرده‌اید بررسی کند (برای مثال، اگر قبلاً به سیستم وارد شده‌اید).

به دو روش می‌توانید به جلسه موجود متصل شوید:

اتصال خودکار (Chrome 144 و نسخه‌های جدیدتر)

اگر از پرچم --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"]

مرجع گزینه‌های پیکربندی

بخش‌های زیر پرچم‌های پیکربندی دردسترس را فهرست می‌کند. برای اطلاع از جدیدترین گزینه‌ها و به‌روزرسانی‌ها، به مخزن Chrome DevTools MCP GitHub مراجعه کنید.

گزینه‌های اتصال

از این گزینه‌ها برای پیکربندی نحوه اتصال سرور به Chrome استفاده کنید.

پرچم نوع پیش‌فرض شرح
‫--autoConnect یا --auto-connect بولی false به‌طور خودکار به نمونه Chrome (نسخه ۱۴۴ و بالاتر) که به‌صورت محلی اجرا می‌شود متصل می‌شود. اشکال‌زدایی از راه دور باید بااستفاده از 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 دسترسی به شبکه را با مسدود کردن الگوهای نشانی وب مشخص‌شده محدود می‌کند (از URLPattern استفاده می‌کند). پیمایش‌ها و منابع فرعی را مسدود می‌کند.
‫--allowedUrlPattern یا --allowed-url-pattern آرایه false دسترسی به شبکه را با مجاز کردن فقط الگوهای نشانی وب مشخص‌شده محدود می‌کند. به Chrome 149 یا بالاتر نیاز دارد.
‫--redactNetworkHeaders یا --redact-network-headers بولی false سرصفحه‌های حساس شبکه را قبل‌از برگرداندن به کارخواه محو می‌کند.
‫--usageStatistics یا --usage-statistics بولی true جمع‌آوری آمار کاربرد را برای بهبود ابزار فعال می‌کند. همچنین می‌توان بااستفاده از متغیرهای محیطی CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS یا CI آن را غیرفعال کرد.
‫--performanceCrux یا --performance-crux بولی true نشانی‌های وب را از ردپاهای عملکرد به Google CrUX API ارسال می‌کند تا داده‌های تجربه کاربر واقعی را واکشی کند.
‫--javascriptEvaluation یا --javascript-evaluation بولی true برای غیرفعال کردن اجرای جاوا اسکریپت، روی false تنظیم کنید. وقتی غیرفعال باشد، ابزارهای ارزیابی اسکریپت غیرفعال می‌شوند، پارامتر initScript از navigate_page خاموش می‌شود، و پیمایش به نشانی‌های وب 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 را فعال می‌کند. به Chrome نسخه ۱۴۹ یا بالاتر با ویژگی‌های WebMCP فعال‌شده نیاز دارد.
‫--memoryDebugging یا --memory-debugging بولی false ابزارهای اشکال‌زدایی حافظه را فعال می‌کند.

گزینه‌های نماگرفت

از این گزینه‌ها برای سفارشی‌سازی نحوه ضبط نماگرفت توسط عامل استفاده کنید.

پرچم نوع پیش‌فرض شرح
‫--screenshotFormat یا --screenshot-format رشته false قالب خروجی پیش‌فرض (png) را لغو می‌کند. گزینه‌ها: jpeg، png، و webp. قالب‌های jpeg و webp کوچک‌تر هستند که به کاهش اندازه بافت در مکالمه‌های هوش مصنوعی کمک می‌کند.
‫--screenshotQuality یا --screenshot-quality شماره false کیفیت فشرده‌سازی (۰ تا ۱۰۰) را برای jpeg و webp ملغی می‌کند.
‫--screenshotMaxWidth یا --screenshot-max-width شماره false حداکثر عرض به پیکسل. نماگرفت‌های بزرگ‌تر کوچک می‌شوند.
‫--screenshotMaxHeight یا --screenshot-max-height شماره false حداکثر ارتفاع به پیکسل. نماگرفت‌های بزرگ‌تر کوچک می‌شوند.

گزینه‌های آزمایشی

از این گزینه‌ها برای فعال کردن ویژگی‌های آزمایشی درحال توسعه استفاده کنید.

پرچم نوع پیش‌فرض شرح
‫--experimentalDevtools یا --experimental-devtools بولی false خودکارسازی را در هدف‌های DevTools فعال می‌کند.
‫--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 نقشه‌های منبع را در DevTools فعال می‌کند. از --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 کار می‌کند).