@extension.dev/mcp 10.10.9 → 10.10.10

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.10.9",
+      "version": "10.10.10",
       "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.10.9",
+  "version": "10.10.10",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 10.10.10
+
+Every sentence the server says is now backed by something it read
+(BUGS_TO_FIX_MCP.md entries 45 to 112, two audits of 2026-10-05: a claims
+census of about 2,030 sentences and a fixture sweep against the pinned
+engine and the platform).
+
+- Success is read, never assumed. Promote, submit, publish, project and
+  workspace create, logout and uninstall read the platform's or the
+  library's own answer and say `promoted-partially`, `submit-unconfirmed`,
+  `publish-unconfirmed`, `create-unconfirmed`, `not-installed` and the like
+  when it falls short. A failed read is reported as unreadable, never as an
+  empty list, across eval, open, the tab polls, session markers and
+  carriers.
+- One resolver returns the token and the project it belongs to. An
+  unnamed call sends `EXTENSION_DEV_TOKEN` and takes its project from the
+  token's own claims, never from whichever stored login is active; a named
+  project sends its stored login first, the private registry grant
+  included.
+- `extension_manifest_validate` judges each browser through the engine's
+  own prefix filter, checks every requested browser's references, refuses
+  an unknown target, and blocks only where the engine or the browser
+  refuses (a `service_worker` the engine rewrites for Firefox is a
+  warning).
+- `extension_build` reads `zip_artifacts`, refuses a stale dist, reports a
+  timeout as `build-timeout`, uses the engine's own bundle-id rule, and
+  writes `firefox-based` builds where the engine does (`dist/gecko-based`).
+- `extension_inspect` names the document it read after navigating, counts
+  uncaught exceptions as console errors, reports a section that threw as
+  `failedSections` instead of an empty value, and marks every cap.
+- `extension_open` checks popup, options and sidebar against the manifest
+  before asking the engine, says when an open could not be confirmed, and
+  never counts a tab it rendered itself as the window.
+- `extension_storage` reads a set back; `context` is gone, since the engine
+  runs every storage call in the background.
+- `extension_assert` counts only the extension's own log lines, reads the
+  guest's id from the contract, compares storage values structurally, and
+  does not credit a background the dev build injected.
+- `extension_stop` with `all` leaves sessions owned by another running
+  server alone unless `includeOtherServers` is true; stop and auth are
+  marked destructive.
+- `extension_dev` reports the control channel from `ready.json`, and a boot
+  error that is not a compile error answers `boot-failed`.
+- The tool reference `claude/rules/mcp-tools.md` is generated from the
+  schemas, and a test validates every example call in the docs against
+  them.
+- Requires Node 22.12 or later, the floor of the engine this package runs
+  in-process.
+- The release workflow publishes to npm before it pushes the version
+  commit and tag, so a failed publish no longer strands a tag.
+
 ## 10.10.9
 
 - One approval now covers several projects in one workspace
@@ -114,7 +165,7 @@
   of an extension whose policy forbids eval. Use `context: "page"` or
   `extension_dom_snapshot` there.
 
-- `extension_submit` and `extension_store_status` link to the console's
+- `extension_submit` and `extension_release_status` (include: ["stores"]) link to the console's
   Submissions tab at `/<workspace>/<project>/submissions`, where the page
   moved; the old `/stores` address still redirects. `@extension.dev/urls`
   moves to `^0.8.2`, which carries the new paths.

package/README.md

@@ -29,7 +29,7 @@ These tools give agents eyes on the live browser, so they debug from evidence in
 - **Run** the dev server with HMR in Chrome, Edge, Firefox, Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf, Zen, Floorp, or any Chromium- or Gecko-based binary, plus Safari on macOS (no HMR yet), no build config
 - **See** the live DOM, unified logs from every extension context, `chrome.storage` contents, and the loaded-extension list
 - **Act**: evaluate code in any context, trigger the action button and commands, reload the extension, replay events
-- **Ship**: validate the manifest cross-browser, build for production, publish a shareable preview, and promote builds to release channels headlessly
+- **Ship**: validate the manifest cross-browser, build for production, publish a shareable preview, and promote builds to release channels (a stable promotion asks for a human approval first)
 
 Built on [Extension.js](https://extension.js.org), the open-source cross-browser extension framework.
 
@@ -146,8 +146,8 @@ npx @extension.dev/mcp login --project <workspace>/<project>
 
 Two flags (or environment variables) narrow the server before an agent sees it:
 
-- `--features=local` exposes only the tools that work on this machine (create, run, inspect, build), which also cuts the tool list by about 40%. `--features=platform` exposes only the extension.dev account, share, release and store tools. Both are on by default. Env: `EXTENSION_DEV_FEATURES`.
-- `--no-ship` keeps everything that stays on this machine and refuses every call that reaches other people: `extension_publish`, `extension_release_promote`, `extension_submit` with `dryRun: false`, `extension_preview_web` with `share: true`, and a share revoke. Dry runs and share listing still work. Env: `EXTENSION_DEV_NO_SHIP=1`.
+- `--features=local` exposes the tools that work on this machine (create, run, inspect, build, plus docs search), which leaves 23 of the 32 tools (the 9 platform tools are off). `--features=platform` exposes only the extension.dev account, share, release and store tools. Both are on by default. Env: `EXTENSION_DEV_FEATURES`.
+- `--no-ship` refuses the calls that put something in front of other people: `extension_publish`, `extension_release_promote`, `extension_submit` with `dryRun: false`, `extension_preview_web` with `share: true`, and a share revoke. Dry runs, share listing, login and project or workspace creation still work. Env: `EXTENSION_DEV_NO_SHIP=1`.
 
 A refused call answers `E_TOOL_DISABLED` with the flag to change.
 
@@ -222,12 +222,12 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | platform | `extension_project_create` | Create the extension.dev project for a built extension, or several under one approval, headless, via device approval |
 | platform | `extension_preview_web` | Render a build in the web emulator, and share it as a link |
 | platform | `extension_shares` | List every link you have shared, and revoke one permanently |
-| platform | `extension_publish` | Publish a shareable preview to extension.dev |
+| platform | `extension_publish` | Mint a shareable link for a build extension.dev already holds (nothing is uploaded) |
 | platform | `extension_release_promote` | Promote a build to a release channel, headless |
-| platform | `extension_submit` | Submit for store review: Chrome, Firefox and Edge, through extension.dev |
+| platform | `extension_submit` | Submit for store review: Chrome, Firefox, Edge and Safari, through extension.dev |
 | platform | `extension_release_status` | Read release channels, recent builds, and store submission and review state |
 
-Browser-launching tools (`dev`, `start`) shell out to the `extension` CLI, the project's own `node_modules/.bin/extension` when present, otherwise `npx extension@<pinned>` at the version this package is verified against; everything else runs in-process.
+Browser-launching tools (`dev`, `start`) shell out to the `extension` CLI, the project's own `node_modules/.bin/extension` when present, otherwise `npx extension@<pinned>` at the version this package is verified against; build, doctor, eval, storage, reload, open, dom_snapshot and assert spawn that CLI too, and the rest runs in-process.
 
 ## Asserting instead of guessing
 
@@ -286,8 +286,8 @@ 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`.
+`extension_inspect` has no Safari path; `surface-rendered` reads the
+surface through the relay there and can pass or fail.
 
 Safari 27 and Safari Technology Preview 247 also ship Apple's own MCP server
 inside `safaridriver` (enable Safari > Settings > Developer > "Allow remote

package/claude/ARCHITECTURE.md

@@ -14,7 +14,7 @@ examples repo (GitHub)
          │
          ├── templates-meta.json        Auto-generated registry (all templates, structured)
          │     Generated by: scripts/generate-templates-meta.mjs
-         │     Published as: GitHub release asset (nightly tag)
+         │     Published at media.extension.land/templates/latest.json, with a pinned examples commit as fallback
          │     Contains: slug, surfaces, framework, permissions, files, downloads, integrity
          │     File paths are repo-relative: examples/<slug>/...
          │
@@ -24,19 +24,19 @@ examples repo (GitHub)
 
 ## Three integration layers
 
-### Layer 1: sidebar-claude template
+### Layer 1: ai-claude template
 
-**Location:** `examples/sidebar-claude/`
+**Location:** `examples/ai-claude/`
 **Role in ecosystem:** An example in the examples repo, discoverable like any other template.
 
 ```
 User: "Build me a Claude chatbot extension"
   │
   ▼
-npx extension create my-bot --template=sidebar-claude
+npx extension create my-bot --template=ai-claude
   │
   ▼
-Resolves → https://github.com/extension-js/examples/tree/main/examples/sidebar-claude
+Resolves → https://github.com/extension-js/examples/tree/main/examples/ai-claude
   │
   ▼
 go-git-it clones → copies to ./my-bot/ → installs deps → done
@@ -44,10 +44,10 @@ go-git-it clones → copies to ./my-bot/ → installs deps → done
 
 **How it integrates with the examples pipeline:**
 
-- `generate-templates-meta.mjs` auto-discovers it by scanning `examples/sidebar-claude/src/manifest.json`
+- `generate-templates-meta.mjs` auto-discovers it by scanning `examples/ai-claude/src/manifest.json`
 - Auto-detects: `uiContext: ["sidebar", "background"]`, `uiFramework: "react"`, `surfaces: ["sidebar", "background"]`
 - Curated `template.meta.json` adds: featured flag, tags (ai, claude), difficulty, useCases, firstSteps
-- CI builds it for Chrome/Edge/Firefox, packages as `.zip`, publishes in nightly release
+- CI builds it for Chrome/Edge/Firefox, packages as `.zip`, publishes it to media.extension.land
 - `templates-meta.json` includes download URLs with SHA256 integrity
 
 ### Layer 2: Claude Code rules (CLAUDE.md)
@@ -76,7 +76,7 @@ Claude now knows:
 - References `templates-meta.json` as the source of truth for template discovery
 - Documents the GitHub URL resolution pattern that `extension create` uses
 - Provides the `curl` command to fetch and query the catalog
-- Documents the nightly release download URL pattern for pre-built distributions
+- Documents the download URL pattern for pre-built distributions
 - Teaches how to contribute new templates (template.meta.json format, generator script)
 
 ### Layer 3: MCP tools
@@ -91,19 +91,19 @@ Claude (via MCP) calls extension_templates({ surface: "sidebar", tags: ["ai"] })
 MCP server fetches templates-meta.json (cached, 1hr TTL)
   │
   ▼
-Returns: [{ slug: "sidebar-claude", ... }, { slug: "sidebar-transformers-js", ... }]
+Returns: [{ slug: "ai-claude", ... }, { slug: "transformers-js", ... }]
   │
   ▼
-Claude calls extension_templates({ action: "source", slug: "sidebar-claude", files: ["src/manifest.json", "src/lib/claude.ts"] })
+Claude calls extension_templates({ action: "source", slug: "ai-claude", files: ["src/manifest.json", "src/lib/client.ts"] })
   │
   ▼
-MCP server fetches from https://raw.githubusercontent.com/extension-js/examples/main/examples/sidebar-claude/<file>
+MCP server fetches the file at the pinned examples commit
   │
   ▼
 Claude reads the source, understands the pattern, adapts it for the user
   │
   ▼
-Claude calls extension_create({ projectName: "my-bot", template: "sidebar-claude" })
+Claude calls extension_create({ projectName: "my-bot", template: "ai-claude" })
   │
   ▼
 MCP server calls extensionCreate() → same go-git-it flow as CLI
@@ -151,7 +151,7 @@ MCP server calls extensionCreate() → same go-git-it flow as CLI
 
 1. **Single source of truth.** `templates-meta.json` is generated from the actual examples. No manual sync needed. Add a template to `examples/`, run `pnpm run generate`, and all three layers pick it up.
 
-2. **The examples repo is the knowledge base.** The MCP server doesn't hard-code extension patterns, it reads them from examples. This means new patterns (like `sidebar-claude`) are immediately available to Claude without updating the MCP server.
+2. **The examples repo is the knowledge base.** The MCP server doesn't hard-code extension patterns, it reads them from examples. This means new patterns (like `ai-claude`) are immediately available to Claude without updating the MCP server.
 
 3. **Graceful degradation.** Users who don't use MCP still benefit from CLAUDE.md. Users who don't use Claude Code still benefit from the template. Each layer works independently.
 

package/claude/CLAUDE.md

@@ -41,7 +41,7 @@ The extension.dev platform ships 50+ templates in the [examples](https://github.
 
 ```bash
 # The full catalog with metadata (framework, surfaces, permissions, etc.)
-curl -sL https://github.com/extension-js/examples/releases/download/nightly/templates-meta.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'
+curl -sL https://media.extension.land/templates/latest.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'
 ```
 
 **Pre-built distributions** are available for every template:
@@ -121,7 +121,8 @@ npm run preview
 
 # Target a specific browser
 npm run dev -- --browser=firefox
-npm run build -- --browser=chrome,firefox
+npm run build -- --browser=chrome
+npm run build -- --browser=firefox
 
 # Zip for distribution
 npm run build -- --zip
@@ -200,13 +201,13 @@ The `extension_dom_snapshot` MCP tool wraps this verb one-to-one.
 
 **Debugging protocol (Chromium CDP): `extension_inspect` MCP tool.** Connects directly to the running session's debug port. Use it when the bridge is not enough: closed shadow roots (`deepDom`), selector probes, DOM snapshots, console summaries, or navigating the tab to a URL before inspecting. Returns structured events:
 
-- `page_html` - full injected HTML (after content scripts run)
-- `page_html_summary` - root/script/style/link counts
-- `page_meta` - readyState, viewport, frame count
-- `dom_snapshot` - structured tree (tag, id, classes, role, max 500 nodes)
-- `console_summary` - error/warn counts + top 5 unique messages
-- `selector_probe` - per-selector element counts and samples
-- `extension_root_tree` - extension root elements with reinject generations
+- `html` - full injected HTML (after content scripts run), with `htmlTruncated` when cut
+- `summary` - root/script/style/link counts
+- `meta` - readyState, viewport, frame count
+- `domSnapshot` - structured tree (tag, id, classes, role; `domSnapshotTruncated` names the cap)
+- `console` - error/warn counts + top unique messages
+- `probes` - per-selector element counts and samples
+- `extensionRoots` - extension root elements with reinject generations
 
 ### Unified logging (`--logs`)
 
@@ -229,7 +230,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.
+- **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 (`surface-rendered` reads the surface through the relay there). `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)

package/claude/README.md

@@ -12,13 +12,13 @@ claude/
   ARCHITECTURE.md         How the template, CLAUDE.md, and MCP layers connect
   commands/
     extension.md          /extension: create, dev, build, add features, debug
-    extension-add.md      /extension-add: add sidebar, popup, content script, etc.
+    extension-add.md      /extension-add: plan a sidebar, popup, content script, etc. (the tool writes no files)
     extension-debug.md    /extension-debug: live DOM/console inspection
     extension-publish.md  /extension-publish: store submission prep
   rules/
     extension-dev.md      Core rules: project structure, manifest, commands
     cross-browser.md      Cross-browser manifest field mapping
-    mcp-tools.md          Full MCP tool specification and design doc
+    mcp-tools.md          MCP tool reference, generated from the server's schemas (pnpm docs:tools)
   examples/
     create-extension.md   Example prompt: scaffold and customize an extension
     add-sidebar.md        Example prompt: add a sidebar panel to an existing extension
@@ -59,7 +59,7 @@ Claude Code will automatically pick up the instructions and know how to:
 
 ## How it connects to the examples repo
 
-The [examples repo](https://github.com/extension-js/examples) publishes `templates-meta.json` as a nightly release asset. This file is the single source of truth for:
+The template catalog (`templates-meta.json`) is read from `media.extension.land/templates/latest.json` first and from a pinned commit of the [examples repo](https://github.com/extension-js/examples) as the fallback, with a bundled snapshot when neither answers. It is the single source of truth for:
 
 - **CLAUDE.md**, references it so Claude knows all available templates
 - **MCP tools**, `extension_templates` fetches and queries it at runtime
@@ -69,4 +69,4 @@ When a new template is added to the examples repo, all three layers pick it up a
 
 ## License
 
-MIT
+Apache-2.0

package/claude/commands/extension-debug.md

@@ -33,7 +33,7 @@ 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.
+   **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 (`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:

package/claude/commands/extension-publish.md

@@ -22,7 +22,7 @@ Default to `chrome` and `firefox`. `all` means chrome, firefox, edge and safari.
    - Firefox: a missing `browser_specific_settings.gecko.data_collection_permissions` declaration, which AMO now requires for new add-ons and updates
    - a bundle over 10 MB, source maps in the production build, missing 128px icon
 
-4. **Pick the build to submit.** Store review runs from a build on extension.dev, not from local files. Call `extension_release_status` with `include: "releases"` to find the sha. If the user has not shipped this version yet, say so and offer `extension_publish` first.
+4. **Pick the build to submit.** Store review runs from a build on extension.dev, not from local files. Call `extension_release_status` with `include: ["releases"]` to find the sha. If no build of this version is listed, say so: a build comes from a push to the project's repository (the platform builds it), not from `extension_publish`, which only shares a build that already exists.
 
 5. **Rehearse.** Call `extension_submit` with the browsers and `buildSha`, leaving `dryRun` at its default (`true`). Show the per-store credential rows. A store whose credentials are not healthy is fixed in the extension.dev console (the response names the page); drop it from `browsers` or stop.
 

package/claude/commands/extension.md

@@ -12,7 +12,7 @@ Parse the user's intent from `$ARGUMENTS` and execute the matching action:
 ### "create <name>" or "new <name>", Scaffold a new extension
 
 1. If MCP tool `extension_templates` is available, use it to find the best template matching the user's description (check for surface type, framework, and keywords)
-2. If not, check the template catalog: `curl -sL https://github.com/extension-js/examples/releases/download/nightly/templates-meta.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'`
+2. If not, check the template catalog: `curl -sL https://media.extension.land/templates/latest.json | jq '.templates[] | {slug, description, uiFramework, surfaces}'`
 3. Run `npx extension@latest create <name> --template=<best-match>`
 4. Report what was created and suggest `npm run dev`
 

package/claude/rules/cross-browser.md

@@ -70,8 +70,8 @@ Older Firefox ignores the `chromium:world` field and runs in the default isolate
 ## API differences
 
 - Chromium: use `chrome.*` namespace for Chrome-specific APIs (sidePanel, etc.)
-- Firefox: use `browser.*` namespace (auto-polyfilled by the framework)
-- For cross-browser code: use `browser.*` when possible, the polyfill maps it to `chrome.*` on Chromium
+- Firefox: `browser.*` is native; `chrome.*` also works there for most APIs
+- For cross-browser code: the polyfill that maps `browser.*` to `chrome.*` on Chromium is on for `extension_dev` and `extension_start` by default and OFF for `extension_build` (pass `polyfill: true` to the build, or write `chrome.*` and check `typeof browser` yourself)
 
 ## Testing across browsers
 
@@ -82,5 +82,6 @@ npm run dev -- --browser=firefox
 npm run dev -- --browser=edge
 
 # Build for multiple browsers
-npm run build -- --browser=chrome,firefox
+npm run build -- --browser=chrome
+npm run build -- --browser=firefox
 ```