@extension.dev/mcp 3.17.0-canary.1779910200.ddcd9eb → 4.0.8

package/CHANGELOG.md

@@ -1,3 +1,39 @@
+# Changelog
+
+## 4.0.8
+
+Tracks the `extension` 4.0.8 suite (the versioning convention: this package's
+version follows the CLI suite release it pairs with). One tool was added since
+3.17.0, `extension_release_promote`, bringing the surface to 27 tools.
+
+- Bump `extension-create`, `extension-develop`, `extension-install` from
+  ^3.13.5 to ^4.0.8. All consumed APIs (`extensionCreate`, `extensionBuild`,
+  `extensionInstall`, `getManagedBrowsersCacheRoot`) and all CLI verbs the
+  tools shell out to (`dev`, `start`, `preview`, `logs`, `eval`, `storage`,
+  `reload`, `open`, `inspect`, `publish`, including `--allow-control`,
+  `--allow-eval` and `--no-browser`) are unchanged in 4.x; verified
+  end-to-end (create -> build -> dev ready contract -> manifest validate).
+- `package.json` version now matches the published line (was a stale 0.0.1)
+  and the server reports its version from `package.json` instead of a
+  hardcoded string (previously stuck at 3.13.5).
+- `browser-extension-manifest-fields` ^2.2.8 -> ^2.2.9.
+- vitest config: resolve the extension-* test aliases from the packages'
+  exports maps; 4.x dropped the CJS entry, so `require.resolve` on the bare
+  specifier no longer works.
+
+## 3.17.0
+
+First stable release on npm. The registry previously carried only canary
+builds (3.17.0-canary.*), so `npx @extension.dev/mcp` resolved a canary;
+this release graduates that line to stable and becomes `latest`.
+
+- 26 tools across scaffolding, build/dev/preview, live inspection (CDP +
+  agent bridge), act tools (eval/storage/reload/open), browser management,
+  and platform auth/publish.
+- Claude Code integration assets (CLAUDE.md, slash commands, rules) and the
+  @extension.dev/skill pairing.
+- MIT license shipped; repository moved to extensiondev/mcp.
+
 # @extension.dev/mcp — Changelog
 
 ## Unreleased — agent-bridge tools
@@ -34,3 +70,36 @@ New tools (22 total):
 Internal: `lib/act` (CLI shell-out helper), `lib/exec.runExtensionCli` (capture),
 `lib/cdp.getClosedShadowRoots`. Test infra aligned to the workspace vitest
 catalog.
+
+## Unreleased — login (auth tools)
+
+Adds the missing `login` flow so `extension_publish` no longer requires the user
+to mint and export `EXTENSION_DEV_TOKEN` by hand. Auth stays auth-AWARE: the
+token lives in a local credentials file, never in the MCP process state or logs.
+
+New tools (25 total):
+
+- **`extension_login`** — GitHub **device-code** flow (no local server; works
+  headless). Two-phase: call with `project` (`<workspace>/<project>`) to get a
+  code + URL, call again with the returned `deviceCode` to finish. On success it
+  writes a project-scoped token to the credentials file. Never returns the token.
+- **`extension_whoami`** — report the stored workspace/project and token expiry
+  without revealing the token.
+- **`extension_logout`** — delete the local credentials file.
+
+Token resolution for publish is now `EXTENSION_DEV_TOKEN` env **>** the
+credentials file (expired file tokens are ignored).
+
+Credentials file (versioned, `0600`): `$XDG_CONFIG_HOME/extension-dev/auth.json`
+(or `~/.config/...`; `%APPDATA%\extension-dev\auth.json` on Windows).
+
+Platform endpoints this depends on (in `apps/www.extension.dev`):
+
+- `GET /api/cli/login/config` — public GitHub OAuth client id + scope.
+- `POST /api/cli/login/exchange` — trades a GitHub **user** token for a
+  project-scoped access token after checking workspace membership. Modeled on
+  `/api/oidc/exchange`; tokens are recorded so they stay revocable.
+
+> ⚠️ **Ops:** the device flow requires **device flow enabled** on the GitHub
+> OAuth App behind `WWW_GITHUB_OAUTH_CLIENT_ID`. Until then, `extension_login`
+> can't complete and users fall back to a dashboard-minted `EXTENSION_DEV_TOKEN`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Extension Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,27 +1,46 @@
+[npm-version-image]: https://img.shields.io/npm/v/%40extension.dev%2Fmcp
+[npm-version-url]: https://www.npmjs.com/package/@extension.dev/mcp
+[action-image]: https://github.com/extensiondev/mcp/actions/workflows/ci.yml/badge.svg?branch=main
+[action-url]: https://github.com/extensiondev/mcp/actions
+
+[![Version][npm-version-image]][npm-version-url] [![workflow][action-image]][action-url]
+
 # @extension.dev/mcp
 
-MCP server for building, debugging, and publishing cross-browser extensions. Exposes 15 tools that let AI assistants scaffold, develop, build, inspect, and debug extensions using the [extension.dev](https://extension.dev) platform and template catalog.
+Give your AI agent hands for browser extension development. One command connects Claude Code, Claude Desktop, Cursor, or any MCP client to 26 tools that scaffold, run, inspect, debug, and publish cross-browser extensions:
+
+```bash
+claude mcp add extension-dev npx @extension.dev/mcp
+```
+
+Extensions fail silently: content scripts that never inject, panels that never open, permissions that return `undefined` with no error. These tools give agents eyes on the live browser (DOM probes, unified logs from every context, storage access, event replay) so they debug from evidence instead of guessing. Scaffolding draws on the 60+ template catalog of the [extension.dev](https://extension.dev) platform, built on [Extension.js](https://extension.js.org).
 
 ## What's in this package
 
 ```
 @extension.dev/mcp
-  src/              MCP server source (15 tools across 3 tiers)
+  src/              MCP server source (26 tools)
   claude/           Claude Code integration (CLAUDE.md, slash commands, rules)
   bin/              CLI entrypoint
 ```
 
-**MCP server** — programmatic bridge between AI assistants and the extension.dev platform. Imports from published npm packages:
+**MCP server**: programmatic bridge between AI assistants and the extension.dev platform. Imports from published npm packages:
 
-- `extension-create` — project scaffolding
-- `extension-develop` — build/dev/preview
-- `extension-install` — managed browser binaries
+- `extension-create`: project scaffolding
+- `extension-develop`: build/dev/preview
+- `extension-install`: managed browser binaries
 
-**Claude Code integration** — drop-in instructions, slash commands, and rules for Claude Code:
+**Claude Code integration**: drop-in instructions, slash commands, and rules for Claude Code:
 
-- `claude/CLAUDE.md` — project-level instructions for any extension project
-- `claude/commands/` — slash commands (`/extension`, `/extension-add`, `/extension-debug`, `/extension-publish`)
-- `claude/rules/` — rules for extension development, cross-browser compat, and MCP tools
+- `claude/CLAUDE.md`: project-level instructions for any extension project
+- `claude/commands/`: slash commands (`/extension`, `/extension-add`, `/extension-debug`, `/extension-publish`)
+- `claude/rules/`: rules for extension development, cross-browser compat, and MCP tools
+
+**Agent Skill**: the knowledge companion to this server lives in [`@extension.dev/skill`](https://npmjs.com/package/@extension.dev/skill): a portable [Agent Skills](https://agentskills.io)-format skill (SKILL.md + references) covering cross-browser rules, silent-failure gotchas, debugging playbooks, and store publishing. This server gives agents hands; the skill gives them judgment. Pair them:
+
+```bash
+mkdir -p .claude/skills && cp -R node_modules/@extension.dev/skill/skills/extension-dev .claude/skills/
+```
 
 Browser-launching tools (`dev`, `start`, `preview`) shell out to the `extension` CLI since they require the full browser launcher infrastructure.
 
@@ -73,11 +92,22 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | 2    | `extension_manifest_validate`   | native                          | Cross-browser manifest validation |
 | 2    | `extension_inspect`             | native                          | Build output analysis             |
 | 2    | `extension_source_inspect`      | CDP WebSocket                   | Live DOM inspection               |
+| 2    | `extension_dom_inspect`         | agent bridge                    | CDP-free DOM snapshot             |
+| 2    | `extension_list_extensions`     | CDP WebSocket                   | List loaded extensions (Chromium) |
+| 2    | `extension_logs`                | agent bridge                    | Stream logs from every context    |
 | 2    | `extension_wait`                | native                          | Poll ready.json contract          |
 | 2    | `extension_add_feature`         | native                          | Add sidebar/popup/content script  |
+| act  | `extension_eval`                | agent bridge                    | Eval in a context (`--allow-eval`) |
+| act  | `extension_storage`             | agent bridge                    | Read/write `chrome.storage`       |
+| act  | `extension_reload`              | agent bridge                    | Reload extension or tab           |
+| act  | `extension_open`                | agent bridge                    | Open surface / trigger `action`,`command` |
 | 3    | `extension_install_browser`     | `extensionInstall()`            | Install managed browser           |
 | 3    | `extension_list_browsers`       | `getManagedBrowsersCacheRoot()` | List managed browsers             |
 | 3    | `extension_detect_browsers`     | native                          | System browser detection          |
+| auth | `extension_login`               | platform                        | GitHub device-code → stored token |
+| auth | `extension_whoami`              | native                          | Show stored login (no token)      |
+| auth | `extension_logout`              | native                          | Remove stored credentials         |
+| auth | `extension_publish`             | platform                        | Publish to extension.dev (token)  |
 
 ## Development
 
@@ -96,6 +126,18 @@ NPM_TOKEN=<token> pnpm publish
 
 Uses `prepublishOnly` to run tests and compile before publishing.
 
+## The extension.dev open source stack
+
+| Package | Use it to |
+| --- | --- |
+| [`@extension.dev/skill`](https://github.com/extensiondev/skill) | Teach agents the cross-browser rules and silent-failure gotchas |
+| [`@extension.dev/deploy`](https://github.com/extensiondev/deploy) | Ship to Chrome, Firefox, and Edge stores from CI |
+| [`@extension.dev/artifact-integrity`](https://github.com/extensiondev/artifact-integrity) | Gate releases on artifact verification |
+| [`@extension.dev/compiler`](https://github.com/extensiondev/compiler) | Build extensions in the browser with esbuild-wasm |
+| [`@extension.dev/core`](https://github.com/extensiondev/core) | Authenticate and publish to the extension.dev platform |
+
+All of it rides on [Extension.js](https://github.com/extension-js/extension.js), the open-source cross-browser extension framework.
+
 ## License
 
 MIT

package/bin/extension-mcp.js

@@ -1,3 +1,16 @@
 #!/usr/bin/env node
-import {startServer} from '../dist/module.js'
-startServer()
+import {startServer, runCli} from '../dist/module.js'
+
+const [, , cmd, ...rest] = process.argv
+
+if (cmd && ['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 {
+  // No subcommand: run as the MCP stdio server (the default and primary mode).
+  startServer()
+}

package/claude/CLAUDE.md

@@ -242,6 +242,14 @@ npm run dev -- --logs info --log-url "example.com"
 - 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)
 
+### Triggering events without clicking (requires `--allow-control`)
+
+- `extension open action` — fire the toolbar action (opens its popup, or replays `chrome.action.onClicked`).
+- `extension open command --name <cmd>` — replay a `chrome.commands.onCommand` keyboard shortcut.
+- `extension_list_extensions` (MCP tool; no CLI verb) — list extensions with a live context in the browser (Chromium, read-only).
+
+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.
+
 ## Contributing templates to the examples repo
 
 If you create a new extension pattern worth sharing:

package/claude/commands/extension-debug.md

@@ -24,7 +24,17 @@ Debug the currently running extension dev session. The user said: $ARGUMENTS
    - Read `dist/extension-js/chrome/ready.json` to get the CDP port
    - Report the port and suggest Chrome DevTools inspection
 
-3. **Diagnose common issues**
+3. **Exercise event handlers (when the bug is in an action / command / shortcut)**
+   If the session was started with `--allow-control`, fire the events a user would, without clicking:
+   - `extension_open` with `surface: "action"` — triggers the toolbar action (opens its popup, or replays `chrome.action.onClicked`).
+   - `extension_open` with `surface: "command"` and `name: "<cmd>"` — replays a `chrome.commands.onCommand` keyboard shortcut.
+   - Then re-inspect or read `extension_logs` to see what the handler did.
+
+   **Caveat:** replay carries no user gesture, so `activeTab` is NOT granted. If the handler depends on `activeTab` (e.g. `chrome.scripting.executeScript` on the active tab, `captureVisibleTab`), the result includes `gesture: false` and a `warning`, and behavior differs from a real click. For a genuine-gesture click (activeTab granted), use chrome-devtools-mcp's `trigger_extension_action` (Chromium only) alongside this server.
+
+   To see what else is loaded in the browser (Chromium): `extension_list_extensions`.
+
+4. **Diagnose common issues**
    Based on what you find, check for:
    - **"It didn't load"**: Check extension root count. If 0, content scripts may not be injecting. Check manifest `content_scripts` matches patterns and the target URL.
    - **Console errors**: Report top errors. Common ones:
@@ -34,7 +44,7 @@ Debug the currently running extension dev session. The user said: $ARGUMENTS
    - **Wrong page**: Check if the content script `matches` pattern in manifest covers the target URL
    - **Shadow DOM empty**: Extension root exists but shadow content is empty — likely a CSS or framework mounting issue
 
-4. **Suggest fixes** based on the diagnosis
+5. **Suggest fixes** based on the diagnosis
 
 ## Examples
 

package/claude/rules/mcp-tools.md

@@ -719,8 +719,15 @@ The `similarTemplates` field lists templates from the catalog with similar surfa
 | `extension_manifest_validate`   | `programs/develop`   | `plugin-web-extension`                    | `templates-meta.json` for similar templates | Extract validation logic                   |
 | `extension_inspect`             | `programs/develop`   | `--source` flag logic                     | —                                           | Extract into callable API                  |
 | `extension_source_inspect`      | `programs/extension` | CDP client / RDP transport                | Live browser via debugging protocol         | Wire to running session                    |
+| `extension_list_extensions`     | MCP `lib/cdp`        | `Extensions.getExtensionInfo` (read-only) | Live browser via CDP (Chromium)             | MCP tool (no CLI verb)                      |
 | `extension_wait`                | `programs/extension` | `dev-wait.ts`                             | `ready.json` contract file                  | Thin wrapper (exists in CLI)               |
 | `extension_add_feature`         | New                  | `extension_get_template_source`           | examples repo patterns                      | Codegen from examples                      |
+| **Agent bridge — act / triggers** |                    |                                           |                                             |                                            |
+| `extension_eval`                | `programs/extension` | bridge control channel                    | Live extension context                      | Wraps `extension eval` (`--allow-eval`)     |
+| `extension_storage`             | `programs/extension` | bridge control channel                    | `chrome.storage`                            | Wraps `extension storage`                   |
+| `extension_reload`              | `programs/extension` | bridge control channel                    | Live extension                              | Wraps `extension reload`                    |
+| `extension_open`                | `programs/extension` | bridge control channel                    | Surfaces + `action`/`command` replay        | Wraps `extension open`                      |
+| `extension_logs`                | `programs/extension` | bridge log/control channel                | `logs.ndjson` + live channel                | Wraps `extension logs`                      |
 | **Tier 3 — Browser management** |                      |                                           |                                             |                                            |
 | `extension_install_browser`     | `programs/install`   | `extensionInstall()`                      | —                                           | Thin wrapper only                          |
 | `extension_list_browsers`       | `programs/install`   | `getManagedBrowsersCacheRoot()`           | —                                           | Thin wrapper only                          |

package/dist/module.d.ts

@@ -1 +1 @@
-export { startServer } from "./src/index";
+export { startServer, runCli } from "./src/index";