chrome-extension-tester-mcp 2.0.0 → 2.2.0

package/README.md

@@ -6,6 +6,8 @@ An **MCP (Model Context Protocol) server** that lets Claude interactively test a
 
 ## Table of Contents
 
+- [Why](#why)
+- [Architecture](#architecture)
 - [Features](#features)
 - [Requirements](#requirements)
 - [Installation](#installation)
@@ -13,12 +15,31 @@ An **MCP (Model Context Protocol) server** that lets Claude interactively test a
 - [Setup with Claude Code (npx)](#setup-with-claude-code-npx)
 - [Available Tools](#available-tools)
 - [Testing Agent Prompt](#testing-agent-prompt)
+- [Example: testing an extension popup](#example-testing-an-extension-popup)
 - [Example Prompts](#example-prompts)
 - [Project Structure](#project-structure)
 - [Notes](#notes)
 
 ---
 
+## Why
+
+Testing a Chrome extension during development means manually clicking reload, opening the popup, checking storage in DevTools, watching the service worker console, and copy-pasting errors back to the agent on every iteration. This MCP server gives an AI coding agent direct access to all of that through tool calls, so the agent can iterate on its own. It exists because the manual loop made working with Claude Code on extensions too slow.
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+    A[AI Agent<br/>Claude / Cursor] -->|MCP protocol| B[This server<br/>14 tools]
+    B -->|Playwright| C[Chromium<br/>persistent context]
+    C -->|loads| D[Extension under test]
+    B -.->|reads / writes| E[(state.js<br/>browser, page, extensionId)]
+```
+
+---
+
 ## Features
 
 - Load and reload any unpacked Chrome extension
@@ -32,6 +53,7 @@ An **MCP (Model Context Protocol) server** that lets Claude interactively test a
 - Test context menu registration and handler invocation
 - Run assertions that return structured PASS / FAIL results
 - Take screenshots at any point during testing
+- Create and reuse test accounts on any website using disposable email (via Guerrilla Mail API)
 
 ---
 
@@ -139,6 +161,77 @@ Add to your project's `.mcp.json` or user-level MCP config:
 | `send_message_to_background` | Send `chrome.runtime.sendMessage` from the popup context and return the response |
 | `test_context_menu` | Check `contextMenus` API availability, simulate right-click, or invoke a menu item handler directly |
 | `simulate_tab_events` | Open, close, switch, list, or close all browser tabs |
+| `test_account_login` | Create or reuse a test account on any website using a disposable email; credentials are stored in `test-accounts.json` and reused across sessions |
+
+### `load_extension`
+Launch Chromium with an unpacked extension and capture its ID.
+**Inputs:** `extension_path` (string, required) — path to the unpacked extension folder.
+**Returns:** Text confirming the resolved path and the detected extension ID.
+
+### `interact_with_popup`
+Open the popup and click, type, or read its DOM.
+**Inputs:** `action` (string, required: `open` | `click` | `type` | `get_text` | `get_html`); `selector` (string); `value` (string, for `type`).
+**Returns:** Text describing the action result, or the requested text/HTML.
+
+### `open_options_page`
+Open the options page (or any extension page) and interact with it.
+**Inputs:** `page` (string, default `options.html`); `action` (string: `open` | `click` | `type` | `get_text` | `get_html`); `selector` (string); `value` (string).
+**Returns:** Text describing the action result, or the requested text/HTML.
+
+### `inspect_dom`
+Query a selector or evaluate JS in a page, optionally navigating first.
+**Inputs:** `url` (string); `selector` (string); `script` (string, overrides `selector`).
+**Returns:** Text with matched elements' outerHTML, or the JSON-serialized script result.
+
+### `get_service_worker_logs`
+Read buffered background service worker console logs.
+**Inputs:** `clear_after` (boolean, default `false`).
+**Returns:** Text listing captured log entries, or a "none captured yet" message.
+
+### `take_screenshot`
+Save a screenshot of the current page or popup.
+**Inputs:** `output_path` (string, default `./screenshot.png`); `full_page` (boolean, default `false`).
+**Returns:** Text with the saved file path.
+
+### `run_assertion`
+Assert an element exists/has text, or that a JS expression is truthy.
+**Inputs:** `description` (string, required); `selector` (string); `expected_text` (string); `script` (string, overrides `selector`).
+**Returns:** Text beginning with `PASS` or `FAIL`, followed by detail.
+
+### `extension_storage`
+Read from or write to `chrome.storage` (local / sync / session).
+**Inputs:** `action` (string, required: `get` | `set` | `remove` | `clear`); `area` (string, default `local`); `keys` (string[]); `data` (object, for `set`).
+**Returns:** Text with storage contents, or a confirmation of the write/removal.
+
+### `monitor_network`
+Capture and inspect network requests during navigation.
+**Inputs:** `action` (string, required: `navigate_and_capture` | `get_captured` | `clear`); `url` (string); `filter_pattern` (string); `include_types` (string[]).
+**Returns:** Text listing captured requests as `[method] [type] status url`.
+
+### `check_badge`
+Read or assert the action badge text and background color.
+**Inputs:** `action` (string, required: `get` | `assert_text` | `assert_color`); `tab_id` (number); `expected_text` (string); `expected_color` (number[] RGBA).
+**Returns:** Text with the badge value, or a `PASS` / `FAIL` assertion result.
+
+### `send_message_to_background`
+Send `chrome.runtime.sendMessage` from the popup and return the response.
+**Inputs:** `message` (object, required); `timeout_ms` (number, default `5000`).
+**Returns:** Text with the sent message and JSON response, or a failure message.
+
+### `test_context_menu`
+Check the `contextMenus` API, simulate a right-click, or trigger an item.
+**Inputs:** `action` (string, required: `check_api` | `right_click` | `trigger_item`); `url` (string); `selector` (string); `menu_item_id` (string); `page_url` (string).
+**Returns:** Text with API availability, dispatch confirmation, or trigger result.
+
+### `simulate_tab_events`
+Open, close, switch, list, or close all browser tabs.
+**Inputs:** `action` (string, required: `open` | `close` | `switch` | `list` | `close_all`); `url` (string); `tab_index` (number).
+**Returns:** Text describing the affected tab(s), or the list of open tabs.
+
+### `test_account_login`
+Create or reuse a test account on a site using a disposable email.
+**Inputs:** `action` (string, required: `auto` | `create` | `login`); `account_key` (string, required); `signup_url` / `login_url` (string); selector overrides (`email_selector`, `password_selector`, `submit_selector`, `pre_click_selector`); multi-step fields (`step2_url`, `step2_password_selector`, `step2_submit_selector`).
+**Returns:** Text reporting account creation/login status plus a screenshot path.
 
 ---
 
@@ -176,6 +269,52 @@ Claude will write the test plan, execute every test, and return a full report.
 
 ---
 
+## Example: testing an extension popup
+
+A typical loop the agent can run on its own:
+
+**1. Load the extension**
+
+```json
+{ "tool": "load_extension", "arguments": { "extension_path": "/tmp/my-extension" } }
+```
+
+```
+Extension loaded.
+Path: /tmp/my-extension
+Extension ID: ddnjmkpjnchafihagpljebmkdpejhaoj
+```
+
+**2. Open the popup and read its HTML**
+
+```json
+{ "tool": "interact_with_popup", "arguments": { "action": "open" } }
+```
+
+```html
+<body>
+  <h1>Tab Saver</h1>
+  <button id="save">Save open tabs</button>
+  <span id="count">0 saved</span>
+</body>
+```
+
+**3. Read local storage**
+
+```json
+{ "tool": "extension_storage", "arguments": { "action": "get", "area": "local" } }
+```
+
+```json
+storage.local contents:
+{
+  "savedTabs": [],
+  "enabled": true
+}
+```
+
+---
+
 ## Example Prompts
 
 ```
@@ -218,6 +357,14 @@ Open a tab to https://news.ycombinator.com, then another to https://github.com,
 Right-click on https://example.com and trigger the context menu item with id "my-action"
 ```
 
+```
+Create a test account on https://example.com/signup and save it as "my_test_account"
+```
+
+```
+Log in to https://example.com/login using the stored "my_test_account" credentials
+```
+
 ---
 
 ## Project Structure
@@ -244,7 +391,8 @@ chrome-extension-testing-mcp/
 │       ├── context-menu.js
 │       ├── badge.js
 │       ├── messaging.js
-│       └── tabs.js
+│       ├── tabs.js
+│       └── account-login.js
 ├── package.json
 └── README.md
 ```
@@ -259,6 +407,8 @@ chrome-extension-testing-mcp/
 - Call `load_extension` again at any time to get a fresh browser instance
 - Native Chrome context menus cannot be automated by Playwright — use `test_context_menu` with `trigger_item` to invoke handlers directly
 - Badge and storage tools communicate via the service worker, so the extension must have a background service worker (MV3)
+- `test_account_login` uses the [Guerrilla Mail API](https://www.guerrillamail.com/GuerrillaMailAPI.html) to generate disposable emails — no browser navigation required, no bot-blocking. Credentials are stored in `test-accounts.json` at the project root (add this to `.gitignore`)
+- Use `action: "auto"` for `test_account_login` to automatically reuse stored credentials or create a new account if none exist
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-extension-tester-mcp",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "MCP server for interactive Chrome extension testing via Playwright — load, interact, assert, inspect storage, network, badges, messaging, tabs, and more.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -7,11 +7,16 @@ import {
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "fs";
 import { TOOLS, HANDLERS } from "./tools/index.js";
 import { PROMPTS, PROMPT_HANDLERS } from "./prompts/index.js";
 
+// Read the version from package.json so it never drifts from the published value.
+const packageJsonUrl = new URL("../package.json", import.meta.url);
+const pkg = JSON.parse(readFileSync(packageJsonUrl, "utf-8"));
+
 const server = new Server(
-  { name: "chrome-extension-tester", version: "2.0.0" },
+  { name: "chrome-extension-tester", version: pkg.version },
   { capabilities: { tools: {}, prompts: {} } }
 );
 
@@ -64,4 +69,4 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("Chrome Extension Tester MCP server running (v2.0.0)...");
+console.error(`Chrome Extension Tester MCP server running (v${pkg.version})...`);

package/src/state.js

@@ -4,6 +4,10 @@ import path from "path";
 
 export const state = {
   browser: null,
+  // BrowserContext when connected via CDP (browser.contexts()[0]); null when using launchPersistentContext
+  context: null,
+  // "launched" = Playwright owns the browser process; "cdp" = attached to user's real browser
+  connectionMode: null,
   page: null,
   extensionId: null,
   swLogs: [],
@@ -23,28 +27,56 @@ export async function ensureBrowser(extensionPath) {
     ],
   });
 
-  await new Promise((r) => setTimeout(r, 1000));
-  const workers = state.browser.serviceWorkers();
-  if (workers.length > 0) {
-    const url = workers[0].url();
-    const match = url.match(/chrome-extension:\/\/([a-z]{32})\//);
-    if (match) state.extensionId = match[1];
+  // Prefer an already-registered service worker; otherwise wait for one to register.
+  const existingWorkers = state.browser.serviceWorkers();
+  let workerUrl = existingWorkers.length > 0 ? existingWorkers[0].url() : null;
+
+  if (!workerUrl) {
+    const worker = await state.browser.waitForEvent("serviceworker", { timeout: 5000 });
+    workerUrl = worker.url();
   }
 
+  const extensionIdMatch = workerUrl.match(/chrome-extension:\/\/([a-z]{32})\//);
+  if (extensionIdMatch) state.extensionId = extensionIdMatch[1];
+
+  state.connectionMode = "launched";
   state.page = await state.browser.newPage();
 }
 
 export async function ensurePage() {
   if (!state.page || state.page.isClosed()) {
-    if (!state.browser) throw new Error("Browser not started. Call load_extension first.");
+    const ctx = state.context || state.browser;
+    if (!ctx) throw new Error("No browser connected. Call load_extension or connect_browser first.");
+    state.page = await ctx.newPage();
+  }
+  return state.page;
+}
+
+/**
+ * Like ensurePage but launches a plain headed Chromium if no browser is running yet.
+ * Used by tools that don't require an extension (e.g. test_account_login).
+ */
+export async function ensurePageStandalone() {
+  if (!state.browser) {
+    state.browser = await chromium.launchPersistentContext("", {
+      headless: false,
+    });
+    state.connectionMode = "launched";
     state.page = await state.browser.newPage();
   }
+
+  if (!state.page || state.page.isClosed()) {
+    const ctx = state.context || state.browser;
+    state.page = await ctx.newPage();
+  }
+
   return state.page;
 }
 
 export async function getServiceWorker() {
-  if (!state.browser) throw new Error("Browser not started. Call load_extension first.");
-  const workers = state.browser.serviceWorkers();
+  const ctx = state.context || state.browser;
+  if (!ctx) throw new Error("No browser connected. Call load_extension or connect_browser first.");
+  const workers = ctx.serviceWorkers();
   if (!workers.length) throw new Error("No service worker found. Extension may not have a background service worker.");
   return workers[0];
 }