extension-debug

Debug the currently running extension dev session. The user said: $ARGUMENTS

Steps

1. Check for a running dev session

   • If MCP tool extension_doctor is available, call it with the project path: it reports whether a session is live, leg by leg (extension_wait with a short timeout is only for a session that is still starting)
   • If no session: start one with extension_dev (it answers when the session is ready) or tell the user to run /extension dev or npm run dev

2. Inspect the live state If MCP tool extension_inspect is available:

   • Pass include: ["html", "summary", "meta", "console", "extension_roots"]
   • If the user provided a URL in $ARGUMENTS, pass it as url
   • If the user provided CSS selectors (strings starting with #, ., or [), pass them as probe
   • Report the results in a structured way

   If MCP is not available:

   • If the session has the control channel (--allow-control on the CLI; an extension_dev session has it unless started with allowControl: false), suggest the CLI equivalent: npx extension inspect --tab <id> --include summary,html --with-console 20
   • Otherwise read dist/extension-js/<browser>/ready.json with your file tool (not a shell glob; a missing file means no session is running) to get the CDP port and suggest Chrome DevTools inspection

3. Exercise event handlers (when the bug is in an action / command / shortcut) If the session has the control channel (--allow-control on the CLI; an extension_dev session has it unless started with allowControl: false), fire the events a user would, without clicking:

   • extension_open with surface: "action", triggers the toolbar action (opens its popup, or replays chrome.action.onClicked).
   • extension_open with surface: "command" and name: "<cmd>", replays a chrome.commands.onCommand keyboard shortcut.
   • Then re-inspect or read extension_logs to see what the handler did.

   Caveat: replay carries no user gesture, so activeTab is NOT granted. If the handler depends on activeTab (e.g. chrome.scripting.executeScript on the active tab, captureVisibleTab), the result includes gesture: false and a warning, and behavior differs from a real click. For a genuine-gesture click (activeTab granted), use chrome-devtools-mcp's trigger_extension_action (Chromium only) alongside this server.

   To see what else is loaded in the browser (Chromium): extension_list_extensions.

   Safari sessions (Extension.js 4.1.21+) have no CDP, but the bridge works once the extension is enabled in Safari: extension_logs, extension_storage, extension_reload, extension_open for surfaces, extension_dom_snapshot by tab id, and the assertions (surface-rendered reads the surface through the relay there). extension_eval in content or page needs a tab the user already opened at the url; extension_open with url and extension_eval in background are blocked by Safari's MV3 background CSP. extension_inspect has no Safari path. Apple's safari-mcp can read a page in its own window beside the dev session; neither it nor this server can open the popup or background page, which stay Web Inspector, attended.

4. Diagnose common issues Based on what you find, check for:

   • "It didn't load": Check extension root count. If 0, content scripts may not be injecting. Check manifest content_scripts matches patterns and the target URL.
   • Console errors: Report top errors. Common ones:
     • Uncaught TypeError, likely a missing import or wrong module format
     • Content Security Policy, extension CSP blocking inline scripts
     • chrome.runtime.lastError, API permission missing
   • Wrong page: Check if the content script matches pattern in manifest covers the target URL
   • Shadow DOM empty: Extension root exists but shadow content is empty, likely a CSS or framework mounting issue

5. Suggest fixes based on the diagnosis