chrome-ai-bridge 1.0.0

package/build/src/tools/performance.js

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { logger } from '../logger.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+/**
+ * Consolidated performance tracing tool.
+ * Combines: performance_start_trace, performance_stop_trace, performance_analyze_insight
+ */
+export const performance = defineTool({
+    name: 'performance',
+    description: 'Performance trace: start, stop, or analyze insight.',
+    annotations: {
+        category: ToolCategories.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        op: z.enum(['start', 'stop', 'analyze']).describe('Operation'),
+        reload: z.boolean().optional().describe('Reload page on start'),
+        autoStop: z.boolean().optional().describe('Auto-stop after 5s'),
+        insightName: z.string().optional().describe('Insight name (for analyze)'),
+    },
+    handler: async (request, response, context) => {
+        const { op, reload, autoStop, insightName } = request.params;
+        switch (op) {
+            case 'start': {
+                if (context.isRunningPerformanceTrace()) {
+                    response.appendResponseLine('Error: trace already running. Use stop first.');
+                    return;
+                }
+                context.setIsRunningPerformanceTrace(true);
+                const page = context.getSelectedPage();
+                const pageUrlForTracing = page.url();
+                if (reload) {
+                    await page.goto('about:blank', { waitUntil: ['networkidle0'] });
+                }
+                const categories = [
+                    '-*',
+                    'blink.console',
+                    'blink.user_timing',
+                    'devtools.timeline',
+                    'disabled-by-default-devtools.screenshot',
+                    'disabled-by-default-devtools.timeline',
+                    'disabled-by-default-devtools.timeline.invalidationTracking',
+                    'disabled-by-default-devtools.timeline.frame',
+                    'disabled-by-default-devtools.timeline.stack',
+                    'disabled-by-default-v8.cpu_profiler',
+                    'disabled-by-default-v8.cpu_profiler.hires',
+                    'latencyInfo',
+                    'loading',
+                    'disabled-by-default-lighthouse',
+                    'v8.execute',
+                    'v8',
+                ];
+                await page.tracing.start({ categories });
+                if (reload) {
+                    await page.goto(pageUrlForTracing, { waitUntil: ['load'] });
+                }
+                if (autoStop) {
+                    await new Promise(resolve => setTimeout(resolve, 5_000));
+                    await stopTracingAndAppendOutput(page, response, context);
+                }
+                else {
+                    response.appendResponseLine('Trace started. Use stop to finish.');
+                }
+                break;
+            }
+            case 'stop': {
+                if (!context.isRunningPerformanceTrace()) {
+                    response.appendResponseLine('No trace running.');
+                    return;
+                }
+                const page = context.getSelectedPage();
+                await stopTracingAndAppendOutput(page, response, context);
+                break;
+            }
+            case 'analyze': {
+                if (!insightName) {
+                    throw new Error('insightName required for analyze');
+                }
+                const lastRecording = context.recordedTraces().at(-1);
+                if (!lastRecording) {
+                    response.appendResponseLine('No recorded traces. Run a trace first.');
+                    return;
+                }
+                const insightOutput = getInsightOutput(lastRecording, insightName);
+                if ('error' in insightOutput) {
+                    response.appendResponseLine(insightOutput.error);
+                    return;
+                }
+                response.appendResponseLine(insightOutput.output);
+                break;
+            }
+        }
+    },
+});
+async function stopTracingAndAppendOutput(page, response, context) {
+    try {
+        const traceEventsBuffer = await page.tracing.stop();
+        const result = await parseRawTraceBuffer(traceEventsBuffer);
+        response.appendResponseLine('Trace stopped.');
+        if (traceResultIsSuccess(result)) {
+            context.storeTraceRecording(result);
+            response.appendResponseLine('Summary:');
+            const traceSummaryText = getTraceSummary(result);
+            response.appendResponseLine(traceSummaryText);
+        }
+        else {
+            response.appendResponseLine('Parse error:');
+            response.appendResponseLine(result.error);
+        }
+    }
+    catch (e) {
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Error stopping trace: ${errorText}`);
+        response.appendResponseLine('Error:');
+        response.appendResponseLine(errorText);
+    }
+    finally {
+        context.setIsRunningPerformanceTrace(false);
+    }
+}

package/build/src/tools/screenshot.js

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const screenshot = defineTool({
+    name: 'take_screenshot',
+    description: 'Take screenshot of page or element.',
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        format: z.enum(['png', 'jpeg']).default('png').describe('Image format'),
+        uid: z.string().optional().describe('Element uid (optional)'),
+        fullPage: z.boolean().optional().describe('Full page screenshot'),
+    },
+    handler: async (request, response, context) => {
+        if (request.params.uid && request.params.fullPage) {
+            throw new Error('Cannot use both uid and fullPage');
+        }
+        let pageOrHandle;
+        if (request.params.uid) {
+            pageOrHandle = await context.getElementByUid(request.params.uid);
+        }
+        else {
+            pageOrHandle = context.getSelectedPage();
+        }
+        const screenshot = await pageOrHandle.screenshot({
+            type: request.params.format,
+            fullPage: request.params.fullPage,
+        });
+        response.appendResponseLine('Screenshot taken');
+        if (screenshot.length >= 2_000_000) {
+            const { filename } = await context.saveTemporaryFile(screenshot, `image/${request.params.format}`);
+            response.appendResponseLine(`Saved: ${filename}`);
+        }
+        else {
+            response.attachImage({
+                mimeType: `image/${request.params.format}`,
+                data: Buffer.from(screenshot).toString('base64'),
+            });
+        }
+    },
+});

package/build/src/tools/script.js

@@ -0,0 +1,39 @@
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const evaluateScript = defineTool({
+    name: 'evaluate_script',
+    description: 'Run JavaScript in page, return JSON result.',
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        function: z.string().describe('JS function string'),
+        args: z
+            .array(z.object({ uid: z.string().describe('Element uid') }))
+            .optional()
+            .describe('Element arguments'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const fn = await page.evaluateHandle(`(${request.params.function})`);
+        const args = [fn];
+        try {
+            for (const el of request.params.args ?? []) {
+                args.push(await context.getElementByUid(el.uid));
+            }
+            await context.waitForEventsAfterAction(async () => {
+                const result = await page.evaluate(async (fn, ...args) => {
+                    // @ts-expect-error no types.
+                    return JSON.stringify(await fn(...args));
+                }, ...args);
+                response.appendResponseLine('Result:');
+                response.appendResponseLine(result);
+            });
+        }
+        finally {
+            Promise.allSettled(args.map(arg => arg.dispose())).catch(() => { });
+        }
+    },
+});

package/build/src/tools/snapshot.js

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Locator } from 'puppeteer-core';
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const takeSnapshot = defineTool({
+    name: 'take_snapshot',
+    description: 'Get page elements with uids. Prefer over screenshot.',
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludeSnapshot(true);
+    },
+});
+export const waitFor = defineTool({
+    name: 'wait_for',
+    description: 'Wait for text to appear on page.',
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: true,
+    },
+    schema: {
+        text: z.string().describe('Text to wait for'),
+        timeout: z.number().optional().describe('Timeout ms (default: 30000)'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const timeout = request.params.timeout ?? 30000;
+        let locator = Locator.race([
+            page.locator(`aria/${request.params.text}`),
+            page.locator(`text/${request.params.text}`),
+        ]);
+        locator = locator.setTimeout(timeout);
+        await locator.wait();
+        response.appendResponseLine(`Found: "${request.params.text}"`);
+        response.setIncludeSnapshot(true);
+    },
+});

package/build/src/trace-processing/parse.js

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PerformanceInsightFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js';
+import { PerformanceTraceFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
+import { AgentFocus } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js';
+import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_end/models/trace/trace.js';
+import { logger } from '../logger.js';
+const engine = TraceEngine.TraceModel.Model.createWithAllHandlers();
+export function traceResultIsSuccess(x) {
+    return 'parsedTrace' in x;
+}
+export async function parseRawTraceBuffer(buffer) {
+    engine.resetProcessor();
+    if (!buffer) {
+        return {
+            error: 'No buffer was provided.',
+        };
+    }
+    const asString = new TextDecoder().decode(buffer);
+    if (!asString) {
+        return {
+            error: 'Decoding the trace buffer returned an empty string.',
+        };
+    }
+    try {
+        const data = JSON.parse(asString);
+        const events = Array.isArray(data) ? data : data.traceEvents;
+        await engine.parse(events);
+        const parsedTrace = engine.parsedTrace();
+        if (!parsedTrace) {
+            return {
+                error: 'No parsed trace was returned from the trace engine.',
+            };
+        }
+        const insights = parsedTrace?.insights ?? null;
+        return {
+            parsedTrace,
+            insights,
+        };
+    }
+    catch (e) {
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Unexpeced error parsing trace: ${errorText}`);
+        return {
+            error: errorText,
+        };
+    }
+}
+const extraFormatDescriptions = `Information on performance traces may contain main thread activity represented as call frames and network requests.
+
+${PerformanceTraceFormatter.callFrameDataFormatDescription}
+
+${PerformanceTraceFormatter.networkDataFormatDescription}
+`;
+export function getTraceSummary(result) {
+    const focus = AgentFocus.fromParsedTrace(result.parsedTrace);
+    const formatter = new PerformanceTraceFormatter(focus);
+    const output = formatter.formatTraceSummary();
+    return `${extraFormatDescriptions}
+
+${output}`;
+}
+export function getInsightOutput(result, insightName) {
+    if (!result.insights) {
+        return {
+            error: 'No Performance insights are available for this trace.',
+        };
+    }
+    // Currently, we do not support inspecting traces with multiple navigations. We either:
+    // 1. Find Insights from the first navigation (common case: user records a trace with a page reload to test load performance)
+    // 2. Fall back to finding Insights not associated with a navigation (common case: user tests an interaction without a page load).
+    const mainNavigationId = result.parsedTrace.data.Meta.mainFrameNavigations.at(0)?.args.data
+        ?.navigationId;
+    const insightsForNav = result.insights.get(mainNavigationId ?? TraceEngine.Types.Events.NO_NAVIGATION);
+    if (!insightsForNav) {
+        return {
+            error: 'No Performance Insights for this trace.',
+        };
+    }
+    const matchingInsight = insightName in insightsForNav.model
+        ? insightsForNav.model[insightName]
+        : null;
+    if (!matchingInsight) {
+        return {
+            error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
+        };
+    }
+    const formatter = new PerformanceInsightFormatter(AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight);
+    return { output: formatter.formatInsight() };
+}

package/build/src/utils/pagination.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const DEFAULT_PAGE_SIZE = 20;
+export function paginate(items, options) {
+    const total = items.length;
+    if (!options || noPaginationOptions(options)) {
+        return {
+            items,
+            currentPage: 0,
+            totalPages: 1,
+            hasNextPage: false,
+            hasPreviousPage: false,
+            startIndex: 0,
+            endIndex: total,
+            invalidPage: false,
+        };
+    }
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const totalPages = Math.max(1, Math.ceil(total / pageSize));
+    const { currentPage, invalidPage } = resolvePageIndex(options.pageIdx, totalPages);
+    const startIndex = currentPage * pageSize;
+    const pageItems = items.slice(startIndex, startIndex + pageSize);
+    const endIndex = startIndex + pageItems.length;
+    return {
+        items: pageItems,
+        currentPage,
+        totalPages,
+        hasNextPage: currentPage < totalPages - 1,
+        hasPreviousPage: currentPage > 0,
+        startIndex,
+        endIndex,
+        invalidPage,
+    };
+}
+function noPaginationOptions(options) {
+    return options.pageSize === undefined && options.pageIdx === undefined;
+}
+function resolvePageIndex(pageIdx, totalPages) {
+    if (pageIdx === undefined) {
+        return { currentPage: 0, invalidPage: false };
+    }
+    if (pageIdx < 0 || pageIdx >= totalPages) {
+        return { currentPage: 0, invalidPage: true };
+    }
+    return { currentPage: pageIdx, invalidPage: false };
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "chrome-ai-bridge",
+  "version": "1.0.0",
+  "description": "MCP server bridging Chrome browser and AI assistants (ChatGPT, Gemini). Browser automation + AI consultation.",
+  "type": "module",
+  "bin": "./scripts/cli.mjs",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./plugin-api": "./build/src/plugin-api.js"
+  },
+  "scripts": {
+    "build": "tsc && node --experimental-strip-types --no-warnings=ExperimentalWarning scripts/post-build.ts",
+    "dev": "MCP_ENV=development node scripts/mcp-wrapper.mjs",
+    "typecheck": "tsc --noEmit",
+    "format": "eslint --cache --fix . && prettier --write --cache .",
+    "check-format": "eslint --cache . && prettier --check --cache .;",
+    "docs": "npm run build && npm run docs:generate && npm run format",
+    "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts",
+    "start": "npm run build && node build/src/index.js",
+    "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",
+    "diagnose:ui": "echo 'Use diagnose_chatgpt_ui tool via MCP client (Claude Code)'",
+    "restart-mcp": "bash scripts/restart-mcp.sh",
+    "test": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test \"build/tests/**/*.test.js\"",
+    "test:only": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
+    "test:only:no-build": "node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
+    "test:update-snapshots": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-force-exit --test --test-update-snapshots \"build/tests/**/*.test.js\"",
+    "prepare": "node --experimental-strip-types scripts/prepare.ts",
+    "sync-server-json-version": "node  --experimental-strip-types scripts/sync-server-json-version.ts && npm run format"
+  },
+  "files": [
+    "build/src",
+    "build/node_modules",
+    "README.md",
+    "LICENSE",
+    "!*.tsbuildinfo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usedhonda/chrome-ai-bridge.git"
+  },
+  "author": "usedhonda (forked from Google LLC)",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/usedhonda/chrome-devtools-mcp/issues"
+  },
+  "homepage": "https://github.com/usedhonda/chrome-devtools-mcp#readme",
+  "mcpName": "chrome-ai-bridge",
+  "keywords": [
+    "mcp",
+    "chrome",
+    "devtools",
+    "chrome-extension",
+    "webstore",
+    "browser-automation",
+    "extension-development"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.18.1",
+    "archiver": "^7.0.1",
+    "debug": "4.4.3",
+    "puppeteer": "^24.31.0",
+    "yargs": "18.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@stylistic/eslint-plugin": "^5.4.0",
+    "@types/archiver": "^6.0.2",
+    "@types/debug": "^4.1.12",
+    "@types/filesystem": "^0.0.36",
+    "@types/node": "^24.3.3",
+    "@types/sinon": "^17.0.4",
+    "@types/yargs": "^17.0.33",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "chokidar": "^4.0.3",
+    "chrome-devtools-frontend": "^1.0.1550444",
+    "eslint": "^9.35.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2",
+    "sinon": "^21.0.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.43.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/scripts/cli.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * CLI Entry Point for chrome-devtools-mcp-for-extension
+ *
+ * This is the entry point when users run:
+ *   npx chrome-devtools-mcp-for-extension
+ *   chrome-devtools-mcp-for-extension (if globally installed)
+ *
+ * Launches the MCP server with browser globals mock:
+ * - Loads browser-globals-mock.mjs BEFORE main.js
+ * - Ensures chrome-devtools-frontend modules work in Node.js
+ * - Simple execution: no wrapper, no hot-reload
+ */
+
+import {spawn} from 'node:child_process';
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+
+// Resolve paths
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mockPath = path.join(__dirname, 'browser-globals-mock.mjs');
+const mainPath = path.join(__dirname, '..', 'build', 'src', 'main.js');
+
+// Launch MCP server with --import flag
+const child = spawn(
+  process.execPath,
+  [
+    '--import',
+    mockPath,
+    mainPath,
+    ...process.argv.slice(2), // Forward CLI arguments
+  ],
+  {
+    stdio: 'inherit',
+    env: process.env,
+  },
+);
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exit(1);
+  }
+  process.exit(code ?? 0);
+});
+
+// Forward signals
+process.on('SIGTERM', () => child?.kill('SIGTERM'));
+process.on('SIGINT', () => child?.kill('SIGINT'));