@extension.dev/mcp 3.17.0-canary.1779905934.1151df3

package/claude/commands/extension-add.md

@@ -0,0 +1,63 @@
+---
+description: Add a feature surface (sidebar, popup, content script, etc.) to an existing extension
+argument-hint: "<feature> [framework]"
+---
+
+Add a new feature surface to the current extension project. The user said: $ARGUMENTS
+
+## Parse arguments
+
+- First argument: feature type — one of: `sidebar`, `popup`, `content-script`, `background`, `newtab`, `options`, `devtools`
+- Second argument (optional): framework — one of: `react`, `vue`, `svelte`, `preact`, `vanilla`. Default: detect from existing project, fall back to `react`
+
+## Steps
+
+1. **Validate the project**
+   - Check that `src/manifest.json` exists
+   - Read it to understand what's already configured
+   - Detect the framework from existing dependencies in `package.json`
+
+2. **Get the reference pattern**
+   If MCP tool `extension_add_feature` is available, use it — it returns the exact manifest additions, files to create, and reference template.
+
+   If MCP tool `extension_get_template_source` is available, read the reference template source to get real implementation patterns.
+
+3. **Update manifest.json**
+   Add the required fields to `src/manifest.json`. Use the extension.dev cross-browser format:
+
+   | Feature        | Chromium                                                                                                  | Firefox                                                             |
+   | -------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+   | Sidebar        | `"chromium:side_panel": {"default_path": "sidebar/index.html"}` + `"chromium:permissions": ["sidePanel"]` | `"firefox:sidebar_action": {"default_panel": "sidebar/index.html"}` |
+   | Popup          | `"chromium:action": {"default_popup": "action/index.html"}`                                               | `"firefox:browser_action": {"default_popup": "action/index.html"}`  |
+   | Content script | `"content_scripts": [{"matches": ["<all_urls>"], "js": ["content/scripts.ts"]}]`                          | Same                                                                |
+   | Background     | `"background": {"chromium:service_worker": "background.ts", "firefox:scripts": ["background.ts"]}`        | Same (prefixed)                                                     |
+   | New tab        | `"chrome_url_overrides": {"newtab": "newtab/index.html"}`                                                 | Same                                                                |
+   | Options        | `"options_ui": {"page": "options/index.html", "open_in_tab": true}`                                       | Same                                                                |
+   | DevTools       | `"devtools_page": "devtools/index.html"`                                                                  | Same                                                                |
+
+4. **Create the files**
+   For HTML-based features (sidebar, popup, newtab, options, devtools):
+   - `src/<feature>/index.html` — HTML entry with script tag
+   - `src/<feature>/scripts.tsx` — Framework mount point (or `.ts` for vanilla)
+   - `src/<feature>/styles.css` — Stylesheet
+   - `src/<feature>/<Feature>App.tsx` — Main component (non-vanilla only)
+
+   For content scripts:
+   - `src/content/scripts.ts` — Entry point
+   - `src/content/styles.css` — Injected styles
+
+   For background:
+   - `src/background.ts` — Service worker / background script
+
+5. **Handle sidebar specifically**
+   If adding a sidebar, also create/update `src/background.ts`:
+
+   ```typescript
+   // Chromium: open sidebar on action click
+   chrome.sidePanel?.setPanelBehavior?.({ openPanelOnActionClick: true });
+
+   // Firefox: sidebar_action handles this automatically
+   ```
+
+6. **Report what was done**
+   List all files created and manifest changes made. Suggest `npm run dev` to test.

package/claude/commands/extension-debug.md

@@ -0,0 +1,43 @@
+---
+description: Debug a running extension — inspect DOM, console, content script injection
+argument-hint: "[url] [selectors...]"
+---
+
+Debug the currently running extension dev session. The user said: $ARGUMENTS
+
+## Steps
+
+1. **Check for a running dev session**
+   - Look for `dist/extension-js/chrome/ready.json` in the project root
+   - If MCP tool `extension_wait` is available, use it with a short timeout (3s) to check
+   - If no session: tell the user to start one with `/extension dev` or `npm run dev`
+
+2. **Inspect the live state**
+   If MCP tool `extension_source_inspect` is available:
+   - Pass `include: ["html", "summary", "meta", "console", "extension_roots"]`
+   - If the user provided a URL in `$ARGUMENTS`, pass it as `url`
+   - If the user provided CSS selectors (strings starting with `#`, `.`, or `[`), pass them as `probe`
+   - Report the results in a structured way
+
+   If MCP is not available:
+   - Suggest the CLI equivalent: `npx extension dev --source <url> --source-format json --source-console`
+   - Read `dist/extension-js/chrome/ready.json` to get the CDP port
+   - Report the port and suggest Chrome DevTools inspection
+
+3. **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:
+     - `Uncaught TypeError` — likely a missing import or wrong module format
+     - `Content Security Policy` — extension CSP blocking inline scripts
+     - `chrome.runtime.lastError` — API permission missing
+   - **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
+
+## Examples
+
+- `/extension-debug` — inspect the default page target
+- `/extension-debug https://example.com` — inspect a specific URL
+- `/extension-debug https://example.com #my-root .sidebar` — inspect URL and probe selectors

package/claude/commands/extension-publish.md

@@ -0,0 +1,62 @@
+---
+description: Prepare an extension for store submission (Chrome Web Store, Firefox Add-ons)
+argument-hint: "[chrome|firefox|both]"
+---
+
+Prepare the current extension for store submission. The user said: $ARGUMENTS
+
+## Parse arguments
+
+Default to `both` (Chrome + Firefox). If the user specifies `chrome` or `firefox`, target only that store.
+
+## Steps
+
+1. **Validate the manifest**
+   If MCP tool `extension_manifest_validate` is available, use it with the target browsers.
+   Otherwise, read `src/manifest.json` and check:
+   - Has `name`, `version`, `description`
+   - Has appropriate `manifest_version` for each target
+   - Permissions are minimal (no unnecessary permissions)
+   - Has icons (at least 16x16, 48x48, 128x128)
+
+2. **Build for each target browser**
+
+   ```bash
+   npx extension build --browser=chrome --zip
+   npx extension build --browser=firefox --zip
+   ```
+
+3. **Inspect the builds**
+   If MCP tool `extension_inspect` is available, use it for each browser build.
+   Check:
+   - Total size under 10MB (store limit)
+   - No source maps in production build
+   - Has manifest.json in dist
+   - Has icons
+
+4. **Report store readiness**
+
+   ### Chrome Web Store
+   - Zip location: `dist/chrome/<name>.zip`
+   - Submit at: https://chrome.google.com/webstore/devconsole
+   - Checklist:
+     - [ ] manifest_version: 3
+     - [ ] Icons: 128x128 PNG
+     - [ ] Description under 132 characters (for listing)
+     - [ ] Screenshots: 1280x800 or 640x400
+     - [ ] Privacy policy URL (if using sensitive permissions)
+
+   ### Firefox Add-ons (AMO)
+   - Zip location: `dist/firefox/<name>.zip`
+   - Submit at: https://addons.mozilla.org/developers/
+   - Checklist:
+     - [ ] manifest_version: 2 (recommended for broadest compat) or 3
+     - [ ] No Chrome-only APIs without polyfill
+     - [ ] Source code zip if using a bundler: `npx extension build --browser=firefox --zip --zip-source`
+     - [ ] AMO requires source code review for minified/bundled code
+
+5. **Flag issues** that would cause store rejection:
+   - `<all_urls>` host permission without justification
+   - `activeTab` + `scripting` without clear use case
+   - Remote code loading (eval, Function constructor, remote scripts)
+   - Excessive permissions for the extension's functionality

package/claude/commands/extension.md

@@ -0,0 +1,76 @@
+---
+description: Create, develop, or build a browser extension with extension.dev
+argument-hint: "<action> [options]"
+---
+
+You are helping build a browser extension with the extension.dev platform. The user said: $ARGUMENTS
+
+## Actions
+
+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_list_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}'`
+3. Run `npx extension@latest create <name> --template=<best-match>`
+4. Report what was created and suggest `npm run dev`
+
+### "dev" or "run" — Start development
+
+1. Run `npm run dev` (or `npx extension dev`) in the project root
+2. Tell the user the browser will open with their extension loaded
+3. Mention HMR is active — changes will hot-reload
+
+### "build" — Build for production
+
+1. Run `npm run build` (or `npx extension build`)
+2. After success, report the output in `dist/chrome/`
+3. If the user mentions "firefox" or "both", also build with `--browser=firefox`
+4. If they mention "zip" or "store", add `--zip`
+
+### "add <feature>" — Add a feature surface
+
+1. If MCP tool `extension_add_feature` is available, use it to get the manifest additions and file list
+2. Otherwise, determine what's needed from the feature type:
+   - **sidebar**: `chromium:side_panel` + `firefox:sidebar_action` + `sidePanel` permission + background handler
+   - **popup**: `chromium:action` + `firefox:browser_action`
+   - **content-script**: `content_scripts` array in manifest
+   - **newtab**: `chrome_url_overrides.newtab`
+   - **background**: `background.service_worker` (Chromium) + `background.scripts` (Firefox)
+3. Create the files and update `src/manifest.json`
+
+### "debug" or "inspect" — Debug a running extension
+
+1. If MCP tool `extension_source_inspect` is available, use it with `include: ["html", "console", "extension_roots"]`
+2. If there's a URL mentioned, pass it as the target
+3. If there are CSS selectors mentioned, pass them as `probe`
+4. Report: injected HTML, console errors, extension root state
+
+### "validate" — Check manifest for issues
+
+1. If MCP tool `extension_manifest_validate` is available, use it
+2. Otherwise, read `src/manifest.json` and check:
+   - Required fields: `name`, `manifest_version`
+   - Cross-browser: `chromium:` and `firefox:` prefixed fields match
+   - Permissions: `sidePanel` present if `side_panel` is declared
+   - Background: `service_worker` (Chromium) and `scripts` (Firefox) both present
+
+### "template <query>" — Search for a template
+
+1. If MCP tool `extension_list_templates` is available, use it with the query
+2. Otherwise, search the catalog JSON
+3. Show matching templates with slug, description, framework, and surfaces
+
+### No action / general question
+
+If the user's input doesn't match an action, treat it as a description of what they want to build. Recommend the best template and offer to create it.
+
+## Cross-browser rules
+
+Always use the extension.dev cross-browser manifest format:
+
+- `chromium:manifest_version: 3`, `firefox:manifest_version: 2`
+- `chromium:action` vs `firefox:browser_action`
+- `chromium:side_panel` vs `firefox:sidebar_action`
+- `background.chromium:service_worker` vs `background.firefox:scripts`

package/claude/examples/add-sidebar.md

@@ -0,0 +1,56 @@
+# Example: Add a sidebar panel to an existing extension
+
+## Prompt
+
+> Add a sidebar panel to my extension that shows a settings page.
+
+## How Claude should approach this
+
+1. **Update manifest.json** — add side panel config for both browsers:
+
+   ```json
+   {
+     "chromium:side_panel": {
+       "default_path": "sidebar/index.html"
+     },
+     "firefox:sidebar_action": {
+       "default_panel": "sidebar/index.html"
+     },
+     "chromium:permissions": ["sidePanel"]
+   }
+   ```
+
+2. **Add action button** to trigger the sidebar:
+
+   ```json
+   {
+     "chromium:action": { "default_title": "Open Settings" },
+     "firefox:browser_action": { "default_title": "Open Settings" }
+   }
+   ```
+
+3. **Create background.ts** to handle the action click:
+
+   ```typescript
+   const isFirefoxLike =
+     import.meta.env.EXTENSION_PUBLIC_BROWSER === "firefox" ||
+     import.meta.env.EXTENSION_PUBLIC_BROWSER === "gecko-based";
+
+   if (isFirefoxLike) {
+     browser.browserAction.onClicked.addListener(() => {
+       browser.sidebarAction.open();
+     });
+   } else {
+     chrome.action.onClicked.addListener(() => {
+       chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
+     });
+   }
+   ```
+
+4. **Create the sidebar UI** — `src/sidebar/index.html`, `src/sidebar/scripts.tsx`, `src/sidebar/styles.css`
+
+5. **Test both browsers:**
+   ```bash
+   npm run dev -- --browser=chrome
+   npm run dev -- --browser=firefox
+   ```

package/claude/examples/create-extension.md

@@ -0,0 +1,49 @@
+# Example: Create a new extension from scratch
+
+## Prompt
+
+> Create a Chrome extension that adds a floating button to every page. When clicked, it summarizes the page content and shows the summary in a popup overlay.
+
+## How Claude should approach this
+
+1. **Scaffold with extension.js:**
+
+   ```bash
+   npx extension@latest create page-summarizer --template=react
+   cd page-summarizer
+   ```
+
+2. **Define the manifest** — content script for the floating button, background script for orchestration:
+
+   ```json
+   {
+     "chromium:manifest_version": 3,
+     "firefox:manifest_version": 2,
+     "name": "Page Summarizer",
+     "content_scripts": [
+       {
+         "matches": ["<all_urls>"],
+         "js": ["content/scripts.tsx"],
+         "css": ["content/styles.css"]
+       }
+     ],
+     "background": {
+       "chromium:service_worker": "background.ts",
+       "firefox:scripts": ["background.ts"]
+     },
+     "permissions": ["activeTab"]
+   }
+   ```
+
+3. **Build the content script** — inject a floating button, handle click to extract `document.body.innerText`, send to background for processing.
+
+4. **Test it:**
+   ```bash
+   npm run dev
+   ```
+
+## Key decisions Claude should make
+
+- Content script for page injection (not popup, since it needs page context)
+- Background script for any API calls (content scripts have CORS restrictions)
+- Use `chrome.runtime.sendMessage` for content <-> background communication

package/claude/rules/cross-browser.md

@@ -0,0 +1,84 @@
+# Cross-Browser Rules for Claude
+
+## Manifest field mapping
+
+| Feature               | Chromium                              | Firefox                       |
+| --------------------- | ------------------------------------- | ----------------------------- |
+| Manifest version      | `chromium:manifest_version: 3`        | `firefox:manifest_version: 2` |
+| Toolbar button        | `chromium:action`                     | `firefox:browser_action`      |
+| Side panel            | `chromium:side_panel`                 | `firefox:sidebar_action`      |
+| Background            | `chromium:service_worker` (string)    | `firefox:scripts` (array)     |
+| Side panel permission | `chromium:permissions: ["sidePanel"]` | Not needed                    |
+
+## Side panel / Sidebar
+
+Chromium:
+
+```json
+{
+  "chromium:side_panel": {
+    "default_path": "sidebar/index.html"
+  },
+  "chromium:permissions": ["sidePanel"]
+}
+```
+
+Firefox:
+
+```json
+{
+  "firefox:sidebar_action": {
+    "default_panel": "sidebar/index.html"
+  }
+}
+```
+
+Background script to open:
+
+```typescript
+if (isFirefoxLike) {
+  browser.browserAction.onClicked.addListener(() => {
+    browser.sidebarAction.open();
+  });
+} else {
+  chrome.action.onClicked.addListener(() => {
+    chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
+  });
+}
+```
+
+## Content scripts with world: "MAIN"
+
+`world: "MAIN"` only works on Chromium. Must be prefixed:
+
+```json
+{
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["content/scripts.ts"],
+      "chromium:world": "MAIN"
+    }
+  ]
+}
+```
+
+Firefox will ignore the `chromium:world` field and run in the default isolated world.
+
+## 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
+
+## Testing across browsers
+
+```bash
+# Dev mode
+npm run dev -- --browser=chrome
+npm run dev -- --browser=firefox
+npm run dev -- --browser=edge
+
+# Build for multiple browsers
+npm run build -- --browser=chrome,firefox
+```

package/claude/rules/extension-dev.md

@@ -0,0 +1,83 @@
+# extension.dev Development Rules for Claude
+
+## File creation order
+
+When Claude creates a new extension, follow this order:
+
+1. `manifest.json` — always first, defines the extension surface
+2. Background script (if needed) — handles browser events
+3. UI entry points — HTML files referenced by manifest
+4. UI scripts — React/Vue/Svelte components mounted into HTML
+5. Styles — CSS/Tailwind files imported by scripts
+6. `package.json` — dependencies based on what was used above
+7. Config files — tsconfig.json, postcss.config.js, extension.config.js only if needed
+
+## manifest.json rules
+
+- Always use the `$schema` field for validation: `"$schema": "https://json.schemastore.org/chrome-manifest.json"`
+- Use `chromium:manifest_version: 3` and `firefox:manifest_version: 2` for cross-browser
+- Icon paths are relative to `src/` (where manifest.json lives)
+- Entry point paths (HTML, scripts) are relative to `src/`
+- Always include icons at sizes: 16, 32, 48, 64, 128
+
+## Script entry points
+
+- Background: referenced in `manifest.json` under `background`
+- Content scripts: referenced in `manifest.json` under `content_scripts`
+- UI pages (popup, sidebar, options, newtab): referenced as HTML files in manifest, include a `<script src="./scripts.tsx">` tag
+
+## HTML page pattern
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Page Title</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this extension.</noscript>
+    <div id="root"></div>
+  </body>
+  <script src="./scripts.tsx"></script>
+</html>
+```
+
+## React mounting pattern
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./styles.css";
+
+const root = ReactDOM.createRoot(document.getElementById("root")!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+```
+
+## Browser detection
+
+```typescript
+const isFirefoxLike =
+  import.meta.env.EXTENSION_PUBLIC_BROWSER === "firefox" ||
+  import.meta.env.EXTENSION_PUBLIC_BROWSER === "gecko-based";
+```
+
+## Storage API
+
+Use `chrome.storage.local` for persistent data. It works cross-browser when the polyfill is active (default).
+
+## Permissions
+
+Only request permissions the extension actually needs. Common ones:
+
+- `sidePanel` — Chromium only, for side panel UI
+- `storage` — for chrome.storage API
+- `activeTab` — for accessing the current tab
+- `tabs` — for tab management
+- `scripting` — for programmatic script injection