chrome-extension-tester-mcp 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bhuvanrj
+
+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

@@ -0,0 +1,267 @@
+# Chrome Extension Tester — MCP Server
+
+An **MCP (Model Context Protocol) server** that lets Claude interactively test any unpacked Chrome extension using Playwright. Load your extension, interact with its popup and options page, inspect storage, monitor network requests, check badges, test messaging, and more — all through natural language.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Setup with Claude Desktop](#setup-with-claude-desktop)
+- [Setup with Claude Code (npx)](#setup-with-claude-code-npx)
+- [Available Tools](#available-tools)
+- [Testing Agent Prompt](#testing-agent-prompt)
+- [Example Prompts](#example-prompts)
+- [Project Structure](#project-structure)
+- [Notes](#notes)
+
+---
+
+## Features
+
+- Load and reload any unpacked Chrome extension
+- Interact with popup and options pages (click, type, read content)
+- Inspect and manipulate `chrome.storage` (local / sync / session)
+- Read background service worker console logs
+- Monitor and inspect network requests
+- Check and assert badge text and color
+- Send messages to the background script and validate responses
+- Simulate tab open / close / switch events
+- Test context menu registration and handler invocation
+- Run assertions that return structured PASS / FAIL results
+- Take screenshots at any point during testing
+
+---
+
+## Requirements
+
+- **Node.js** 18 or higher
+- **Claude Desktop** or **Claude Code** with MCP support
+- A Chrome extension with a `manifest.json` (Manifest V2 or V3)
+
+---
+
+## Installation
+
+### Option A — npx (no install needed)
+
+```bash
+npx chrome-extension-tester-mcp
+```
+
+### Option B — install globally
+
+```bash
+npm install -g chrome-extension-tester-mcp
+```
+
+### Option C — clone and run locally
+
+```bash
+git clone https://github.com/BHUVAN-RJ/chrome-extension-testing-mcp.git
+cd chrome-extension-testing-mcp
+npm install
+npx playwright install chromium
+```
+
+---
+
+## Setup with Claude Desktop
+
+Add the following to your Claude Desktop MCP config file:
+
+**macOS / Linux** — `~/.config/claude/claude_desktop_config.json`
+**Windows** — `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Using npx (recommended)
+
+```json
+{
+  "mcpServers": {
+    "chrome-extension-tester": {
+      "command": "npx",
+      "args": ["chrome-extension-tester-mcp"]
+    }
+  }
+}
+```
+
+### Using a local clone
+
+```json
+{
+  "mcpServers": {
+    "chrome-extension-tester": {
+      "command": "node",
+      "args": ["/absolute/path/to/chrome-extension-testing-mcp/src/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the config.
+
+---
+
+## Setup with Claude Code (npx)
+
+Add to your project's `.mcp.json` or user-level MCP config:
+
+```json
+{
+  "mcpServers": {
+    "chrome-extension-tester": {
+      "command": "npx",
+      "args": ["chrome-extension-tester-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Available Tools
+
+| Tool | What it does |
+|------|-------------|
+| `load_extension` | Launch Chromium with an unpacked extension; captures the extension ID automatically |
+| `interact_with_popup` | Open the popup, then click elements, type text, or read content |
+| `open_options_page` | Open the extension's options / settings page and interact with it |
+| `inspect_dom` | Navigate to a URL, query a DOM selector, or evaluate arbitrary JavaScript |
+| `get_service_worker_logs` | Read buffered background service worker console logs; optionally clear them |
+| `take_screenshot` | Save a screenshot of the current page or popup |
+| `run_assertion` | Assert that an element exists, has specific text, or a JS expression is truthy — returns PASS or FAIL |
+| `extension_storage` | Get, set, remove, or clear keys in `chrome.storage.local`, `.sync`, or `.session` |
+| `monitor_network` | Capture network requests during navigation; retrieve or clear the captured list |
+| `check_badge` | Read or assert the extension action badge text and background color |
+| `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 |
+
+---
+
+## Testing Agent Prompt
+
+The server includes a built-in MCP prompt called **`extension-tester-agent`** — a fully automated testing agent that validates all implemented changes and returns a structured report.
+
+### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `extension_path` | yes | Absolute path to the unpacked extension folder |
+| `extension_description` | yes | What the extension does — features, UI, storage, background behaviour |
+| `changes` | yes | Everything implemented or changed in this session |
+
+### What it does
+
+1. **Understands** the extension and derives a set of tests from the changes list
+2. **Writes a test plan** — every change maps to at least one test and the right MCP tool
+3. **Executes every test** — never skips, takes screenshots on failure
+4. **Reports** a structured PASS / FAIL table with details on any failures
+
+### How to invoke
+
+After implementing changes, tell Claude:
+
+```
+Use the extension-tester-agent prompt with:
+- extension_path: /path/to/my-extension
+- extension_description: "A tab manager that saves sessions to chrome.storage.local and restores them via a popup"
+- changes: "Added save button; save button writes open tabs to storage.local; badge shows count of saved tabs"
+```
+
+Claude will write the test plan, execute every test, and return a full report.
+
+---
+
+## Example Prompts
+
+```
+Load my extension from /Users/me/my-extension and open the popup
+```
+
+```
+Click the button with selector #save and take a screenshot
+```
+
+```
+Navigate to https://example.com and check if my content script injected a .banner element
+```
+
+```
+Read all keys from chrome.storage.local
+```
+
+```
+Set { "enabled": true } in chrome.storage.local and verify it was saved
+```
+
+```
+Navigate to https://example.com, capture all network requests, then show me any that were blocked
+```
+
+```
+Check the badge text — it should say "ON"
+```
+
+```
+Send the message { "type": "GET_STATUS" } to the background and show the response
+```
+
+```
+Open a tab to https://news.ycombinator.com, then another to https://github.com, then list all open tabs
+```
+
+```
+Right-click on https://example.com and trigger the context menu item with id "my-action"
+```
+
+---
+
+## Project Structure
+
+```
+chrome-extension-testing-mcp/
+├── src/
+│   ├── index.js              # MCP server entry point
+│   ├── state.js              # Shared browser state and helpers
+│   ├── prompts/
+│   │   ├── index.js          # Registers MCP prompts
+│   │   └── extension-tester.js  # extension-tester-agent prompt definition
+│   └── tools/
+│       ├── index.js          # Aggregates all tool definitions and handlers
+│       ├── load-extension.js
+│       ├── popup.js
+│       ├── dom.js
+│       ├── logs.js
+│       ├── screenshot.js
+│       ├── assertion.js
+│       ├── storage.js
+│       ├── network.js
+│       ├── options-page.js
+│       ├── context-menu.js
+│       ├── badge.js
+│       ├── messaging.js
+│       └── tabs.js
+├── package.json
+└── README.md
+```
+
+---
+
+## Notes
+
+- The browser launches in **headed mode** (visible window) so you can watch tests run in real time
+- Screenshots default to `./screenshot.png` unless a custom path is provided
+- Service worker logs are buffered from the moment `load_extension` is called
+- 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)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "chrome-extension-tester-mcp",
+  "version": "2.0.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",
+  "bin": {
+    "chrome-extension-tester": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "postinstall": "playwright install chromium"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chrome-extension",
+    "testing",
+    "playwright",
+    "automation",
+    "browser-testing",
+    "claude"
+  ],
+  "author": "bhuvanrj",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BHUVAN-RJ/chrome-extension-testing-mcp"
+  },
+  "homepage": "https://github.com/BHUVAN-RJ/chrome-extension-testing-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/BHUVAN-RJ/chrome-extension-testing-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "playwright": "^1.44.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { TOOLS, HANDLERS } from "./tools/index.js";
+import { PROMPTS, PROMPT_HANDLERS } from "./prompts/index.js";
+
+const server = new Server(
+  { name: "chrome-extension-tester", version: "2.0.0" },
+  { capabilities: { tools: {}, prompts: {} } }
+);
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const handler = HANDLERS[name];
+
+  if (!handler) {
+    return {
+      content: [{ type: "text", text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  }
+
+  try {
+    return await handler(args || {});
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error in ${name}: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── Prompts ───────────────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const getMessages = PROMPT_HANDLERS[name];
+
+  if (!getMessages) {
+    throw new Error(`Unknown prompt: ${name}`);
+  }
+
+  const definition = PROMPTS.find((p) => p.name === name);
+
+  return {
+    description: definition.description,
+    messages: getMessages(args || {}),
+  };
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Chrome Extension Tester MCP server running (v2.0.0)...");

package/src/prompts/extension-tester.js

@@ -0,0 +1,138 @@
+export const definition = {
+  name: "extension-tester-agent",
+  description:
+    "A testing agent that validates all implemented changes in a Chrome extension. Understands what the extension does, derives tests from the changes list, runs every test using the MCP tools, and returns a structured PASS/FAIL report.",
+  arguments: [
+    {
+      name: "extension_path",
+      description: "Absolute path to the unpacked extension folder (must contain manifest.json)",
+      required: true,
+    },
+    {
+      name: "extension_description",
+      description:
+        "What this extension does — its purpose, key features, UI elements, storage it uses, pages it injects into, background behaviour, etc. The more detail the better.",
+      required: true,
+    },
+    {
+      name: "changes",
+      description:
+        "Everything that was implemented or changed in this session. List each change on its own line or separated by semicolons.",
+      required: true,
+    },
+  ],
+};
+
+export function getMessages({ extension_path, extension_description, changes }) {
+  return [
+    {
+      role: "user",
+      content: {
+        type: "text",
+        text: `
+You are a Chrome extension testing agent. Your job is to validate that every implemented change works correctly before the result is returned to the user.
+
+You have access to the chrome-extension-tester MCP tools:
+- load_extension          → launch Chrome with the extension loaded
+- interact_with_popup     → open popup, click, type, read text/HTML
+- open_options_page       → open and interact with the options/settings page
+- inspect_dom             → navigate to a URL, query selectors, or run JS
+- get_service_worker_logs → read background service worker console output
+- take_screenshot         → save a screenshot (use on any failure)
+- run_assertion           → assert element exists, has text, or a JS expression is true
+- extension_storage       → get/set/remove/clear chrome.storage (local/sync/session)
+- monitor_network         → capture network requests during navigation
+- check_badge             → read or assert the extension icon badge
+- send_message_to_background → send chrome.runtime.sendMessage and capture the response
+- test_context_menu       → verify context menu API or simulate right-click events
+- simulate_tab_events     → open, close, switch, and list browser tabs
+
+---
+
+## Extension
+
+**Path:** ${extension_path}
+
+**What it does:**
+${extension_description}
+
+---
+
+## Changes to validate
+
+${changes}
+
+---
+
+## Your process — follow this exactly
+
+### Phase 1 — Understand
+Read the extension description and the changes list carefully.
+For each change, reason about:
+- What part of the extension is affected (popup UI, background logic, content script, storage, messaging, options page, badge, context menu, network, tabs)
+- What the correct behaviour looks like after this change
+- Which MCP tools are the right ones to verify it
+
+### Phase 2 — Write a test plan
+Before running anything, output a numbered test plan:
+- One line per test
+- Format: [TOOL] Description of what is being verified
+- Cover EVERY change — do not skip anything
+
+Example:
+1. [load_extension] Load extension from path, confirm extension ID is detected
+2. [interact_with_popup] Open popup, assert #save-button exists
+3. [run_assertion] Assert #save-button has text "Save"
+4. [extension_storage] After clicking save, verify storage.local has { saved: true }
+5. [get_service_worker_logs] Check no errors logged during save flow
+
+### Phase 3 — Execute every test
+- Start by calling load_extension
+- Work through the test plan top to bottom
+- For each test: call the tool, record the result (PASS / FAIL + detail)
+- On any FAIL: call take_screenshot immediately, note the output path
+- Do not stop on failure — run every test and collect all results
+
+### Phase 4 — Report
+Output a final report in this exact format:
+
+---
+## Test Report
+
+**Extension:** ${extension_path}
+**Result:** PASS  ← or FAIL
+
+### Results
+
+| # | Test | Result | Detail |
+|---|------|--------|--------|
+| 1 | [load_extension] Load extension | PASS | ID: abcdef... |
+| 2 | [interact_with_popup] #save-button exists | FAIL | Element not found |
+| 3 | ... | ... | ... |
+
+### Failures
+(only if FAIL)
+For each failed test:
+- What was expected
+- What was actually observed
+- Screenshot path if taken
+- Likely cause based on the change description
+
+### Summary
+X of Y tests passed.
+(If all pass: "All changes verified. Ready to return to user.")
+(If any fail: "Do not return to user. Fix the following before re-testing: ...")
+---
+
+## Rules
+- Always load_extension first, even if the browser is already open
+- Never mark the result PASS if any single test failed
+- If a tool call errors, that counts as a FAIL for that test
+- Do not invent tests for things not in the changes list
+- Do not skip tests because they seem obvious
+- Be concise in tool calls — don't narrate, just execute
+`.trim(),
+      },
+    },
+  ];
+}

package/src/prompts/index.js

@@ -0,0 +1,9 @@
+import * as extensionTester from "./extension-tester.js";
+
+const allPrompts = [extensionTester];
+
+export const PROMPTS = allPrompts.map((p) => p.definition);
+
+export const PROMPT_HANDLERS = Object.fromEntries(
+  allPrompts.map((p) => [p.definition.name, p.getMessages])
+);

package/src/state.js

@@ -0,0 +1,50 @@
+import { chromium } from "playwright";
+import fs from "fs";
+import path from "path";
+
+export const state = {
+  browser: null,
+  page: null,
+  extensionId: null,
+  swLogs: [],
+  networkCaptures: [],
+};
+
+export async function ensureBrowser(extensionPath) {
+  if (state.browser) return;
+  const absPath = path.resolve(extensionPath);
+  if (!fs.existsSync(absPath)) throw new Error(`Extension path not found: ${absPath}`);
+
+  state.browser = await chromium.launchPersistentContext("", {
+    headless: false,
+    args: [
+      `--disable-extensions-except=${absPath}`,
+      `--load-extension=${absPath}`,
+    ],
+  });
+
+  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];
+  }
+
+  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.");
+    state.page = await state.browser.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();
+  if (!workers.length) throw new Error("No service worker found. Extension may not have a background service worker.");
+  return workers[0];
+}

package/src/tools/assertion.js

@@ -0,0 +1,66 @@
+import { ensurePage } from "../state.js";
+
+export const definition = {
+  name: "run_assertion",
+  description: "Run a test assertion against the current page. Checks a condition and reports PASS or FAIL.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      description: {
+        type: "string",
+        description: "Human-readable description of what is being tested",
+      },
+      selector: {
+        type: "string",
+        description: "CSS selector to check existence or text content of",
+      },
+      expected_text: {
+        type: "string",
+        description: "Expected text content of the element (optional, used with selector)",
+      },
+      script: {
+        type: "string",
+        description: "JS expression that must return true to pass (overrides selector)",
+      },
+    },
+    required: ["description"],
+  },
+};
+
+export async function handler(args) {
+  const p = await ensurePage();
+  let passed = false;
+  let detail = "";
+
+  try {
+    if (args.script) {
+      passed = !!(await p.evaluate(args.script));
+      detail = `Script: ${args.script}`;
+    } else if (args.selector) {
+      const el = await p.$(args.selector);
+      if (!el) {
+        passed = false;
+        detail = `Element "${args.selector}" not found`;
+      } else if (args.expected_text !== undefined) {
+        const actual = await el.textContent();
+        passed = actual.trim() === args.expected_text.trim();
+        detail = `Expected: "${args.expected_text}" | Got: "${actual.trim()}"`;
+      } else {
+        passed = true;
+        detail = `Element "${args.selector}" exists`;
+      }
+    } else {
+      return { content: [{ type: "text", text: "Provide a selector or script for the assertion." }] };
+    }
+  } catch (e) {
+    passed = false;
+    detail = `Error: ${e.message}`;
+  }
+
+  return {
+    content: [{
+      type: "text",
+      text: `${passed ? "PASS" : "FAIL"} — ${args.description}\n${detail}`,
+    }],
+  };
+}