chrome-extension-tester-mcp 2.0.0

package/src/tools/badge.js

@@ -0,0 +1,76 @@
+import { getServiceWorker } from "../state.js";
+
+export const definition = {
+  name: "check_badge",
+  description: "Read or assert the extension icon badge text and background color from chrome.action.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["get", "assert_text", "assert_color"],
+        description: "get: return current badge text and color; assert_text: check badge text equals expected; assert_color: check badge background color matches expected RGBA",
+      },
+      tab_id: {
+        type: "number",
+        description: "Tab ID to scope the badge check (optional, defaults to global badge)",
+      },
+      expected_text: {
+        type: "string",
+        description: "Expected badge text (for assert_text)",
+      },
+      expected_color: {
+        type: "array",
+        items: { type: "number" },
+        description: "Expected RGBA color array e.g. [255, 0, 0, 255] (for assert_color)",
+      },
+    },
+    required: ["action"],
+  },
+};
+
+export async function handler(args) {
+  const sw = await getServiceWorker();
+  const tabId = args.tab_id ?? undefined;
+
+  const badge = await sw.evaluate(async (tabId) => {
+    const details = tabId !== undefined ? { tabId } : {};
+    const [text, color] = await Promise.all([
+      new Promise((resolve) => chrome.action.getBadgeText(details, resolve)),
+      new Promise((resolve) => chrome.action.getBadgeBackgroundColor(details, resolve)),
+    ]);
+    return { text, color };
+  }, tabId);
+
+  if (args.action === "get") {
+    return {
+      content: [{
+        type: "text",
+        text: `Badge Text: "${badge.text || "(empty)"}\nBadge Color (RGBA): [${badge.color.join(", ")}]`,
+      }],
+    };
+  }
+
+  if (args.action === "assert_text") {
+    const passed = badge.text.trim() === (args.expected_text ?? "").trim();
+    return {
+      content: [{
+        type: "text",
+        text: `${passed ? "PASS" : "FAIL"} — Badge text assertion\nExpected: "${args.expected_text}" | Got: "${badge.text}"`,
+      }],
+    };
+  }
+
+  if (args.action === "assert_color") {
+    if (!args.expected_color?.length) {
+      return { content: [{ type: "text", text: "Provide an 'expected_color' RGBA array for assert_color." }] };
+    }
+    const passed = args.expected_color.every((v, i) => v === badge.color[i]);
+    return {
+      content: [{
+        type: "text",
+        text: `${passed ? "PASS" : "FAIL"} — Badge color assertion\nExpected: [${args.expected_color.join(", ")}] | Got: [${badge.color.join(", ")}]`,
+      }],
+    };
+  }
+}

package/src/tools/context-menu.js

@@ -0,0 +1,85 @@
+import { ensurePage, getServiceWorker } from "../state.js";
+
+export const definition = {
+  name: "test_context_menu",
+  description: "Test context menus registered by the extension. Can verify the contextMenus API is available and simulate right-click events on page elements.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["check_api", "right_click", "trigger_item"],
+        description: "check_api: verify contextMenus API is available in service worker; right_click: simulate right-click on a selector (triggers contextmenu DOM event); trigger_item: invoke a context menu item handler by id via service worker",
+      },
+      url: {
+        type: "string",
+        description: "URL to navigate to before right-clicking (optional)",
+      },
+      selector: {
+        type: "string",
+        description: "CSS selector of the element to right-click (for 'right_click' action)",
+      },
+      menu_item_id: {
+        type: "string",
+        description: "The context menu item ID to trigger (for 'trigger_item' action — matches the id passed to chrome.contextMenus.create)",
+      },
+      page_url: {
+        type: "string",
+        description: "The pageUrl to pass to the onClicked handler (for 'trigger_item' action)",
+      },
+    },
+    required: ["action"],
+  },
+};
+
+export async function handler(args) {
+  if (args.action === "check_api") {
+    const sw = await getServiceWorker();
+    const result = await sw.evaluate(() => ({
+      available: typeof chrome.contextMenus !== "undefined",
+      hasCreate: typeof chrome.contextMenus?.create === "function",
+      hasRemove: typeof chrome.contextMenus?.remove === "function",
+      hasUpdate: typeof chrome.contextMenus?.update === "function",
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: `Context Menus API:\n${JSON.stringify(result, null, 2)}\n\nNote: chrome.contextMenus.getAll() is not available in MV3 service workers. Items are registered imperatively via chrome.contextMenus.create().`,
+      }],
+    };
+  }
+
+  if (args.action === "right_click") {
+    if (!args.selector) return { content: [{ type: "text", text: "Provide a 'selector' for right_click action." }] };
+    const p = await ensurePage();
+    if (args.url) await p.goto(args.url, { waitUntil: "domcontentloaded" });
+    await p.click(args.selector, { button: "right" });
+    return {
+      content: [{
+        type: "text",
+        text: `Right-click dispatched on "${args.selector}".\nThis fires the contextmenu DOM event on the element. Note: native Chrome context menus cannot be interacted with via Playwright — use 'trigger_item' to invoke the handler directly.`,
+      }],
+    };
+  }
+
+  if (args.action === "trigger_item") {
+    if (!args.menu_item_id) return { content: [{ type: "text", text: "Provide a 'menu_item_id' to trigger." }] };
+    const sw = await getServiceWorker();
+    // Directly invoke the onClicked listener by dispatching a synthetic event via the SW
+    const result = await sw.evaluate(({ menuItemId, pageUrl }) => {
+      return new Promise((resolve) => {
+        const info = { menuItemId, editable: false, pageUrl: pageUrl || "about:blank" };
+        const tab = { id: 0, index: 0, url: pageUrl || "about:blank", active: true, highlighted: true, pinned: false, incognito: false };
+        try {
+          chrome.contextMenus.onClicked.dispatch(info, tab);
+          resolve({ dispatched: true, menuItemId });
+        } catch (e) {
+          resolve({ dispatched: false, error: e.message });
+        }
+      });
+    }, { menuItemId: args.menu_item_id, pageUrl: args.page_url });
+    return {
+      content: [{ type: "text", text: `Context menu trigger result:\n${JSON.stringify(result, null, 2)}` }],
+    };
+  }
+}

package/src/tools/dom.js

@@ -0,0 +1,47 @@
+import { ensurePage } from "../state.js";
+
+export const definition = {
+  name: "inspect_dom",
+  description: "Inspect DOM elements or run JavaScript in a page context. Optionally navigate to a URL first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "URL to navigate to before inspecting (optional)",
+      },
+      selector: {
+        type: "string",
+        description: "CSS selector to query — returns outerHTML of all matching elements",
+      },
+      script: {
+        type: "string",
+        description: "JavaScript expression to evaluate in page context (overrides selector)",
+      },
+    },
+  },
+};
+
+export async function handler(args) {
+  const p = await ensurePage();
+  if (args.url) await p.goto(args.url, { waitUntil: "domcontentloaded" });
+
+  if (args.script) {
+    const result = await p.evaluate(args.script);
+    return { content: [{ type: "text", text: `Script result:\n${JSON.stringify(result, null, 2)}` }] };
+  }
+
+  if (args.selector) {
+    const elements = await p.$$eval(args.selector, (els) => els.map((el) => el.outerHTML));
+    return {
+      content: [{
+        type: "text",
+        text: elements.length
+          ? `Found ${elements.length} element(s) matching "${args.selector}":\n\n${elements.join("\n\n")}`
+          : `No elements found matching "${args.selector}"`,
+      }],
+    };
+  }
+
+  return { content: [{ type: "text", text: "Provide either a selector or a script." }] };
+}

package/src/tools/index.js

@@ -0,0 +1,35 @@
+import * as loadExtension from "./load-extension.js";
+import * as popup from "./popup.js";
+import * as dom from "./dom.js";
+import * as logs from "./logs.js";
+import * as screenshot from "./screenshot.js";
+import * as assertion from "./assertion.js";
+import * as storage from "./storage.js";
+import * as network from "./network.js";
+import * as optionsPage from "./options-page.js";
+import * as contextMenu from "./context-menu.js";
+import * as badge from "./badge.js";
+import * as messaging from "./messaging.js";
+import * as tabs from "./tabs.js";
+
+const allTools = [
+  loadExtension,
+  popup,
+  dom,
+  logs,
+  screenshot,
+  assertion,
+  storage,
+  network,
+  optionsPage,
+  contextMenu,
+  badge,
+  messaging,
+  tabs,
+];
+
+export const TOOLS = allTools.map((t) => t.definition);
+
+export const HANDLERS = Object.fromEntries(
+  allTools.map((t) => [t.definition.name, t.handler])
+);

package/src/tools/load-extension.js

@@ -0,0 +1,48 @@
+import path from "path";
+import { state, ensureBrowser } from "../state.js";
+
+export const definition = {
+  name: "load_extension",
+  description: "Load an unpacked Chrome extension from a local path and launch the browser. Call again to reload/restart.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      extension_path: {
+        type: "string",
+        description: "Absolute or relative path to the unpacked extension folder (must contain manifest.json)",
+      },
+    },
+    required: ["extension_path"],
+  },
+};
+
+export async function handler(args) {
+  if (state.browser) {
+    await state.browser.close();
+    state.browser = null;
+    state.page = null;
+    state.extensionId = null;
+    state.swLogs.length = 0;
+    state.networkCaptures.length = 0;
+  }
+
+  await ensureBrowser(args.extension_path);
+
+  state.browser.serviceWorkers().forEach((sw) => {
+    sw.on("console", (msg) =>
+      state.swLogs.push(`[${new Date().toISOString()}] ${msg.type()}: ${msg.text()}`)
+    );
+  });
+  state.browser.on("serviceworker", (sw) => {
+    sw.on("console", (msg) =>
+      state.swLogs.push(`[${new Date().toISOString()}] ${msg.type()}: ${msg.text()}`)
+    );
+  });
+
+  return {
+    content: [{
+      type: "text",
+      text: `Extension loaded.\nPath: ${path.resolve(args.extension_path)}\nExtension ID: ${state.extensionId || "unknown (no service worker detected)"}`,
+    }],
+  };
+}

package/src/tools/logs.js

@@ -0,0 +1,28 @@
+import { state } from "../state.js";
+
+export const definition = {
+  name: "get_service_worker_logs",
+  description: "Fetch console logs captured from the extension's background service worker.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      clear_after: {
+        type: "boolean",
+        description: "Clear the log buffer after reading (default: false)",
+      },
+    },
+  },
+};
+
+export async function handler(args) {
+  const logs = [...state.swLogs];
+  if (args.clear_after) state.swLogs.length = 0;
+  return {
+    content: [{
+      type: "text",
+      text: logs.length
+        ? `Service Worker Logs (${logs.length} entries):\n\n${logs.join("\n")}`
+        : "No service worker logs captured yet.",
+    }],
+  };
+}

package/src/tools/messaging.js

@@ -0,0 +1,66 @@
+import { state, ensurePage } from "../state.js";
+
+export const definition = {
+  name: "send_message_to_background",
+  description: "Send a chrome.runtime.sendMessage to the extension's background service worker and return the response. Runs from within the extension's popup context.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      message: {
+        type: "object",
+        description: "The message object to send (must be JSON-serializable)",
+      },
+      timeout_ms: {
+        type: "number",
+        description: "Milliseconds to wait for a response before timing out (default: 5000)",
+      },
+    },
+    required: ["message"],
+  },
+};
+
+export async function handler(args) {
+  if (!state.extensionId) {
+    return { content: [{ type: "text", text: "Extension ID not detected. Call load_extension first." }] };
+  }
+
+  const p = await ensurePage();
+  const currentUrl = p.url();
+
+  // Must be in extension context to use chrome.runtime.sendMessage
+  if (!currentUrl.startsWith(`chrome-extension://${state.extensionId}`)) {
+    await p.goto(`chrome-extension://${state.extensionId}/popup.html`, { waitUntil: "domcontentloaded" });
+  }
+
+  const timeout = args.timeout_ms || 5000;
+
+  const result = await p.evaluate(
+    ({ message, timeout }) =>
+      new Promise((resolve) => {
+        const timer = setTimeout(
+          () => resolve({ error: "Timeout: no response received within " + timeout + "ms" }),
+          timeout
+        );
+        chrome.runtime.sendMessage(message, (response) => {
+          clearTimeout(timer);
+          if (chrome.runtime.lastError) {
+            resolve({ error: chrome.runtime.lastError.message });
+          } else {
+            resolve({ response });
+          }
+        });
+      }),
+    { message: args.message, timeout }
+  );
+
+  if (result.error) {
+    return { content: [{ type: "text", text: `Message failed: ${result.error}` }] };
+  }
+
+  return {
+    content: [{
+      type: "text",
+      text: `Message sent: ${JSON.stringify(args.message, null, 2)}\n\nResponse: ${JSON.stringify(result.response, null, 2)}`,
+    }],
+  };
+}

package/src/tools/network.js

@@ -0,0 +1,84 @@
+import { state, ensurePage } from "../state.js";
+
+export const definition = {
+  name: "monitor_network",
+  description: "Monitor, capture, and inspect network requests. Useful for testing extensions that block, redirect, or modify requests (e.g. ad blockers, header modifiers).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["navigate_and_capture", "get_captured", "clear"],
+        description: "navigate_and_capture: go to a URL and record all requests; get_captured: return buffered results; clear: empty the buffer",
+      },
+      url: {
+        type: "string",
+        description: "URL to navigate to (required for navigate_and_capture)",
+      },
+      filter_pattern: {
+        type: "string",
+        description: "Only show requests whose URL contains this string (optional)",
+      },
+      include_types: {
+        type: "array",
+        items: { type: "string" },
+        description: "Filter by resource type: document, script, stylesheet, image, xhr, fetch, etc. (optional)",
+      },
+    },
+    required: ["action"],
+  },
+};
+
+export async function handler(args) {
+  if (args.action === "clear") {
+    state.networkCaptures.length = 0;
+    return { content: [{ type: "text", text: "Network capture buffer cleared." }] };
+  }
+
+  if (args.action === "get_captured") {
+    let entries = [...state.networkCaptures];
+    if (args.filter_pattern) entries = entries.filter((r) => r.url.includes(args.filter_pattern));
+    if (args.include_types?.length) entries = entries.filter((r) => args.include_types.includes(r.resourceType));
+    return {
+      content: [{
+        type: "text",
+        text: entries.length
+          ? `${entries.length} captured request(s):\n\n${entries.map((r) => `[${r.method}] [${r.resourceType}] ${r.status} ${r.url}`).join("\n")}`
+          : "No captured requests match the filter.",
+      }],
+    };
+  }
+
+  if (args.action === "navigate_and_capture") {
+    if (!args.url) return { content: [{ type: "text", text: "Provide a 'url' to navigate to." }] };
+
+    const p = await ensurePage();
+    const captured = [];
+
+    const onResponse = (response) => {
+      captured.push({
+        method: response.request().method(),
+        url: response.url(),
+        status: response.status(),
+        resourceType: response.request().resourceType(),
+      });
+    };
+
+    p.on("response", onResponse);
+    await p.goto(args.url, { waitUntil: "networkidle" });
+    p.off("response", onResponse);
+
+    captured.forEach((r) => state.networkCaptures.push(r));
+
+    let displayed = captured;
+    if (args.filter_pattern) displayed = displayed.filter((r) => r.url.includes(args.filter_pattern));
+    if (args.include_types?.length) displayed = displayed.filter((r) => args.include_types.includes(r.resourceType));
+
+    return {
+      content: [{
+        type: "text",
+        text: `Captured ${captured.length} total request(s)${args.filter_pattern ? ` (${displayed.length} matching "${args.filter_pattern}")` : ""}:\n\n${displayed.map((r) => `[${r.method}] [${r.resourceType}] ${r.status} ${r.url}`).join("\n")}`,
+      }],
+    };
+  }
+}

package/src/tools/options-page.js

@@ -0,0 +1,64 @@
+import { state, ensurePage } from "../state.js";
+
+export const definition = {
+  name: "open_options_page",
+  description: "Open the extension options/settings page (options.html or a custom page). Supports any extension page by filename.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      page: {
+        type: "string",
+        description: "Extension page filename to open (default: options.html). Change if the extension uses a different filename.",
+      },
+      action: {
+        type: "string",
+        enum: ["open", "click", "type", "get_text", "get_html"],
+        description: "Action to perform after opening (optional, defaults to just opening)",
+      },
+      selector: {
+        type: "string",
+        description: "CSS selector for interaction actions",
+      },
+      value: {
+        type: "string",
+        description: "Value to type (for 'type' action)",
+      },
+    },
+  },
+};
+
+export async function handler(args) {
+  if (!state.extensionId) {
+    return { content: [{ type: "text", text: "Extension ID not detected. Call load_extension first." }] };
+  }
+
+  const pageName = args.page || "options.html";
+  const optionsUrl = `chrome-extension://${state.extensionId}/${pageName}`;
+  const p = await ensurePage();
+
+  await p.goto(optionsUrl, { waitUntil: "domcontentloaded" });
+
+  if (!args.action || args.action === "open") {
+    return { content: [{ type: "text", text: `Options page opened at ${optionsUrl}` }] };
+  }
+
+  if (args.action === "click") {
+    await p.click(args.selector);
+    return { content: [{ type: "text", text: `Clicked: ${args.selector}` }] };
+  }
+
+  if (args.action === "type") {
+    await p.fill(args.selector, args.value || "");
+    return { content: [{ type: "text", text: `Typed "${args.value}" into ${args.selector}` }] };
+  }
+
+  if (args.action === "get_text") {
+    const text = await p.textContent(args.selector);
+    return { content: [{ type: "text", text: `Text content of "${args.selector}":\n${text}` }] };
+  }
+
+  if (args.action === "get_html") {
+    const html = await p.innerHTML(args.selector);
+    return { content: [{ type: "text", text: `Inner HTML of "${args.selector}":\n${html}` }] };
+  }
+}

package/src/tools/popup.js

@@ -0,0 +1,61 @@
+import { state, ensurePage } from "../state.js";
+
+export const definition = {
+  name: "interact_with_popup",
+  description: "Open the extension popup and interact with UI elements (click, type, read text/HTML).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["open", "click", "type", "get_text", "get_html"],
+        description: "Action to perform",
+      },
+      selector: {
+        type: "string",
+        description: "CSS selector for the target element (not needed for 'open')",
+      },
+      value: {
+        type: "string",
+        description: "Text to type (only for 'type' action)",
+      },
+    },
+    required: ["action"],
+  },
+};
+
+export async function handler(args) {
+  if (!state.extensionId && args.action === "open") {
+    return {
+      content: [{ type: "text", text: "Extension ID not detected. Make sure the extension has a background service worker." }],
+    };
+  }
+
+  const p = await ensurePage();
+
+  if (args.action === "open") {
+    const popupUrl = `chrome-extension://${state.extensionId}/popup.html`;
+    await p.goto(popupUrl, { waitUntil: "domcontentloaded" });
+    return { content: [{ type: "text", text: `Popup opened at ${popupUrl}` }] };
+  }
+
+  if (args.action === "click") {
+    await p.click(args.selector);
+    return { content: [{ type: "text", text: `Clicked: ${args.selector}` }] };
+  }
+
+  if (args.action === "type") {
+    await p.fill(args.selector, args.value || "");
+    return { content: [{ type: "text", text: `Typed "${args.value}" into ${args.selector}` }] };
+  }
+
+  if (args.action === "get_text") {
+    const text = await p.textContent(args.selector);
+    return { content: [{ type: "text", text: `Text content of "${args.selector}":\n${text}` }] };
+  }
+
+  if (args.action === "get_html") {
+    const html = await p.innerHTML(args.selector);
+    return { content: [{ type: "text", text: `Inner HTML of "${args.selector}":\n${html}` }] };
+  }
+}

package/src/tools/screenshot.js

@@ -0,0 +1,27 @@
+import path from "path";
+import { ensurePage } from "../state.js";
+
+export const definition = {
+  name: "take_screenshot",
+  description: "Take a screenshot of the current browser page or popup.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      output_path: {
+        type: "string",
+        description: "File path to save the screenshot (default: ./screenshot.png)",
+      },
+      full_page: {
+        type: "boolean",
+        description: "Capture the full scrollable page (default: false)",
+      },
+    },
+  },
+};
+
+export async function handler(args) {
+  const p = await ensurePage();
+  const outPath = path.resolve(args.output_path || "./screenshot.png");
+  await p.screenshot({ path: outPath, fullPage: args.full_page || false });
+  return { content: [{ type: "text", text: `Screenshot saved to: ${outPath}` }] };
+}