@extension.dev/mcp 10.0.0 → 10.2.0

package/.claude-plugin/marketplace.json

@@ -9,8 +9,8 @@
     {
       "name": "extension-mcp",
       "source": "./",
-      "description": "MCP tools for browser extension development: scaffold from 60+ 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.0.0",
+      "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.2.0",
       "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 60+ 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.0.0",
+  "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.2.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## 10.2.0
+
+A production walk of the full share-and-publish loop, then a fix for every
+roughness it surfaced, on top of a week of engine tracking and preview
+hardening. Everything landed since 10.1.0 ships here; the 10.1.1 version
+bump was never published and is folded in.
+
+- Revoking a share accepts the ids the platform actually mints: `gen_` plus
+  64 hex characters, with the older 32-character form still valid. A
+  malformed reference is refused by name, with what a real id looks like,
+  instead of being silently cut down to a 32-character prefix that revokes
+  nothing while reporting the wrong cause.
+- Every revoke handle the tools return points at `www.extension.dev`
+  directly, so one plain DELETE works. The apex `extension.dev` answers
+  DELETE with a redirect, and a caller that does not follow redirects got
+  "Redirecting..." back while the share stayed live.
+- `extension_doctor` hands over the CLI's own report when the engine exits
+  nonzero with output the server cannot parse: the response carries
+  `cliReport`, the doctor's actual check list and remediations, instead of
+  discarding it and guessing that the local CLI is stale.
+- `extension_inspect` with no `url` ranks the extension's own surfaces
+  first and the toolchain's pages last, so it no longer inspects the
+  Extension.js welcome surface and reports on the wrong document. When only
+  toolchain or override pages are open, a warning names exactly which page
+  was inspected and how to target yours.
+- `extension_publish` against a host where the token's project does not
+  exist now says what to do: check the token's scope with `extension_auth`,
+  create the project first at extension.dev/new, or log in against a
+  project that exists there.
+- `extension_auth status` asks the platform who the stored credential
+  really is instead of trusting the file on this machine, and reports the
+  three answers apart: the server confirmed it, the server refused it and
+  the workspace shown is only a local claim, or the server could not be
+  reached and nothing here is server confirmed. A credential minted against
+  a development deployment reads as refused where production refuses it,
+  which is what it always was and never said.
+- The MCP `isError` flag now agrees with the envelope: every `ok: false`
+  result is marked `isError: true`, so an agent branching on the transport
+  flag no longer reads a platform refusal, a publish 404 or an auth 401, as
+  success.
+- `extension_preview_web` with `share: true` no longer fails a working
+  share because the local dev lane is dead: the uploaded link is what was
+  asked for, so the result is `ok: true` with status `shared` and a warning
+  naming the unreachable local leg, which is expected outside the
+  extension.dev monorepo.
+- The Extension.js engine pin moved to 4.0.20, the server asks the engine
+  its version and JSON support from its published capabilities instead of
+  paying for a second build to find out, and a canary pin no longer parses
+  to NaN.
+- Safari packaging lets an agent name the app and bundle id it is
+  packaging, and the docs say what a derived bundle id actually costs a
+  developer instead of claiming Apple rejects it.
+- Preview and share housekeeping: `hostUrl` is pinned to a local server,
+  stale carriers are cleared on start and swept on every exit, re-sharing
+  is documented for what it really does, and the CORS verdict is read off
+  the last hop a browser would follow.
+- The offline template fallback points at the published corpus, three
+  control refusals are told apart instead of sharing one message, and a
+  stray binary file no longer ships in the package.
+
+## 10.1.0
+
+A six-lens audit of the whole surface (auth, platform, run, see, act and
+build, plumbing) followed by a fix pass over everything it confirmed. 33
+fixes, the ones you would notice first:
+
+- A failed spawn of the dev CLI (npx missing from PATH) no longer crashes
+  the whole MCP server; it fails that one call with guidance.
+- `extension_wait` now ignores ready contracts stamped before the current
+  session, so a leftover file from a crashed run can no longer report the
+  previous session's compile error as yours.
+- `extension_create` never deletes a directory it did not create: the
+  transient-failure cleanup used to wipe pre-existing directories, including
+  their `.git`, when scaffolding into one.
+- `extension_submit` dry runs are platform-primary: a platform-reported
+  preflight failure can no longer be overwritten by locally computed store
+  health, and token-only CI callers no longer fail the dry run for lacking a
+  local credentials file. The tool also gained a `projectPath` input so the
+  STORE.md advisory check reads the project, not the server's cwd.
+- `manifest.json` with `world: "MAIN"` no longer fails Firefox validation:
+  Firefox has supported the MAIN world since 128. The rule is now a
+  strict_min_version advisory.
+- Device login reports hard server errors as errors, on both the tool and
+  the CLI paths, instead of authorization-pending or a bogus timeout; the
+  login flow now enforces the same cleartext-http refusal as every other
+  token-bearing path, validates the returned project scope before storing
+  credentials, and the CLI prints the one-click approval link.
+- `extension_publish` with a pinned buildSha no longer fills the response
+  with a different build's metadata when the pin is not in the local index.
+- `extension_shares` no longer labels your own expired shares as "not owned
+  by this token" when listing with `status: "live"`, and revocation is only
+  reported permanent when the platform confirmed it.
+- `extension_logs` accepts the `newtab`, `history`, and `bookmarks`
+  contexts, `level: "off"` silences console output instead of returning all
+  of it, and a stream error mid-follow returns what was collected instead
+  of discarding it.
+- `extension_stop` and session bookkeeping survive an MCP restart: session
+  markers are cleaned when a session exits on its own, single-project stop
+  consults the same on-disk markers as `all: true`, orphan reaping escapes
+  regex metachars in project paths and only kills plausible session
+  processes, and a replaced session can no longer unregister its successor.
+- `extension_open` trusts the live browser over the computed id hash when
+  they disagree (symlinked dist paths), so it no longer navigates to a
+  nonexistent extension id and no longer reports a successfully opened
+  surface as a failure.
+- Offline first runs work: the bundled template catalog snapshot is now the
+  fallback when the network and cache are both unavailable, a corrupted
+  cache file heals instead of erroring, and a shapeless 200 response is no
+  longer cached for an hour.
+- `extension-mcp --help`, `--version`, and unknown commands now answer
+  instead of silently starting a stdio server.
+- The release pipeline bumps the version before building, so the published
+  bundle reports the version it ships as, with an assertion gating publish
+  on it and on the type declarations existing.
+- Docs and drop-ins caught up with the code: template count corrected to
+  50+, the AI template slugs are `ai-claude` and `ai-chatgpt`, Firefox
+  support noted for `extension_list_extensions` and Safari for
+  `extension_submit`, and the `extension_dom_snapshot` description names
+  which subpaths need the debug port.
+
 ## 10.0.0
 
 Every tool now returns the same frame. Before this, 28 tools hand-built 142

package/README.md

@@ -17,7 +17,7 @@ claude mcp add extension-dev npx @extension.dev/mcp
 
 Works with Claude Code, Claude Desktop, Cursor, and any MCP client.
 
-[extension.dev](https://extension.dev) · [Documentation](https://extension.js.org) · [Templates](https://templates.extension.dev) · [Examples](https://github.com/extension-js/examples) · [Discord](https://discord.gg/v9h2RgeTSN)
+[extension.dev](https://extension.dev) · [Extension.js](https://extension.js.org) · [Templates](https://templates.extension.dev) · [Examples](https://github.com/extension-js/examples) · [Discord](https://discord.gg/v9h2RgeTSN)
 
 ## Why an MCP server for extensions
 
@@ -25,7 +25,7 @@ Extensions fail silently: content scripts that never inject, panels that never o
 
 These tools give agents eyes on the live browser, so they debug from evidence instead of guessing:
 
-- **Scaffold** from the 60+ template catalog behind [templates.extension.dev](https://templates.extension.dev), or add a popup, sidebar, or content script to an existing project
+- **Scaffold** from the 50+ template catalog behind [templates.extension.dev](https://templates.extension.dev), or add a popup, sidebar, or content script to an existing project
 - **Run** the dev server with HMR in Chrome, Edge, Firefox, Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf, 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
@@ -102,7 +102,7 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | Tier | Tool | Description |
 | ---- | ---- | ----------- |
 | build | `extension_create` | Scaffold from a template |
-| build | `extension_templates` | Browse 60+ templates (`list`) and read one's source (`source`) |
+| build | `extension_templates` | Browse 50+ templates (`list`) and read one's source (`source`) |
 | build | `extension_add_feature` | Add sidebar/popup/content script |
 | build | `extension_build` | Build for production |
 | run | `extension_dev` | Dev server with HMR |
@@ -112,8 +112,8 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | see | `extension_manifest_validate` | Cross-browser manifest validation |
 | see | `extension_analyze` | Static analysis of the built extension on disk |
 | see | `extension_inspect` | Deep live inspection of a running extension (closed shadow roots, probes) |
-| see | `extension_dom_snapshot` | Shallow DOM snapshot of a chosen tab or extension surface, CDP-free |
-| see | `extension_list_extensions` | List loaded extensions (Chromium) |
+| see | `extension_dom_snapshot` | Shallow DOM snapshot of a chosen tab or extension surface over the agent bridge |
+| see | `extension_list_extensions` | List loaded extensions (Chromium and Firefox) |
 | see | `extension_logs` | Stream logs from every context |
 | see | `extension_doctor` | Diagnose the dev session leg by leg (ready contract, ports, token, executor, browser) |
 | see | `extension_theme_verify` | Verify a Chrome theme manifest against the colors Chrome actually paints |
@@ -134,7 +134,7 @@ Browser-launching tools (`dev`, `start`) shell out to the `extension` CLI, the p
 
 ## 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. Sharing needs auth (`extension_auth` or `EXTENSION_DEV_TOKEN`), the link expires, and `DELETE`ing the returned `revokeUrl` with the same token kills it early. Revocation is permanent and re-sharing mints a new link, so that `revokeUrl` is the only handle to the link you just made; every share is also appended to `.extension.dev/shared-previews.json` in the project (gitignored) so it survives losing the tool output. Without `share`, the tool returns a local-only deep link and uploads nothing.
+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.
 
 `extension_shares` is the other half of that: it lists every link the token has shared, live and dead, with the `previewUrl` and `revokeUrl` of each, and revokes one by `artifactId` or by pasting any of its URLs. Pass `projectPath` and it reconciles the platform's answer with the project's own record, so a link shared from another machine shows up as `remoteOnly` and a record with nothing behind it any more shows up under `localOnly`. It never rewrites the local file.
 
@@ -142,7 +142,7 @@ That is a different job from shipping. Use `share` for the build you are holding
 
 ## From preview to store
 
-The platform tools connect agents to [extension.dev](https://extension.dev): `extension_auth` runs extension.dev's own device flow (you approve the code at [extension.dev/device](https://extension.dev/device), and GitHub is federated server-side, so no GitHub token ever reaches your machine) and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build your project has already published into a shareable URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_submit` submits a built extension to the Chrome Web Store, Edge Add-ons, and Firefox AMO through extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI, it defaults to a dry run and store credentials are never tool arguments. The two verbs are not interchangeable: `extension_publish` pushes to the extension.dev platform, `extension_submit` sends the build into a store's review queue, which is irreversible. After a real submission, `extension_release_status` reads the recorded outcome, per-store credential health, and review state from the project's public registry, so agents and CI can answer "was it approved?" without a console visit. Access tokens live at most 7 days; CI pipelines re-mint them from the console's Access tokens page.
+The platform tools connect agents to [extension.dev](https://extension.dev): `extension_auth` runs extension.dev's own device flow (you approve the code at [extension.dev/device](https://extension.dev/device), and GitHub is federated server-side, so no GitHub token ever reaches your machine) and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build your project has already published into a shareable URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_submit` submits a built extension to the Chrome Web Store, Edge Add-ons, Firefox AMO, and the App Store for Safari through extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI, it defaults to a dry run and store credentials are never tool arguments. The two verbs are not interchangeable: `extension_publish` pushes to the extension.dev platform, `extension_submit` sends the build into a store's review queue, which is irreversible. After a real submission, `extension_release_status` reads the recorded outcome, per-store credential health, and review state from the project's public registry, so agents and CI can answer "was it approved?" without a console visit. Access tokens live at most 7 days; CI pipelines re-mint them from the console's Access tokens page.
 
 ## The extension.dev stack
 
@@ -155,8 +155,9 @@ All of it rides on [Extension.js](https://github.com/extension-js/extension.js),
 
 ## Community
 
-- Join the [Discord](https://discord.gg/v9h2RgeTSN) for help and feedback
-- Browse production-ready [examples](https://github.com/extension-js/examples)
+- Join the extension.dev [Discord](https://discord.gg/v9h2RgeTSN) for help and feedback
+- Browse production-ready templates at [templates.extension.dev](https://templates.extension.dev)
+- Follow the platform's public packages on [GitHub](https://github.com/extensiondev)
 - Report Extension.js framework issues on [GitHub](https://github.com/extension-js/extension.js/issues)
 
 ## License

package/bin/extension-mcp.js

@@ -7,17 +7,39 @@
 // ╚═╝     ╚═╝ ╚═════╝╚═╝
 // Apache License 2.0 (c) 2026 Cezar Augusto and the extension.dev collaborators
 
+import {createRequire} from 'node:module'
 import {startServer, runCli} from '../dist/module.js'
 
+const require = createRequire(import.meta.url)
+const {version} = require('../package.json')
+
+const usage = `@extension.dev/mcp ${version}
+
+Usage:
+  extension-mcp                 Start the MCP server on stdio
+  extension-mcp login [flags]   Device login at extension.dev
+  extension-mcp logout          Remove the stored credentials
+  extension-mcp whoami          Show the stored identity
+  extension-mcp release [...]   Headless release commands
+  extension-mcp --version       Print the version
+`
+
 const [, , cmd, ...rest] = process.argv
 
-if (cmd && ['login', 'logout', 'whoami', 'release'].includes(cmd)) {
+if (cmd === undefined) {
+  startServer()
+} else if (['login', 'logout', 'whoami', 'release'].includes(cmd)) {
   runCli(cmd, rest)
     .then((code) => process.exit(code))
     .catch((err) => {
       process.stderr.write(`${err?.message || String(err)}\n`)
       process.exit(1)
     })
+} else if (['--version', '-v'].includes(cmd)) {
+  process.stdout.write(`${version}\n`)
+} else if (['--help', '-h', 'help'].includes(cmd)) {
+  process.stdout.write(usage)
 } else {
-  startServer()
+  process.stderr.write(`Unknown command "${cmd}"\n\n${usage}`)
+  process.exit(1)
 }

package/claude/ARCHITECTURE.md

@@ -7,7 +7,7 @@ This document explains how the three Claude integration layers (the template, th
 ```
 examples repo (GitHub)
          │
-         ├── examples/<slug>/           60+ extension templates
+         ├── examples/<slug>/           50+ extension templates
          │     ├── src/manifest.json    Source of truth per template
          │     ├── template.meta.json   Curated metadata (tags, difficulty, useCases, AI fields)
          │     └── ...

package/claude/CLAUDE.md

@@ -11,7 +11,7 @@ You are working on a browser extension project built with the [extension.dev](ht
 
 ## Template catalog
 
-The extension.dev platform ships 60+ templates in the [examples](https://github.com/extension-js/examples) repo. The canonical registry is `templates-meta.json` published as a GitHub release asset and committed to the repo.
+The extension.dev platform ships 50+ templates in the [examples](https://github.com/extension-js/examples) repo. The canonical registry is `templates-meta.json` published as a GitHub release asset and committed to the repo.
 
 **How templates work:**
 
@@ -24,8 +24,8 @@ The extension.dev platform ships 60+ templates in the [examples](https://github.
 | Surface        | Vanilla      | React            | Vue           | Svelte           | AI               |
 | -------------- | ------------ | ---------------- | ------------- | ---------------- | ---------------- |
 | Content script | `content`    | `content-react`  | `content-vue` | `content-svelte` | n/a              |
-| Sidebar        | `sidebar`    | `sidebar-shadcn` | n/a           |, | `sidebar-claude` |
-| Action popup   | `action`     | n/a              |, | n/a              | `action-chatgpt` |
+| Sidebar        | `sidebar`    | `sidebar-shadcn` | n/a           | n/a              | `ai-claude`      |
+| Action popup   | `action`     | n/a              | n/a           | n/a              | `ai-chatgpt`     |
 | New tab        | `new`        | `new-react`      | `new-vue`     | `new-svelte`     | n/a              |
 | Full framework | `javascript` | `react`          | `vue`         | `svelte`         | n/a              |
 
@@ -34,7 +34,7 @@ The extension.dev platform ships 60+ templates in the [examples](https://github.
 1. Match the user's desired surface (sidebar, content script, popup, etc.)
 2. Match their framework preference
 3. Prefer `featured: true` templates for common use cases
-4. For AI-powered extensions, start from `sidebar-claude` or `action-chatgpt`
+4. For AI-powered extensions, start from `ai-claude` or `ai-chatgpt`
 
 **To browse all available templates:**
 
@@ -146,7 +146,7 @@ export default {
 
 ## Important gotchas
 
-1. **world: "MAIN" is Chromium-only.** If your content script uses `"world": "MAIN"`, prefix it with `chromium:` and provide a Firefox fallback or skip.
+1. **world: "MAIN" needs Firefox 128+.** Chromium and current Firefox both support it; only when targeting Firefox older than 128 prefix it with `chromium:` and provide a fallback.
 2. **Side panels vs sidebar actions.** Chromium uses `side_panel` + `sidePanel` permission. Firefox uses `sidebar_action` (no permission needed).
 3. **Service workers vs background scripts.** Chromium uses `service_worker` (single file). Firefox uses `scripts` (array).
 4. **Environment variables.** Use `EXTENSION_PUBLIC_*` prefix for variables accessible in extension code. `import.meta.env.EXTENSION_PUBLIC_BROWSER` gives the current browser.

package/claude/rules/cross-browser.md

@@ -49,7 +49,9 @@ if (isFirefoxLike) {
 
 ## Content scripts with world: "MAIN"
 
-`world: "MAIN"` only works on Chromium. Must be prefixed:
+`world: "MAIN"` works on Chromium and on Firefox 128 or newer. Only when
+supporting Firefox older than 128, prefix it so those versions fall back to
+the isolated world:
 
 ```json
 {
@@ -63,7 +65,7 @@ if (isFirefoxLike) {
 }
 ```
 
-Firefox will ignore the `chromium:world` field and run in the default isolated world.
+Older Firefox ignores the `chromium:world` field and runs in the default isolated world.
 
 ## API differences
 

package/claude/rules/mcp-tools.md

@@ -19,7 +19,7 @@ This file contains structured metadata for every template: surfaces, framework,
 **How `extension create` resolves templates today:**
 
 ```
-User: npx extension create my-ext --template=sidebar-claude
+User: npx extension create my-ext --template=ai-claude
                                            │
                                            ▼
 programs/create/steps/import-external-template.ts
@@ -64,7 +64,7 @@ These map directly to existing programmatic APIs and provide immediate value.
       "template": {
         "type": "string",
         "default": "typescript",
-        "description": "Template slug from the extension.dev template catalog (e.g. 'react', 'sidebar-claude', 'content-vue'). Use extension_templates to discover options."
+        "description": "Template slug from the extension.dev template catalog (e.g. 'react', 'ai-claude', 'content-vue'). Use extension_templates to discover options."
       },
       "install": {
         "type": "boolean",
@@ -345,7 +345,7 @@ These combine extension.dev knowledge with the examples repo to make Claude _sma
     "properties": {
       "slug": {
         "type": "string",
-        "description": "Template slug (e.g. 'sidebar-claude', 'content-react')"
+        "description": "Template slug (e.g. 'ai-claude', 'content-react')"
       },
       "files": {
         "type": "array",
@@ -892,7 +892,7 @@ const CURATED_ALLOWED_KEYS = [
 ];
 ```
 
-**Example for `sidebar-claude/template.meta.json`:**
+**Example for `ai-claude/template.meta.json`:**
 
 ```json
 {
@@ -942,7 +942,7 @@ These fields enable `extension_templates` to match user intent ("I want to build
 5. Extract browser detection into `extensionDetectBrowsers()` in `programs/extension`
 6. Extract wait mode into `extensionWait()` in `programs/extension`
 7. Add AI metadata fields to `CURATED_ALLOWED_KEYS` in `generate-templates-meta.mjs`
-8. Populate `template.meta.json` with AI fields for key templates (sidebar-claude, action-chatgpt, sidebar-transformers-js)
+8. Populate `template.meta.json` with AI fields for key templates (ai-claude, ai-chatgpt, sidebar-transformers-js)
 
 ### Phase 2: MCP Server package