@mcp-b/chrome-devtools-mcp 2.0.13 → 2.2.0

package/build/src/prompts/index.js

@@ -1,156 +0,0 @@
-/**
- * @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/tools/WebMCPToolHub.js

@@ -1,329 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * WebMCPToolHub manages dynamic registration of WebMCP tools as first-class MCP tools.
- *
- * When a page has WebMCP tools available, this hub:
- * 1. Syncs those tools to the MCP server as native tools
- * 2. Uses naming convention: webmcp_{domain}_page{idx}_{toolName}
- * 3. Updates tools when WebMCP sends list_changed notifications
- * 4. Removes tools when pages navigate or close
- *
- * This allows Claude Code to call WebMCP tools directly without the two-step
- * list_webmcp_tools -> call_webmcp_tool process.
- */
-export class WebMCPToolHub {
-    #server;
-    #context;
-    #logger;
-    /** Map of tool IDs to their tracking metadata. */
-    #trackedTools = new Map();
-    /** Tracks which tool IDs belong to each page (for cleanup on navigation). */
-    #pageTools = new WeakMap();
-    /** Guards against concurrent sync operations per page. */
-    #syncInProgress = new WeakSet();
-    /** Whether automatic tool tracking is enabled. */
-    #enabled = true;
-    constructor(server, context, enabled = true) {
-        this.#server = server;
-        this.#context = context;
-        this.#logger = context.logger;
-        this.#enabled = enabled;
-    }
-    /**
-     * Disable automatic tool registration
-     */
-    disable() {
-        this.#enabled = false;
-    }
-    /**
-     * Enable automatic tool registration
-     */
-    enable() {
-        this.#enabled = true;
-    }
-    /**
-     * Check if the hub is enabled
-     */
-    isEnabled() {
-        return this.#enabled;
-    }
-    /**
-     * Sync tools for a page. Called on:
-     * 1. Initial WebMCP connection
-     * 2. ToolListChangedNotificationSchema notification
-     *
-     * @param page - The browser page
-     * @param client - The MCP client (passed to avoid infinite loop via getWebMCPClient)
-     */
-    async syncToolsForPage(page, client) {
-        if (!this.#enabled) {
-            return { synced: 0, removed: 0, updated: 0 };
-        }
-        if (this.#syncInProgress.has(page)) {
-            this.#logger('Sync already in progress for page, skipping');
-            return { synced: 0, removed: 0, updated: 0 };
-        }
-        this.#syncInProgress.add(page);
-        const urlAtStart = page.url();
-        try {
-            const { tools } = await client.listTools();
-            // Guard: page navigated during async operation
-            if (page.url() !== urlAtStart) {
-                this.#logger('Page navigated during sync, aborting');
-                return { synced: 0, removed: 0, updated: 0 };
-            }
-            return this.#applyToolChanges(page, tools);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.#logger(`Failed to sync WebMCP tools: ${message}`);
-            // Return error indicator so callers know sync failed vs "no tools found"
-            return { synced: 0, removed: 0, updated: 0, error: message };
-        }
-        finally {
-            this.#syncInProgress.delete(page);
-        }
-    }
-    /**
-     * Remove all tracked tools for a page. Called on:
-     * 1. Transport close (navigation/page close)
-     * 2. Manual removal
-     */
-    removeToolsForPage(page) {
-        const toolIds = this.#pageTools.get(page);
-        if (!toolIds) {
-            return 0;
-        }
-        let removed = 0;
-        for (const toolId of toolIds) {
-            if (this.#trackedTools.has(toolId)) {
-                this.#logger(`Removing tracked WebMCP tool: ${toolId}`);
-                this.#trackedTools.delete(toolId);
-                removed++;
-            }
-        }
-        this.#pageTools.delete(page);
-        this.#logger(`Removed ${removed} tracked WebMCP tools for page`);
-        return removed;
-    }
-    /**
-     * Apply tool changes by comparing current tools with new tools from WebMCP.
-     * Handles add, update, and remove operations.
-     */
-    #applyToolChanges(page, tools) {
-        const domain = extractDomain(page.url());
-        const pageIdx = this.#context.getPages().indexOf(page);
-        // Guard: page not found in pages list (may have been closed)
-        if (pageIdx === -1) {
-            this.#logger('Page not found in pages list, skipping tool sync');
-            return { synced: 0, removed: 0, updated: 0 };
-        }
-        const newToolIds = new Set();
-        let synced = 0;
-        let updated = 0;
-        for (const tool of tools) {
-            const toolId = this.#generateToolId(domain, pageIdx, tool.name);
-            newToolIds.add(toolId);
-            const existing = this.#trackedTools.get(toolId);
-            if (existing) {
-                // Re-track to ensure metadata updates are applied
-                this.#logger(`Re-tracking WebMCP tool: ${toolId}`);
-                this.#trackedTools.delete(toolId);
-                this.#trackTool(page, domain, pageIdx, tool);
-                updated++;
-            }
-            else {
-                // Track new tool
-                this.#trackTool(page, domain, pageIdx, tool);
-                synced++;
-            }
-        }
-        // Remove tools that no longer exist
-        const existingToolIds = this.#pageTools.get(page) || new Set();
-        let removed = 0;
-        for (const toolId of existingToolIds) {
-            if (!newToolIds.has(toolId)) {
-                if (this.#trackedTools.has(toolId)) {
-                    this.#logger(`Removing stale WebMCP tool: ${toolId}`);
-                    this.#trackedTools.delete(toolId);
-                    removed++;
-                }
-            }
-        }
-        this.#pageTools.set(page, newToolIds);
-        this.#logger(`WebMCP tool tracking: ${synced} added, ${updated} updated, ${removed} removed`);
-        // No longer send tools/list_changed - tools are called directly via call_webmcp_tool
-        return { synced, removed, updated };
-    }
-    /**
-     * Track a tool (tools are called directly via call_webmcp_tool, not registered with MCP server)
-     */
-    #trackTool(page, domain, pageIdx, tool) {
-        const toolId = this.#generateToolId(domain, pageIdx, tool.name);
-        // Validate tool name and log any warnings
-        const warnings = validateToolName(tool.name);
-        for (const warning of warnings) {
-            this.#logger(`⚠️ Warning: ${warning}`);
-        }
-        this.#logger(`Tracking WebMCP tool: ${toolId}`);
-        // Track tool metadata including schemas and annotations
-        this.#trackedTools.set(toolId, {
-            page,
-            originalName: tool.name,
-            domain,
-            toolId,
-            description: tool.description || '',
-            inputSchema: tool.inputSchema,
-            outputSchema: tool.outputSchema,
-            annotations: tool.annotations,
-        });
-        // Track tool for this page
-        const pageToolSet = this.#pageTools.get(page) || new Set();
-        pageToolSet.add(toolId);
-        this.#pageTools.set(page, pageToolSet);
-    }
-    /**
-     * Generate a unique tool ID following the naming convention
-     */
-    #generateToolId(domain, pageIdx, toolName) {
-        return `webmcp_${domain}_page${pageIdx}_${sanitizeName(toolName)}`;
-    }
-    /**
-     * Get the total number of tracked tools
-     */
-    getToolCount() {
-        return this.#trackedTools.size;
-    }
-    /**
-     * Get all tracked tool IDs
-     */
-    getRegisteredToolIds() {
-        return Array.from(this.#trackedTools.keys());
-    }
-    /**
-     * Get all tracked tools with their metadata.
-     * Only returns tools from pages in the current session's window scope.
-     */
-    getRegisteredTools() {
-        const sessionPages = this.#context.getPages();
-        const result = [];
-        for (const rt of this.#trackedTools.values()) {
-            const pageIdx = sessionPages.indexOf(rt.page);
-            // Only include tools from pages in the session's window scope
-            if (pageIdx !== -1) {
-                result.push({
-                    toolId: rt.toolId,
-                    originalName: rt.originalName,
-                    domain: rt.domain,
-                    pageIdx,
-                    description: rt.description,
-                    inputSchema: rt.inputSchema,
-                    outputSchema: rt.outputSchema,
-                    annotations: rt.annotations,
-                });
-            }
-        }
-        return result;
-    }
-    /**
-     * Get a tracked tool by name and page.
-     */
-    getToolByName(toolName, page) {
-        const pageToolIds = this.#pageTools.get(page);
-        if (!pageToolIds) {
-            return undefined;
-        }
-        for (const toolId of pageToolIds) {
-            const tool = this.#trackedTools.get(toolId);
-            if (tool && tool.originalName === toolName) {
-                return tool;
-            }
-        }
-        return undefined;
-    }
-}
-/**
- * Sanitize a name to be used in tool IDs.
- * Replaces any non-alphanumeric characters (except underscore) with underscore.
- */
-export function sanitizeName(name) {
-    return name.replace(/[^a-zA-Z0-9_]/g, '_');
-}
-/**
- * Validate a tool name and return any warnings about the first character.
- * Tool names should start with a letter (a-z, A-Z) for best compatibility
- * with MCP clients. Starting with underscore, number, or hyphen may cause issues.
- *
- * NOTE: Similar validation logic exists in @mcp-b/global/src/global.ts for browser context.
- * Keep both implementations in sync when making changes.
- *
- * @param name - Tool name to validate
- * @returns Array of warning messages (empty if name starts with a letter)
- */
-export function validateToolName(name) {
-    const warnings = [];
-    // Check if name starts with underscore
-    if (name.startsWith('_')) {
-        warnings.push(`Tool name "${name}" starts with underscore. ` +
-            'This may cause compatibility issues with some MCP clients. ' +
-            'Consider using a letter as the first character.');
-    }
-    // Check if name starts with a number
-    if (/^[0-9]/.test(name)) {
-        warnings.push(`Tool name "${name}" starts with a number. ` +
-            'This may cause compatibility issues. ' +
-            'Consider using a letter as the first character.');
-    }
-    // Check if name starts with hyphen
-    if (name.startsWith('-')) {
-        warnings.push(`Tool name "${name}" starts with hyphen. ` +
-            'This may cause compatibility issues. ' +
-            'Consider using a letter as the first character.');
-    }
-    return warnings;
-}
-/**
- * Extract and sanitize domain from a URL.
- * Handles localhost specially to include port in the domain.
- * Returns 'unknown' for URLs without a valid hostname (about:blank, file://, data:, etc.)
- */
-export function extractDomain(url) {
-    try {
-        const urlObj = new URL(url);
-        const hostname = urlObj.hostname;
-        // Handle empty hostname (about:blank, file://, data:, etc.)
-        if (!hostname) {
-            return 'unknown';
-        }
-        const isLocalhost = hostname === 'localhost' ||
-            hostname === '127.0.0.1' ||
-            hostname === '[::1]';
-        const domain = isLocalhost
-            ? `localhost_${urlObj.port || '80'}`
-            : hostname;
-        return sanitizeName(domain);
-    }
-    catch (err) {
-        // Log at debug level for troubleshooting malformed URLs
-        if (typeof console !== 'undefined' && console.debug) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.debug(`[WebMCPToolHub] Failed to extract domain from URL "${url}": ${message}`);
-        }
-        return 'unknown';
-    }
-}
-/**
- * Convert a sanitized domain back to display format.
- * Handles localhost port conversion and general underscore-to-dot conversion.
- *
- * IMPORTANT: Handle localhost FIRST before general underscore replacement
- */
-export function getDisplayDomain(sanitizedDomain) {
-    return sanitizedDomain
-        .replace(/^localhost_(\d+)$/, 'localhost:$1')
-        .replace(/_/g, '.');
-}

package/build/src/tools/browser.js

@@ -1,92 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { zod } from '../third_party/index.js';
-import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
-export const connectToBrowser = defineTool({
-    name: 'connect_to_browser',
-    description: 'Connect to a different Chrome browser instance at runtime. ' +
-        'Disconnects from the current browser (without closing it) and attaches to the new one. ' +
-        'Useful for WXT extension development: run `wxt dev`, parse the debug URL from stdout, ' +
-        'then call this tool to attach. Retries automatically if the browser is still starting up.',
-    annotations: {
-        title: 'Connect to Browser',
-        category: ToolCategory.NAVIGATION,
-        readOnlyHint: false,
-    },
-    schema: {
-        browserUrl: zod
-            .string()
-            .optional()
-            .describe('HTTP URL to the browser\'s DevTools endpoint, e.g. "http://127.0.0.1:9222". ' +
-            'Exactly one of browserUrl or wsEndpoint is required.'),
-        wsEndpoint: zod
-            .string()
-            .optional()
-            .describe('WebSocket URL to connect to, e.g. "ws://127.0.0.1:9222/devtools/browser/...". ' +
-            'Exactly one of browserUrl or wsEndpoint is required.'),
-        wsHeaders: zod
-            .record(zod.string())
-            .optional()
-            .describe('Optional HTTP headers for WebSocket connection (only used with wsEndpoint).'),
-        timeout: zod
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe('Maximum time in milliseconds to wait for the browser to become available. ' +
-            'Defaults to 30000 (30 seconds). The tool retries every 2 seconds within this window.'),
-    },
-    handler: async (request, response, context) => {
-        const { browserUrl, wsEndpoint, wsHeaders, timeout } = request.params;
-        // Validate: exactly one connection method required
-        if (!browserUrl && !wsEndpoint) {
-            throw new Error('Either browserUrl or wsEndpoint is required. ' +
-                'Example: browserUrl "http://127.0.0.1:9222" or wsEndpoint "ws://127.0.0.1:9222/devtools/browser/..."');
-        }
-        if (browserUrl && wsEndpoint) {
-            throw new Error('Provide only one of browserUrl or wsEndpoint, not both.');
-        }
-        // Validate URL protocols
-        if (browserUrl && !browserUrl.startsWith('http://') && !browserUrl.startsWith('https://')) {
-            throw new Error(`Invalid browserUrl: "${browserUrl}". Must start with http:// or https://`);
-        }
-        if (wsEndpoint && !wsEndpoint.startsWith('ws://') && !wsEndpoint.startsWith('wss://')) {
-            throw new Error(`Invalid wsEndpoint: "${wsEndpoint}". Must start with ws:// or wss://`);
-        }
-        try {
-            const result = await context.reconnectBrowser({
-                browserURL: browserUrl,
-                wsEndpoint,
-                wsHeaders,
-                timeout,
-            });
-            response.appendResponseLine(`Connected to browser at ${wsEndpoint ?? browserUrl}`);
-            response.appendResponseLine(`WebSocket endpoint: ${result.wsEndpoint}`);
-            response.appendResponseLine('');
-            response.appendResponseLine('Pages:');
-            for (const page of result.pages) {
-                const marker = page.selected ? ' (selected)' : '';
-                response.appendResponseLine(`  [${page.index}] ${page.url}${marker}`);
-            }
-        }
-        catch (err) {
-            response.setIsError(true);
-            const message = err instanceof Error ? err.message : String(err);
-            response.appendResponseLine(`Failed to connect: ${message}`);
-            response.appendResponseLine('');
-            response.appendResponseLine('Troubleshooting:');
-            response.appendResponseLine('  - Ensure Chrome was launched with --remote-debugging-port=<port>');
-            response.appendResponseLine('  - Verify the URL is reachable: curl ' + (browserUrl ?? wsEndpoint));
-            if (timeout) {
-                response.appendResponseLine('  - Try increasing the timeout (current: ' + timeout + 'ms)');
-            }
-            else {
-                response.appendResponseLine('  - Try setting a longer timeout (default is 30s)');
-            }
-        }
-    },
-});

package/build/src/tools/extension.js

@@ -1,31 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { zod } from '../third_party/index.js';
-import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
-export const evaluateInExtensionWorker = defineTool({
-    name: 'evaluate_in_extension_worker',
-    description: 'Execute a JavaScript expression in a Chrome extension background service worker. ' +
-        'Useful for inspecting extension state (e.g., McpHub connections, offscreen status) ' +
-        'that is not accessible from page contexts.',
-    annotations: {
-        category: ToolCategory.DEBUGGING,
-        readOnlyHint: false,
-    },
-    schema: {
-        expression: zod
-            .string()
-            .describe('JavaScript expression to evaluate in the service worker.'),
-        extensionId: zod
-            .string()
-            .optional()
-            .describe('Extension ID to target. If omitted, the first extension service worker found is used.'),
-    },
-    handler: async (request, response, context) => {
-        const result = await context.evaluateInExtensionWorker(request.params.expression, request.params.extensionId);
-        response.appendResponseLine(JSON.stringify(result, null, 2));
-    },
-});