@mcp-b/chrome-devtools-mcp 0.0.0-beta-20260116040639

package/build/src/main.js

@@ -0,0 +1,259 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import './polyfill.js';
+import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { parseArguments } from './cli.js';
+import { loadIssueDescriptions } from './issue-descriptions.js';
+import { logger, saveLogsToFile } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
+import { McpServer, StdioServerTransport, SetLevelRequestSchema, zod, } from './third_party/index.js';
+import { registerPrompts } from './prompts/index.js';
+import { ToolCategory } from './tools/categories.js';
+import { tools } from './tools/tools.js';
+import { WebMCPToolHub } from './tools/WebMCPToolHub.js';
+/**
+ * Package version (managed by release-please).
+ * @remarks If moved, update release-please config.
+ */
+// x-release-please-start-version
+const VERSION = '1.5.6';
+// x-release-please-end
+process.on('unhandledRejection', (reason, promise) => {
+    logger('Unhandled promise rejection', promise, reason);
+});
+export const args = parseArguments(VERSION);
+const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
+const server = new McpServer({
+    name: 'chrome_devtools',
+    title: 'Chrome DevTools MCP server',
+    version: VERSION,
+}, { capabilities: { logging: {}, prompts: {}, tools: { listChanged: true } } });
+// Register WebMCP development prompts
+registerPrompts(server);
+server.server.setRequestHandler(SetLevelRequestSchema, () => {
+    return {};
+});
+/** Cached McpContext instance for the current browser. */
+let context;
+/**
+ * Get or create the McpContext for browser operations.
+ *
+ * Handles browser connection/launch with the following priority:
+ * 1. Explicit browserUrl/wsEndpoint - connect directly
+ * 2. autoConnect enabled - try connecting, fall back to launching
+ * 3. Otherwise - launch a new browser
+ *
+ * @returns Initialized McpContext ready for tool operations.
+ */
+async function getContext() {
+    const extraArgs = (args.chromeArg ?? []).map(String);
+    if (args.proxyServer) {
+        extraArgs.push(`--proxy-server=${args.proxyServer}`);
+    }
+    const devtools = args.experimentalDevtools ?? false;
+    let browser;
+    let wasLaunched = false;
+    // If explicit browserUrl or wsEndpoint is provided, connect without fallback
+    if (args.browserUrl || args.wsEndpoint) {
+        browser = await ensureBrowserConnected({
+            browserURL: args.browserUrl,
+            wsEndpoint: args.wsEndpoint,
+            wsHeaders: args.wsHeaders,
+            devtools,
+            channel: undefined,
+            userDataDir: args.userDataDir,
+        });
+    }
+    // If autoConnect is true, try connecting first, then fall back to launching
+    else if (args.autoConnect) {
+        try {
+            logger('Attempting to connect to running browser instance...');
+            browser = await ensureBrowserConnected({
+                browserURL: undefined,
+                wsEndpoint: undefined,
+                wsHeaders: undefined,
+                devtools,
+                channel: args.channel,
+                userDataDir: args.userDataDir,
+            });
+            logger('Successfully connected to running browser instance');
+        }
+        catch (err) {
+            logger('Failed to connect to running browser, launching new instance...', err);
+            browser = await ensureBrowserLaunched({
+                headless: args.headless,
+                executablePath: args.executablePath,
+                channel: args.channel,
+                isolated: args.isolated ?? false,
+                userDataDir: args.userDataDir,
+                logFile,
+                viewport: args.viewport,
+                args: extraArgs,
+                acceptInsecureCerts: args.acceptInsecureCerts,
+                devtools,
+            });
+            wasLaunched = true;
+        }
+    }
+    // Otherwise, just launch a new browser
+    else {
+        browser = await ensureBrowserLaunched({
+            headless: args.headless,
+            executablePath: args.executablePath,
+            channel: args.channel,
+            isolated: args.isolated ?? false,
+            userDataDir: args.userDataDir,
+            logFile,
+            viewport: args.viewport,
+            args: extraArgs,
+            acceptInsecureCerts: args.acceptInsecureCerts,
+            devtools,
+        });
+        wasLaunched = true;
+    }
+    if (context?.browser !== browser) {
+        context = await McpContext.from(browser, logger, {
+            experimentalDevToolsDebugging: devtools,
+            experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+        });
+        if (wasLaunched) {
+            // Fresh browser launch - use the existing default page
+            // Mark it as explicitly selected so this session stays pinned to it
+            context.selectPage(context.getSelectedPage(), true);
+            logger('Using existing window for this MCP session');
+            // Resize the window to nearly full screen
+            try {
+                const page = context.getSelectedPage();
+                const browserTarget = browser.target();
+                const cdpSession = await browserTarget.createCDPSession();
+                // @ts-expect-error _targetId is internal but stable
+                const targetId = page.target()._targetId;
+                const { windowId } = await cdpSession.send('Browser.getWindowForTarget', {
+                    targetId,
+                });
+                await cdpSession.send('Browser.setWindowBounds', {
+                    windowId,
+                    bounds: {
+                        left: 20,
+                        top: 20,
+                        width: 1800,
+                        height: 1200,
+                        windowState: 'normal',
+                    },
+                });
+                await cdpSession.detach();
+                logger('Resized window to nearly full screen');
+            }
+            catch (err) {
+                // Non-fatal: window sizing is best-effort
+                logger('Failed to resize window:', err);
+            }
+        }
+        else {
+            // Connected to existing browser - create new window for isolation
+            // This ensures multiple MCP clients don't step on each other's toes
+            await context.newWindow();
+            logger('Created new window for this MCP session');
+        }
+        // Initialize WebMCP tool hub for dynamic tool registration
+        const toolHub = new WebMCPToolHub(server, context);
+        context.setToolHub(toolHub);
+        logger('WebMCPToolHub initialized for dynamic tool registration');
+    }
+    return context;
+}
+/**
+ * Log security disclaimers to stderr.
+ *
+ * Warns users that browser content is exposed to MCP clients.
+ */
+const logDisclaimers = () => {
+    console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
+debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
+};
+/**
+ * Mutex to serialize tool execution and prevent concurrent modifications.
+ */
+const toolMutex = new Mutex();
+/**
+ * Register a tool with the MCP server.
+ *
+ * Handles category-based filtering (emulation, performance, network)
+ * and wraps the handler with context initialization and error handling.
+ *
+ * @param tool - Tool definition to register.
+ */
+function registerTool(tool) {
+    if (tool.annotations.category === ToolCategory.EMULATION &&
+        args.categoryEmulation === false) {
+        return;
+    }
+    if (tool.annotations.category === ToolCategory.PERFORMANCE &&
+        args.categoryPerformance === false) {
+        return;
+    }
+    if (tool.annotations.category === ToolCategory.NETWORK &&
+        args.categoryNetwork === false) {
+        return;
+    }
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: zod.object(tool.schema).passthrough(),
+        annotations: tool.annotations,
+    }, async (params) => {
+        const guard = await toolMutex.acquire();
+        try {
+            logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            const context = await getContext();
+            logger(`${tool.name} context: resolved`);
+            await context.detectOpenDevToolsWindows();
+            const response = new McpResponse();
+            await tool.handler({
+                params,
+            }, response, context);
+            const content = await response.handle(tool.name, context);
+            const result = {
+                content,
+            };
+            if (response.isError) {
+                result.isError = true;
+            }
+            return result;
+        }
+        catch (err) {
+            logger(`${tool.name} error:`, err, err?.stack);
+            let errorText = err && 'message' in err ? err.message : String(err);
+            if ('cause' in err && err.cause) {
+                errorText += `\nCause: ${err.cause.message}`;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: errorText,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        finally {
+            guard.dispose();
+        }
+    });
+}
+for (const tool of tools) {
+    registerTool(tool);
+}
+await loadIssueDescriptions();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Chrome DevTools MCP Server connected');
+logDisclaimers();

package/build/src/polyfill.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// polyfills are now bundled with all other dependencies
+import './third_party/index.js';

package/build/src/polyfillLoader.js

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+const require = createRequire(import.meta.url);
+let cachedPolyfill = null;
+/**
+ * Load the @mcp-b/global IIFE polyfill code.
+ * This polyfill provides the navigator.modelContext API for pages that don't have WebMCP.
+ * Cached after first load for performance.
+ *
+ * @returns The IIFE JavaScript code as a string
+ * @throws Error if the polyfill file cannot be found or read
+ */
+export function getPolyfillCode() {
+    if (cachedPolyfill) {
+        return cachedPolyfill;
+    }
+    try {
+        // Use Node's module resolution to find the package regardless of
+        // workspace structure or installation method (pnpm, npm, yarn).
+        // Use the package's exported subpath '@mcp-b/global/iife' which resolves
+        // to the IIFE bundle via the exports field in package.json.
+        const polyfillPath = require.resolve('@mcp-b/global/iife');
+        cachedPolyfill = readFileSync(polyfillPath, 'utf-8');
+        return cachedPolyfill;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Provide actionable error message
+        throw new Error(`Could not find @mcp-b/global polyfill: ${message}\n` +
+            'Run `pnpm build` in the global package or ensure @mcp-b/global is installed.');
+    }
+}
+/**
+ * Clear the cached polyfill code, forcing the next getPolyfillCode() call
+ * to reload from disk. Useful for testing or after @mcp-b/global updates.
+ */
+export function clearPolyfillCache() {
+    cachedPolyfill = null;
+}

package/build/src/prompts/index.js

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2025 WebMCP Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod as z } from '../third_party/index.js';
+/**
+ * Registers MCP prompts for AI-driven development workflows.
+ */
+export function registerPrompts(server) {
+    // WebMCP Development Workflow prompt
+    server.registerPrompt('webmcp-dev-workflow', {
+        title: 'WebMCP Development Workflow',
+        description: 'Guides you through the AI-driven development workflow for building and testing WebMCP tools. ' +
+            'Use this when developing web applications that expose MCP tools.',
+    }, () => {
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `You are helping me develop WebMCP tools for my web application. Here's the workflow:
+
+## AI-Driven Tool Development Workflow
+
+1. **Write the Tool**: I'll ask you to create a WebMCP tool in my codebase using @mcp-b/global
+2. **Hot Reload**: My dev server will automatically reload with the new tool
+3. **Navigate**: Use navigate_page to open my dev server (e.g., http://localhost:3000)
+4. **Discover**: Use list_webmcp_tools to see registered tools (shown with callable names like webmcp_localhost_3000_page0_my_tool)
+5. **Test**: Call the tool directly by its prefixed name (e.g., webmcp_localhost_3000_page0_my_tool)
+6. **Iterate**: If something is wrong, fix the code and repeat
+
+## Tool Registration Pattern
+
+\`\`\`typescript
+import '@mcp-b/global';
+
+navigator.modelContext.registerTool({
+  name: 'tool_name',
+  description: 'What this tool does',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param1: { type: 'string', description: 'Parameter description' }
+    },
+    required: ['param1']
+  },
+  async execute(args) {
+    // Implementation
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result) }]
+    };
+  }
+});
+\`\`\`
+
+What would you like to build? Describe the tool you need and I'll help you implement and test it.`,
+                    },
+                },
+            ],
+        };
+    });
+    // Test WebMCP Tool prompt
+    server.registerPrompt('test-webmcp-tool', {
+        title: 'Test WebMCP Tool',
+        description: 'Systematically test a WebMCP tool on the current page. ' +
+            'Discovers available tools and helps you test them with various inputs.',
+        argsSchema: {
+            toolName: z
+                .string()
+                .optional()
+                .describe('Optional: specific tool name to test'),
+            devServerUrl: z
+                .string()
+                .optional()
+                .describe('Optional: URL of your dev server (default: http://localhost:3000)'),
+        },
+    }, args => {
+        const url = args?.devServerUrl || 'http://localhost:3000';
+        const toolNameInstruction = args?.toolName
+            ? `Focus on testing the "${args.toolName}" tool specifically.`
+            : 'List all available tools and help me choose which one to test.';
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Help me test WebMCP tools on my development server.
+
+## Test Plan
+
+1. Navigate to ${url}
+2. Use list_webmcp_tools to discover registered tools (shown with callable names like webmcp_localhost_3000_page0_tool_name)
+3. ${toolNameInstruction}
+4. Call the tool directly by its prefixed name and test with various inputs:
+   - Valid inputs (happy path)
+   - Edge cases (empty strings, nulls, etc.)
+   - Invalid inputs (wrong types, missing required fields)
+5. Report the results and any issues found
+
+Please start by navigating to the page and listing the available tools.`,
+                    },
+                },
+            ],
+        };
+    });
+    // Debug WebMCP Connection prompt
+    server.registerPrompt('debug-webmcp', {
+        title: 'Debug WebMCP Connection',
+        description: 'Troubleshoot WebMCP connection issues. ' +
+            'Helps diagnose why tools are not appearing or not working.',
+        argsSchema: {
+            url: z
+                .string()
+                .optional()
+                .describe('URL of the page to debug (default: current page)'),
+        },
+    }, args => {
+        const urlInstruction = args?.url
+            ? `Navigate to ${args.url} first.`
+            : 'Use the current page.';
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Help me debug WebMCP connectivity issues.
+
+${urlInstruction}
+
+## Debugging Steps
+
+1. **Check page load**: Take a snapshot to verify the page loaded correctly
+2. **Check console**: Use list_console_messages to look for:
+   - Errors loading @mcp-b/global
+   - Tool registration errors
+   - Any JavaScript errors
+3. **Test WebMCP**: Try list_webmcp_tools to see if connection works
+4. **Verify registration**: If no tools appear, check if the code properly imports '@mcp-b/global' and calls registerTool
+
+## Common Issues
+
+- **"WebMCP not detected"**: The page doesn't have @mcp-b/global loaded
+- **Tools not appearing**: Registration code might not be executing
+- **Connection timeout**: Page might still be loading
+
+Please start the diagnosis.`,
+                    },
+                },
+            ],
+        };
+    });
+}

package/build/src/third_party/index.js

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import 'core-js/modules/es.promise.with-resolvers.js';
+import 'core-js/proposals/iterator-helpers.js';
+export { default as yargs } from 'yargs';
+export { hideBin } from 'yargs/helpers';
+export { default as debug } from 'debug';
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+export { SetLevelRequestSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
+export { z as zod } from 'zod/v4';
+export { Locator, PredefinedNetworkConditions, CDPSessionEvent, } from 'puppeteer-core';
+export { default as puppeteer } from 'puppeteer-core';

package/build/src/tools/ToolDefinition.js

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+export function defineTool(definition) {
+    return definition;
+}
+export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';
+export const timeoutSchema = {
+    timeout: zod
+        .number()
+        .int()
+        .optional()
+        .describe(`Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`)
+        .transform(value => {
+        return value && value <= 0 ? undefined : value;
+    }),
+};