@extension.dev/mcp 9.0.0 → 10.1.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": "9.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.1.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": "9.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.1.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## 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
+different JSON shapes: `ok` appeared on 71 of them, `error` on 67, `hint` on 60,
+`message` on 49, `status` on 46, and five more keys carried the same meaning
+under different names. An agent could not tell success from failure without
+knowing which tool it had called.
+
+The frame is schema 1, the same one the Extension.js CLI emits under
+`--output json`:
+
+```json
+{
+  "schema": 1,
+  "ok": false,
+  "command": "extension_dev",
+  "status": "compile-failed",
+  "value": null,
+  "error": { "code": "E_FIRST_COMPILE", "message": "…" },
+  "hint": "…",
+  "warnings": []
+}
+```
+
+`command` names the tool. `status` is a kebab-case word from that tool's own
+vocabulary. `error.code` is stable and worth branching on; `error.message` is
+free copy and is not. The payload moved under `value`, and every advisory note
+that used to have its own key is now an entry in `warnings`.
+
+**Breaking.** Every payload key moved one level down. `build.success` is now
+`ok`, `doctor.healthy` is now `ok`, `manifest_validate.valid` is now
+`value.valid`, and `wait` gained the `ok` it never had. The ready contract's own
+`command` is carried as `value.sessionCommand`, because the envelope claims that
+key. `authorization_pending` became `authorization-pending`, with the old
+spelling echoed as `value.legacyStatus` for one minor.
+
+`extension_dev` and `extension_start` also stopped reading the dev server's
+prose to decide whether the first compile failed. They poll its `ready.json`
+contract instead, which splits a locked profile out of a dead browser and
+returns the compile errors as a list. The output scrape survives only as a
+fallback for a project whose own CLI predates the contract, is confined to one
+`@deprecated` module, and says so in `warnings` whenever it is used. The choice
+is a capability probe, never a version check: a project-local `extension` binary
+wins over this package's pin, so the version is not knowable in advance. The
+contract's own error stamps are read whatever the engine's age, so a locked
+profile is named as one the moment the engine records it.
+
 ## 9.0.0
 
 Every client pays for this server's tool list at the start of every session,

package/README.md

@@ -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 |
@@ -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
 

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",
@@ -154,7 +154,7 @@ These map directly to existing programmatic APIs and provide immediate value.
 ```json
 {
   "name": "extension_build",
-  "description": "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
+  "description": "Build a browser extension for production. The output lands in dist/<browser>/. Pass zip:true to also package a .zip for store submission. The build refuses a manifest with build-blocking errors unless you pass skipValidation:true, because such a manifest yields a broken bundle the bundler itself never flags.",
   "inputSchema": {
     "type": "object",
     "properties": {
@@ -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",
@@ -610,22 +610,34 @@ The `similarTemplates` field lists templates from the catalog with similar surfa
 }
 ```
 
-**Returns:** The `ready.json` contract:
+**Returns:** The schema-1 envelope, carrying the `ready.json` contract under `value`:
 
 ```json
 {
+  "schema": 1,
+  "ok": true,
+  "command": "extension_wait",
   "status": "ready",
-  "command": "dev",
-  "browser": "chrome",
-  "port": 8080,
-  "pid": 12345,
-  "distPath": "/path/to/dist/chrome",
-  "manifestPath": "/path/to/dist/chrome/manifest.json",
-  "compiledAt": "2026-04-14T10:30:00.000Z",
-  "startedAt": "2026-04-14T10:29:55.000Z"
+  "value": {
+    "compiled": true,
+    "browserAttached": true,
+    "sessionCommand": "dev",
+    "browser": "chrome",
+    "port": 8080,
+    "pid": 12345,
+    "distPath": "/path/to/dist/chrome",
+    "manifestPath": "/path/to/dist/chrome/manifest.json",
+    "compiledAt": "2026-04-14T10:30:00.000Z",
+    "startedAt": "2026-04-14T10:29:55.000Z"
+  },
+  "error": null,
+  "warnings": []
 }
 ```
 
+The envelope's `command` names the tool, so the ready contract's own `command`
+is carried as `value.sessionCommand`.
+
 **Why this matters for MCP:** When Claude starts a dev session via `extension_dev`, it needs to know when the extension is actually loaded and ready before calling `extension_inspect`. This tool provides that gate.
 
 ---
@@ -880,7 +892,7 @@ const CURATED_ALLOWED_KEYS = [
 ];
 ```
 
-**Example for `sidebar-claude/template.meta.json`:**
+**Example for `ai-claude/template.meta.json`:**
 
 ```json
 {
@@ -930,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