@mcp-b/chrome-devtools-mcp 1.2.0 → 1.3.1

package/build/src/tools/WebMCPToolHub.js

@@ -0,0 +1,372 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
+import { zod, } from '../third_party/index.js';
+/**
+ * Convert a JSON Schema inputSchema from WebMCP to a Zod schema.
+ *
+ * Falls back to a permissive passthrough schema if conversion fails,
+ * allowing the tool to still be registered and used.
+ *
+ * @param inputSchema - The JSON Schema from the WebMCP tool definition.
+ * @param logger - Optional logger for conversion errors.
+ * @returns A Zod schema for parameter validation.
+ */
+function convertInputSchema(inputSchema, logger) {
+    if (!inputSchema) {
+        return zod.object({}).passthrough();
+    }
+    try {
+        return jsonSchemaToZod(inputSchema);
+    }
+    catch (err) {
+        logger?.('Failed to convert inputSchema to Zod:', err);
+        return zod.object({}).passthrough();
+    }
+}
+/**
+ * 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
+ * diff_webmcp_tools -> call_webmcp_tool process.
+ */
+export class WebMCPToolHub {
+    #server;
+    #context;
+    #logger;
+    /** Map of tool IDs to their registration metadata. */
+    #registeredTools = 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 registration is enabled. */
+    #enabled = true;
+    /** Global diff state for diff_webmcp_tools - tracks last seen tool IDs. */
+    #lastSeenToolIds = null;
+    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) {
+            this.#logger('Failed to sync WebMCP tools:', err);
+            return { synced: 0, removed: 0, updated: 0 };
+        }
+        finally {
+            this.#syncInProgress.delete(page);
+        }
+    }
+    /**
+     * Remove all 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) {
+            const registered = this.#registeredTools.get(toolId);
+            if (registered) {
+                this.#logger(`Removing WebMCP tool: ${toolId}`);
+                registered.handle.remove();
+                this.#registeredTools.delete(toolId);
+                removed++;
+            }
+        }
+        this.#pageTools.delete(page);
+        this.#logger(`Removed ${removed} 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.#registeredTools.get(toolId);
+            if (existing) {
+                // Remove and re-register to ensure schema updates are applied
+                // (MCP SDK's update() doesn't support schema changes)
+                this.#logger(`Re-registering WebMCP tool: ${toolId}`);
+                existing.handle.remove();
+                this.#registeredTools.delete(toolId);
+                this.#registerTool(page, domain, pageIdx, tool);
+                updated++;
+            }
+            else {
+                // Register new tool
+                this.#registerTool(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)) {
+                const registered = this.#registeredTools.get(toolId);
+                if (registered) {
+                    this.#logger(`Removing stale WebMCP tool: ${toolId}`);
+                    registered.handle.remove();
+                    this.#registeredTools.delete(toolId);
+                    removed++;
+                }
+            }
+        }
+        this.#pageTools.set(page, newToolIds);
+        this.#logger(`WebMCP tool sync: ${synced} added, ${updated} updated, ${removed} removed`);
+        return { synced, removed, updated };
+    }
+    /**
+     * Register a single tool with the MCP server
+     */
+    #registerTool(page, domain, pageIdx, tool) {
+        const toolId = this.#generateToolId(domain, pageIdx, tool.name);
+        const description = this.#generateDescription(domain, pageIdx, tool.description);
+        this.#logger(`Registering WebMCP tool: ${toolId}`);
+        // Store tool name for use in the callback closure
+        const originalToolName = tool.name;
+        // Convert the JSON Schema inputSchema to Zod for MCP SDK registration
+        const zodSchema = convertInputSchema(tool.inputSchema, this.#logger);
+        const handle = this.#server.registerTool(toolId, {
+            description,
+            inputSchema: zodSchema,
+        }, async (params) => {
+            // Look up page dynamically to handle potential stale references
+            const currentPage = this.#getPageForTool(toolId);
+            if (!currentPage) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Tool no longer available - page may have closed or navigated',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Pass params directly - they are already parsed by MCP SDK using the Zod schema
+            return this.#executeTool(currentPage, originalToolName, params);
+        });
+        this.#registeredTools.set(toolId, {
+            handle,
+            page,
+            originalName: tool.name,
+            domain,
+            toolId,
+            description,
+        });
+        // Track tool for this page
+        const pageToolSet = this.#pageTools.get(page) || new Set();
+        pageToolSet.add(toolId);
+        this.#pageTools.set(page, pageToolSet);
+    }
+    /**
+     * Execute a WebMCP tool on a page
+     */
+    async #executeTool(page, toolName, args) {
+        try {
+            const result = await this.#context.getWebMCPClient(page);
+            if (!result.connected) {
+                return {
+                    content: [{ type: 'text', text: 'WebMCP connection lost' }],
+                    isError: true,
+                };
+            }
+            const callResult = await result.client.callTool({
+                name: toolName,
+                arguments: args,
+            });
+            // The SDK's callTool returns CallToolResult, but we need to handle
+            // the content array properly
+            return callResult;
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Tool error: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    /**
+     * Get the page associated with a registered tool
+     */
+    #getPageForTool(toolId) {
+        const registered = this.#registeredTools.get(toolId);
+        return registered?.page;
+    }
+    /**
+     * Generate a unique tool ID following the naming convention
+     */
+    #generateToolId(domain, pageIdx, toolName) {
+        return `webmcp_${domain}_page${pageIdx}_${sanitizeName(toolName)}`;
+    }
+    /**
+     * Generate a tool description with WebMCP context
+     */
+    #generateDescription(domain, pageIdx, originalDescription) {
+        const displayDomain = getDisplayDomain(domain);
+        return `[WebMCP - ${displayDomain} - Page ${pageIdx}] ${originalDescription || 'No description'}`;
+    }
+    /**
+     * Get the total number of registered tools
+     */
+    getToolCount() {
+        return this.#registeredTools.size;
+    }
+    /**
+     * Get all registered tool IDs
+     */
+    getRegisteredToolIds() {
+        return Array.from(this.#registeredTools.keys());
+    }
+    /**
+     * Get all registered tools with their metadata (for diff_webmcp_tools)
+     */
+    getRegisteredTools() {
+        return Array.from(this.#registeredTools.values()).map(rt => ({
+            toolId: rt.toolId,
+            originalName: rt.originalName,
+            domain: rt.domain,
+            pageIdx: this.#context.getPages().indexOf(rt.page),
+            description: rt.description,
+        }));
+    }
+    /**
+     * Get the last seen tool IDs for diff tracking
+     */
+    getLastSeenToolIds() {
+        return this.#lastSeenToolIds;
+    }
+    /**
+     * Set the last seen tool IDs for diff tracking
+     */
+    setLastSeenToolIds(toolIds) {
+        this.#lastSeenToolIds = toolIds;
+    }
+    /**
+     * Clear the last seen tool IDs (resets diff state)
+     */
+    clearLastSeenToolIds() {
+        this.#lastSeenToolIds = null;
+    }
+}
+/**
+ * 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, '_');
+}
+/**
+ * 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 {
+        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/pages.js

@@ -29,12 +29,18 @@ export const selectPage = defineTool({
     schema: {
         pageIdx: zod
             .number()
-            .describe('The index of the page to select. Call list_pages to list pages.'),
+            .describe(`The index of the page to select. Call ${listPages.name} to get available pages.`),
+        bringToFront: zod
+            .boolean()
+            .optional()
+            .describe('Whether to focus the page and bring it to the top.'),
     },
     handler: async (request, response, context) => {
         const page = context.getPageByIdx(request.params.pageIdx);
-        await page.bringToFront();
         context.selectPage(page);
+        if (request.params.bringToFront) {
+            await page.bringToFront();
+        }
         response.setIncludePages(true);
     },
 });

package/build/src/tools/webmcp.js

@@ -7,153 +7,85 @@ import { zod } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 /**
- * List all MCP tools available on a webpage.
- * Auto-connects to WebMCP if not already connected.
+ * Show all WebMCP tools registered across all pages, with diff since last call.
+ * First call returns full list. Subsequent calls return only added/removed tools.
  */
-export const listWebMCPTools = defineTool({
-    name: 'list_webmcp_tools',
-    description: 'List all MCP tools available on a webpage. ' +
-        'Automatically connects to WebMCP if the page has @mcp-b/global loaded. ' +
-        'Use page_index to target a specific page (see list_pages for indices).',
+export const diffWebMCPTools = defineTool({
+    name: 'diff_webmcp_tools',
+    description: 'Show all WebMCP tools registered across all pages, with diff since last call. ' +
+        'First call returns full list. Subsequent calls return only added/removed tools. ' +
+        'Use full=true to force complete list. ' +
+        'Tools are shown with their callable names (e.g., webmcp_localhost_3000_page0_test_add). ' +
+        'Call these tools directly by name instead of using a separate call tool.',
     annotations: {
-        title: 'List Website MCP Tools',
+        title: 'Diff Website MCP Tools',
         category: ToolCategory.WEBMCP,
         readOnlyHint: true,
     },
     schema: {
-        page_index: zod
-            .number()
-            .int()
+        full: zod
+            .boolean()
             .optional()
-            .describe('Index of the page to list tools from. If not specified, uses the currently selected page. ' +
-            'Use list_pages to see available pages and their indices.'),
+            .describe('Force full tool list instead of diff. Default: false'),
     },
     handler: async (request, response, context) => {
-        const { page_index } = request.params;
-        // Get the target page
-        const page = page_index !== undefined
-            ? context.getPageByIdx(page_index)
-            : context.getSelectedPage();
-        // Get client from context (handles auto-connect and stale connection detection)
-        const result = await context.getWebMCPClient(page);
-        if (!result.connected) {
-            response.appendResponseLine(result.error || 'No WebMCP tools available on this page.');
+        const { full } = request.params;
+        const toolHub = context.getToolHub();
+        if (!toolHub) {
+            response.appendResponseLine('WebMCPToolHub not initialized.');
             return;
         }
-        const client = result.client;
-        try {
-            const { tools } = await client.listTools();
-            if (page_index !== undefined) {
-                response.appendResponseLine(`Page ${page_index}: ${page.url()}`);
-                response.appendResponseLine('');
+        const tools = toolHub.getRegisteredTools();
+        const currentToolIds = new Set(tools.map(t => t.toolId));
+        const lastSeen = toolHub.getLastSeenToolIds();
+        // First call or full=true: return full list
+        if (!lastSeen || full) {
+            toolHub.setLastSeenToolIds(currentToolIds);
+            if (tools.length === 0) {
+                response.appendResponseLine('No WebMCP tools registered.');
+                response.appendResponseLine('Navigate to a page with @mcp-b/global loaded to discover tools.');
+                return;
             }
-            response.appendResponseLine(`${tools.length} tool(s) available:`);
+            response.appendResponseLine(`${tools.length} WebMCP tool(s) registered:`);
             response.appendResponseLine('');
             for (const tool of tools) {
-                response.appendResponseLine(`- ${tool.name}`);
+                response.appendResponseLine(`- ${tool.toolId}`);
+                response.appendResponseLine(`  Original: ${tool.originalName}`);
+                response.appendResponseLine(`  Domain: ${tool.domain} (page ${tool.pageIdx})`);
                 if (tool.description) {
                     response.appendResponseLine(`  Description: ${tool.description}`);
                 }
-                if (tool.inputSchema) {
-                    const schemaStr = JSON.stringify(tool.inputSchema, null, 2);
-                    // Only show schema if it's not too long
-                    if (schemaStr.length < 500) {
-                        response.appendResponseLine(`  Input Schema: ${schemaStr}`);
-                    }
-                    else {
-                        response.appendResponseLine(`  Input Schema: (complex schema, ${schemaStr.length} chars)`);
-                    }
-                }
                 response.appendResponseLine('');
             }
-        }
-        catch (err) {
-            response.appendResponseLine(`Failed to list tools: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    },
-});
-/**
- * Call a tool registered on a webpage via WebMCP.
- * Auto-connects to WebMCP if not already connected.
- */
-export const callWebMCPTool = defineTool({
-    name: 'call_webmcp_tool',
-    description: 'Call a tool registered on a webpage via WebMCP. ' +
-        'Automatically connects if the page has @mcp-b/global loaded. ' +
-        'Use list_webmcp_tools to see available tools and their schemas. ' +
-        'Use page_index to target a specific page.',
-    annotations: {
-        title: 'Call Website MCP Tool',
-        category: ToolCategory.WEBMCP,
-        readOnlyHint: false, // Tools may have side effects
-    },
-    schema: {
-        name: zod.string().describe('The name of the tool to call'),
-        arguments: zod
-            .record(zod.any())
-            .optional()
-            .describe('Arguments to pass to the tool as a JSON object'),
-        page_index: zod
-            .number()
-            .int()
-            .optional()
-            .describe('Index of the page to call the tool on. If not specified, uses the currently selected page. ' +
-            'Use list_pages to see available pages and their indices.'),
-    },
-    handler: async (request, response, context) => {
-        const { name, arguments: args, page_index } = request.params;
-        // Get the target page
-        const page = page_index !== undefined
-            ? context.getPageByIdx(page_index)
-            : context.getSelectedPage();
-        // Get client from context (handles auto-connect and stale connection detection)
-        const result = await context.getWebMCPClient(page);
-        if (!result.connected) {
-            response.appendResponseLine(result.error || 'No WebMCP tools available on this page.');
             return;
         }
-        const client = result.client;
-        try {
-            if (page_index !== undefined) {
-                response.appendResponseLine(`Page ${page_index}: ${page.url()}`);
-            }
-            response.appendResponseLine(`Calling tool: ${name}`);
-            if (args && Object.keys(args).length > 0) {
-                response.appendResponseLine(`Arguments: ${JSON.stringify(args)}`);
+        // Subsequent calls: return diff
+        const added = tools.filter(t => !lastSeen.has(t.toolId));
+        const removed = [...lastSeen].filter(id => !currentToolIds.has(id));
+        toolHub.setLastSeenToolIds(currentToolIds);
+        if (added.length === 0 && removed.length === 0) {
+            response.appendResponseLine('No changes since last poll.');
+            if (tools.length > 0) {
+                const toolNames = tools.map(t => t.originalName).join(', ');
+                response.appendResponseLine(`${tools.length} tools available: ${toolNames}`);
             }
-            response.appendResponseLine('');
-            const callResult = await client.callTool({
-                name,
-                arguments: args || {},
-            });
-            response.appendResponseLine('Result:');
-            // Format the result content
-            if (callResult.content && Array.isArray(callResult.content)) {
-                for (const content of callResult.content) {
-                    if (content.type === 'text') {
-                        response.appendResponseLine(content.text);
-                    }
-                    else if (content.type === 'image') {
-                        response.appendResponseLine(`[Image: ${content.mimeType}, ${content.data.length} bytes]`);
-                    }
-                    else if (content.type === 'resource') {
-                        response.appendResponseLine(`[Resource: ${JSON.stringify(content.resource)}]`);
-                    }
-                    else {
-                        response.appendResponseLine(JSON.stringify(content, null, 2));
-                    }
+            return;
+        }
+        if (added.length > 0) {
+            response.appendResponseLine(`Added (${added.length}):`);
+            for (const tool of added) {
+                response.appendResponseLine(`+ ${tool.toolId}`);
+                if (tool.description) {
+                    response.appendResponseLine(`  ${tool.description}`);
                 }
             }
-            else {
-                response.appendResponseLine(JSON.stringify(callResult, null, 2));
-            }
-            if (callResult.isError) {
-                response.appendResponseLine('');
-                response.appendResponseLine('(Tool returned an error)');
-            }
+            response.appendResponseLine('');
         }
-        catch (err) {
-            response.appendResponseLine(`Failed to call tool: ${err instanceof Error ? err.message : String(err)}`);
+        if (removed.length > 0) {
+            response.appendResponseLine(`Removed (${removed.length}):`);
+            for (const id of removed) {
+                response.appendResponseLine(`- ${id}`);
+            }
         }
     },
 });