@extension.dev/mcp 10.9.0 → 10.10.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 50+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "10.9.0",
+      "version": "10.10.1",
       "category": "development",
       "author": {
         "name": "Cezar Augusto"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "extension-mcp",
   "description": "MCP tools for browser extension development: scaffold from 50+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox. Ships /extension, /extension-add, /extension-debug, and /extension-publish commands.",
-  "version": "10.9.0",
+  "version": "10.10.1",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,155 @@
 # Changelog
 
+## 10.10.1
+
+Five Gecko findings from one agent session on Firefox and Waterfox
+(BUGS_TO_FIX_MCP.md entries 5 to 9), each replayed against a live Firefox
+Nightly before and after the fix where the shape allowed it, plus four more
+that followed them the same week, and the engine release that carries the
+root-cause fix for the first of them.
+
+- `extension-create`, `extension-develop` and `extension-install` move from
+  4.1.29 to 4.1.30. That engine settles a promise before a surface relay
+  replies to an eval (the root cause behind the first entry below, filed
+  from this repo as extension.js 512), names a missing tab, a refused url,
+  a closed surface and a browser exit on every act verb instead of a
+  generic refusal, and lets `reload` resolve a surface's tab. The relay
+  wrapper below stays: a project that pins an older engine in its own
+  node_modules still drives that engine.
+
+- `extension_eval` on a surface that answers through the in-bundle relay
+  (every Gecko session, and Chromium MV2) never hands the relay a promise.
+  The relay evaluates synchronously and passes the raw value to
+  `sendResponse`; a promise is not cloneable, Firefox reports that to the
+  sender as no reply, and the bridge then called the surface "not open"
+  while the page was still running the expression. The wrapper now settles
+  a thenable inside the page under a token, and the tool polls until it is
+  done: an async expression returns its value, a rejection answers `E_EVAL`
+  with the page's own message, and one that never settles answers
+  `E_WAIT_TIMEOUT` naming where the result will land. The engine's "open it
+  first: extension open newtab" hint is now spoken as the tool call it means.
+- `extension_inspect` on Gecko reads a page inside the extension through
+  its surface relay: a url that matches a declared surface document (the
+  full `moz-extension://` address, the document path, or its file name)
+  routes to that context instead of the tab injection, which Firefox
+  refuses into extension pages with "Missing host permission for the tab".
+  An extension url that matches no declared surface says so and names the
+  ones the manifest declares.
+- `extension_stop` reaps the browser the launcher recorded in `ready.json`
+  (`browserPid`, `launcherPid`, and any process holding `profilePath`), so
+  a Firefox started on a custom profile, or one whose argv never names the
+  project, no longer survives a `stopped` answer with `reaped: []`.
+- `extension_doctor` no longer calls a Gecko session unhealthy over a
+  browser exit that the executor outlived: Firefox hands a fresh profile to
+  a relaunched process and the first one exits 0, which the engine's browser
+  leg reports as a failure while storage probes and evals keep answering.
+  That leg becomes a warning that says so, and any other failure still
+  counts.
+- `extension_browsers` detect finds a managed binary as deep as the cache
+  writes it (a Firefox Nightly sits six levels down inside its app bundle),
+  so it no longer reports the system Firefox as available while
+  `extension_dev` launches the cached Nightly. When both exist, the entry
+  carries `systemBinaryPath` and a `devLaunches` line saying which one dev
+  starts and how to choose the other. `extension_wait` reports `browserPid`
+  and `profilePath` from the contract.
+- `extension_open` with surface `sidebar` on Gecko no longer stops at the
+  engine's "sidePanel not available", a Chromium API named on a Firefox
+  engine. It asks the sidebar relay whether the `sidebar_action` panel is
+  open and reports `status: "already-open"` when it is (Firefox opens the
+  panel at install, so it usually is); when it is not, the document is
+  rendered as a tab with the gesture rule stated (Firefox opens the panel
+  only from the toolbar button or View > Sidebar, Bugzilla 1392624).
+- `extension_eval` with context `page` and a `moz-extension://` url on
+  Gecko evaluates through the surface relay of the document that url names,
+  with a warning naming the context to pass next time, instead of "chrome.
+  scripting is not available ... use context background". An extension url
+  that matches no declared surface says which surfaces the manifest
+  declares. The url-to-surface mapping now lives in one place for inspect
+  and eval.
+- `extension_dev` with `port: 0` no longer warns "Requested port 0 was not
+  available": 0 asks the engine for any free port, so the note now says
+  which port it picked, and the collision wording stays for a numbered port
+  the server could not bind.
+
+## 10.10.0
+
+Safari was the one engine this server treated as a dead end, while the
+Extension.js it shells out to had grown a working Safari dev loop. The client
+now rides that loop, and its pinned CLI packages move to the release that
+has it.
+
+- `extension-create`, `extension-develop` and `extension-install` move from
+  4.1.2 to 4.1.29, the stable release that carries the `navigate` verb
+  (first shipped in a 4.1.28 canary). On Safari that engine reloads the extension
+  on every save through the extension's own bridge, streams background and
+  content lines into the session's log file, and points a tab at a url
+  without eval; a project with no local Extension.js now gets all of that
+  from the pin.
+- The bridge tools work on a Safari dev session started with
+  `allowControl` or `allowEval`: `extension_storage`, `extension_reload`,
+  `extension_open` for surfaces, `extension_dom_snapshot` by tab id,
+  `extension_logs`, and the assertions `content-script-injected`,
+  `background-worker-booted`, `storage-key-present` and
+  `console-errors-empty`, measured live on Safari 27. `extension_eval` in
+  `content` or `page` needs a tab already open at the url, and Safari's MV3
+  background CSP blocks eval in `background` and the bridge's `url`
+  navigation, which the engine reports by name. `surface-rendered` and
+  `extension_inspect` still need a target list Safari does not expose, and
+  say so.
+- `extension_browsers` reports Safari's version and an `automation` block
+  (the safaridriver beside it and whether it speaks `--mcp` and `--bidi`),
+  and `extension_doctor` with no `projectPath` gains a `safari-agent` leg,
+  so an agent learns when Apple's Safari MCP server can pair with this one.
+  The packaged CLAUDE.md and `/extension-debug` describe that pairing.
+- `extension_open` with `url` asks the engine's `navigate` verb first, a
+  static tabs call inside the extension that works where an MV3 background
+  refuses eval, which is every Safari session. Only an engine that does not
+  know the verb yet falls back to the background eval, and that fallback
+  names the upgrade when Safari's CSP refuses it.
+- If a dev session records a safaridriver session in `ready.json`
+  (`webdriverPort`, `webdriverSessionId`), `extension_eval` with context
+  `page` and `extension_open` with `url` use it for the page's main world,
+  and `extension_doctor` adds a `safari-window` leg; with no such record
+  the leg is a skip and both tools take the bridge.
+
+Four defects agents met while driving the server on real extension work
+(BUGS_TO_FIX_MCP.md entries 1 to 4) close in the same release.
+
+- The initialize result now carries `instructions`: four lines that name
+  the moments (run, wait, inspect, drive, build an extension) and the tools
+  that own them, for clients that hide tool descriptions behind a search
+  step and would otherwise show the model only a server name and a tool
+  count. `createServer()` is exported so a client can initialize against
+  the same server object the stdio path connects.
+- `extension_open` with surface `newtab`, `history` or `bookmarks` resolves
+  the `chrome_url_overrides` page itself and opens it by url. The engine's
+  `open` verb never knew those surfaces and answered `E_ARGS` "unknown
+  surface" to exactly what the tool description promised; an override page
+  is only ever a tab, so this is the surface, not a fallback, and the hint
+  says so.
+- `extension_open` with surface `sidebar` on Chromium, when Chrome refuses
+  `sidePanel.open()` for lack of a user gesture, opens the extension's own
+  sidebar page in a tab, dispatches a synthetic click on it over CDP, calls
+  `chrome.sidePanel.open` from inside that click and closes the tab. The
+  panel that opens is the real one; the result reports `gesture:
+  "synthetic-click"` and a warning that the toolbar wiring was not
+  exercised. If the click does not open it either, the sidebar document is
+  rendered as a tab with the reason in a warning, and if even that fails
+  the refusal gains a hint naming the url to read instead of ending the
+  road. Headless sessions keep their tab fallback and never click.
+- `extension_eval` on a Chromium MV3 session evaluates extension pages over
+  CDP: contexts `popup`, `options`, `sidebar`, `newtab`, `history` and
+  `bookmarks`, and context `page` with a `chrome-extension://` url. The
+  inspector path is not governed by the extension page CSP that blocks the
+  in-bundle relay's string eval, and script injection could never reach an
+  extension page at all, which is where the misleading "Extension manifest
+  must request permission to access this host" came from. A page that is
+  not open answers `E_NO_TARGET` with the `extension_open` call that opens
+  it; a thrown expression answers `E_EVAL` with the exception text; a bare
+  top-level `await` parses, as in the DevTools console; MV2 Chromium and
+  Gecko sessions keep the relay. Both this path and the sidebar gesture were
+  measured live on Chrome for Testing 151 before release.
+
 ## 10.9.0
 
 The client ran its browser work through CLI packages pinned three minor

package/README.md

@@ -173,6 +173,40 @@ check registry, so a document from one lane can never be mistaken for the
 other's. Each check here names the preview check it is the live-browser
 counterpart of, and a contract test holds the two grammars together.
 
+## Safari
+
+A Safari dev session runs on the same bridge as every other engine. On
+Extension.js 4.1.28 or newer, `extension_dev --browser=safari` (macOS with
+Xcode) builds the app, opens it, and, once you enable the extension in
+Safari > Settings > Extensions, reloads it on every save through the
+extension's own socket to the dev server and streams its background and
+content lines into the session's log file. With `allowControl` or
+`allowEval`, the control channel is on too: `extension_storage`,
+`extension_reload`, `extension_dom_snapshot` (by tab id), `extension_open`
+for surfaces, `extension_logs`, and the assertions `content-script-injected`
+(on a content line at the url), `background-worker-booted`,
+`storage-key-present` and `console-errors-empty` all work against it.
+`extension_eval` in `content` or `page` needs a tab already open at the url,
+and `extension_open` with `url` cannot open one on Safari: the bridge
+navigates through a background eval, and Safari's MV3 background CSP blocks
+eval, which also blocks `extension_eval` in `background`. Open the page in
+Safari by hand, then read it. Safari has no CDP or RDP, so
+`extension_inspect` has no Safari path and `surface-rendered` answers
+inconclusive, pointing at `extension_dom_snapshot` with a `context`.
+
+Safari 27 and Safari Technology Preview 247 also ship Apple's own MCP server
+inside `safaridriver` (enable Safari > Settings > Developer > "Allow remote
+automation and external agents", then
+`claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp`). It drives an
+isolated automation window with page-level tools and has no extension-aware
+tool. It runs beside a Safari dev session, because this server never opens
+an automation session of its own: if a dev session ever records one in
+`ready.json` (`webdriverPort`, `webdriverSessionId`), `extension_eval` with
+context `page` and `extension_open` with `url` use it for the page's main
+world, and `extension_doctor` shows it as a `safari-window` leg; today no
+Extension.js release records one, and that leg reads `skip`.
+`extension_browsers` reports whether the machine's safaridriver has `--mcp`.
+
 ## Sharing a build in progress
 
 An unpacked extension is unusually hard to hand to someone: the only way to look at a colleague's work-in-progress has been to take their zip and run untrusted code with real browser permissions on your own machine. `extension_preview_web` with `share: true` uploads the `dist/` it just built and returns a link that renders those exact bytes in the emulator. Whoever opens it installs nothing and signs in to nothing, which is what lets a designer, a PM, or a reviewer into the loop at all. Those bytes run in an isolated sandbox origin or they do not run at all: preview refuses a shared build rather than serving it in its own renderer. Sharing needs auth (`extension_auth` or `EXTENSION_DEV_TOKEN`), the link lives 30 days, and `DELETE`ing the returned `revokeUrl` with the same token kills it early. Re-sharing an unchanged build returns that same link rather than a second one, and only a revoked link is replaced by a different one, because revocation is permanent: the address is burned and never resolves again. That makes `revokeUrl` the handle to the link you just made, so every share is also appended to `.extension.dev/shared-previews.json` in the project (gitignored) so it survives losing the tool output. The upload holds up to 2,000 files and about 64MB of text, or roughly 48MB when the build is mostly images, fonts or wasm, which travel base64-encoded. Without `share`, the tool returns a local-only deep link and uploads nothing.

package/claude/ARCHITECTURE.md

@@ -16,10 +16,7 @@ examples repo (GitHub)
          │     Generated by: scripts/generate-templates-meta.mjs
          │     Published as: GitHub release asset (nightly tag)
          │     Contains: slug, surfaces, framework, permissions, files, downloads, integrity
-         │
-         ├── public/<slug>/             Staged sources + pre-built distributions
-         │     ├── src/                 Committed source for website consumption
-         │     └── dist/<browser>/      Pre-built .zip and .xpi files
+         │     File paths are repo-relative: examples/<slug>/...
          │
          └── artifacts/                 Build pipeline output
                └── <slug>.<browser>.zip  Distributable archives

package/claude/CLAUDE.md

@@ -228,6 +228,7 @@ npm run dev -- --logs info --log-url "example.com"
 ### Other debugging tools
 
 - Use `--browser=firefox` to test cross-browser compatibility
+- **Safari (macOS).** On Extension.js 4.1.28 or newer, `--browser=safari` builds the app, opens it, and after you enable the extension in Safari > Settings > Extensions it reloads on every save through the extension's bridge and streams background and content lines into the session log. Start it with `allowEval: true` and the bridge tools work: `extension_storage`, `extension_reload`, `extension_open` for surfaces, `extension_dom_snapshot` by tab id, `extension_logs`, and the assertions except `surface-rendered`. `extension_eval` in `content` or `page` needs a tab already open at the url, which you open in Safari by hand: `extension_open` with `url` and `extension_eval` in `background` are blocked by Safari's MV3 background CSP, and the engine says so. Safari has no CDP or RDP, so `extension_inspect` has no Safari path. Apple's Safari MCP server (`claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp`, Safari 27+, after enabling Safari > Settings > Developer > "Allow remote automation and external agents") reads a page in its own isolated window with no extension-aware tool, and runs beside a dev session, since this server opens no automation session of its own.
 - Check `dist/<browser>/` for build output
 - Use `--wait` flag to check if dev session is ready (outputs ready.json contract)
 - Use `npm run start` to test production builds (builds first, then launches)
@@ -240,6 +241,10 @@ npm run dev -- --logs info --log-url "example.com"
 
 These replay your captured listeners, so they work on Chrome and Firefox, but carry **no user gesture**, so `activeTab` is not granted (the result reports `gesture: false`, plus a `warning` when the manifest declares `activeTab`). If you need a genuine-gesture click (activeTab granted), use [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)'s `trigger_extension_action` (Chromium only) alongside this server.
 
+Two surfaces the engine's `open` verb cannot serve are handled by the MCP tool itself. `extension_open` with `surface: "newtab"`, `"history"` or `"bookmarks"` resolves the `chrome_url_overrides` page and opens it in a tab, which is the only place the browser renders it. `extension_open` with `surface: "sidebar"` on Chromium, when Chrome refuses `sidePanel.open()` for lack of a user gesture, opens the extension's own sidebar page in a tab, dispatches a synthetic click on it over CDP, calls `chrome.sidePanel.open` from inside that click and closes the tab: the real panel opens, the result says `gesture: "synthetic-click"`, and a warning notes that the toolbar wiring was not exercised. If that fails too, the sidebar document is rendered as a tab and the warning names the reason.
+
+On a Chromium MV3 session, `extension_eval` reaches extension pages over CDP rather than the in-bundle relay: contexts `popup`, `options`, `sidebar`, `newtab`, `history`, `bookmarks`, and `context: "page"` with a `chrome-extension://` url. The MV3 extension CSP blocks the relay's string eval and script injection cannot reach an extension page at all, while the inspector path is governed by neither. The page must already be open (`extension_open` first); a closed one answers `E_NO_TARGET` with the call that opens it.
+
 ## Contributing templates to the examples repo
 
 If you create a new extension pattern worth sharing:

package/claude/commands/extension-debug.md

@@ -33,6 +33,8 @@ Debug the currently running extension dev session. The user said: $ARGUMENTS
 
    To see what else is loaded in the browser (Chromium): `extension_list_extensions`.
 
+   **Safari sessions** (Extension.js 4.1.28+) 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 except `surface-rendered`. `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.

package/claude/rules/mcp-tools.md

@@ -761,6 +761,20 @@ is carried as `value.sessionCommand`.
       "engine": "gecko",
       "cdpSupport": false,
       "rdpSupport": true
+    },
+    {
+      "browser": "safari",
+      "binaryPath": "/Applications/Safari.app/Contents/MacOS/Safari",
+      "source": "system",
+      "engine": "webkit",
+      "version": "27.0",
+      "cdpSupport": false,
+      "rdpSupport": false,
+      "automation": {
+        "safaridriver": "/usr/bin/safaridriver",
+        "mcp": true,
+        "bidi": true
+      }
     }
   ],
   "managed": {
@@ -770,6 +784,8 @@ is carried as `value.sessionCommand`.
 }
 ```
 
+`automation` appears on Safari only (macOS): whether the safaridriver beside it speaks `--mcp` (Apple's Safari MCP server, Safari 27+) and `--bidi`. The hint says how to pair that server when it is there.
+
 **Why this matters:** Before Claude runs `extension_dev --browser=firefox`, it should know if Firefox is actually installed. This prevents "browser not found" errors and lets Claude suggest `extension_browsers` when needed. Especially important for Docker/devcontainer environments.
 
 ---