execute_javascript

Instructions

Implementation Reference

• src/tools/devtools-console.ts:30-57 (handler)

  Handler function that defines the 'execute_javascript' MCP tool. It accepts a JavaScript expression, sends it via WebSocket bridge to a Chrome extension which executes it in the page context, and returns the result. Handles both success and JavaScript exception details.

  server.tool(
    'execute_javascript',
    'Run ANY JavaScript code directly in the page. This is your escape hatch for anything the other tools can\'t do: extract data, modify the page, trigger events, check values, etc. Full access to window, document, and all page APIs.',
    {
      expression: z.string().describe('JavaScript code to run. Can be a simple expression or multi-line function.'),
      tabId: z.number().optional().describe('Target tab ID (defaults to active tab)'),
      apiKey: z.string().optional().describe('API key for authentication if enabled'),
    },
    async ({ expression, tabId, apiKey }) => {
      const result = await bridge.sendCommand({
        command: 'execute_javascript',
        params: { expression },
        tabId,
        apiKey,
      });
      if (!result.success) {
        return { content: [{ type: 'text', text: `Error: ${result.error?.message}` }], isError: true };
      }
      const data = result.data as { result: unknown; exceptionDetails?: unknown };
      if (data.exceptionDetails) {
        return {
          content: [{ type: 'text', text: `JavaScript exception: ${JSON.stringify(data.exceptionDetails, null, 2)}` }],
          isError: true,
        };
      }
      return { content: [{ type: 'text', text: JSON.stringify(data.result, null, 2) }] };
    }
  );

• src/tools/devtools-console.ts:33-37 (schema)

  Zod schema for the 'execute_javascript' tool parameters: 'expression' (required string), 'tabId' (optional number), and 'apiKey' (optional string).

  {
    expression: z.string().describe('JavaScript code to run. Can be a simple expression or multi-line function.'),
    tabId: z.number().optional().describe('Target tab ID (defaults to active tab)'),
    apiKey: z.string().optional().describe('API key for authentication if enabled'),
  },

• src/tools/devtools-console.ts:5-58 (registration)

  Registration function 'registerDevtoolsConsoleTools' that registers the 'execute_javascript' tool (along with 'get_console_logs') on the MCP server. Called from src/tools/index.ts line 43.

  export function registerDevtoolsConsoleTools(server: McpServer, bridge: WebSocketBridge) {
    server.tool(
      'get_console_logs',
      'Get all console messages from the page (console.log, console.error, warnings, etc.). Use this to debug JavaScript errors, see what the page is logging, or verify your code is running.',
      {
        level: z.enum(['log', 'warn', 'error', 'info', 'debug', 'all']).optional()
          .describe('Filter logs: "error" for errors only, "warn" for warnings, "all" for everything (default)'),
        clear: z.boolean().optional().describe('Clear all logs after reading so you only get new messages next time'),
        tabId: z.number().optional().describe('Target tab ID (defaults to active tab)'),
        apiKey: z.string().optional().describe('API key for authentication if enabled'),
      },
      async ({ level, clear, tabId, apiKey }) => {
        const result = await bridge.sendCommand({
          command: 'get_console_logs',
          params: { level, clear },
          tabId,
          apiKey,
        });
        if (!result.success) {
          return { content: [{ type: 'text', text: `Error: ${result.error?.message}` }], isError: true };
        }
        return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
      }
    );
  
    server.tool(
      'execute_javascript',
      'Run ANY JavaScript code directly in the page. This is your escape hatch for anything the other tools can\'t do: extract data, modify the page, trigger events, check values, etc. Full access to window, document, and all page APIs.',
      {
        expression: z.string().describe('JavaScript code to run. Can be a simple expression or multi-line function.'),
        tabId: z.number().optional().describe('Target tab ID (defaults to active tab)'),
        apiKey: z.string().optional().describe('API key for authentication if enabled'),
      },
      async ({ expression, tabId, apiKey }) => {
        const result = await bridge.sendCommand({
          command: 'execute_javascript',
          params: { expression },
          tabId,
          apiKey,
        });
        if (!result.success) {
          return { content: [{ type: 'text', text: `Error: ${result.error?.message}` }], isError: true };
        }
        const data = result.data as { result: unknown; exceptionDetails?: unknown };
        if (data.exceptionDetails) {
          return {
            content: [{ type: 'text', text: `JavaScript exception: ${JSON.stringify(data.exceptionDetails, null, 2)}` }],
            isError: true,
          };
        }
        return { content: [{ type: 'text', text: JSON.stringify(data.result, null, 2) }] };
      }
    );
  }

• src/websocket-bridge.ts:63-103 (helper)

  WebSocketBridge.sendCommand() - the helper that sends the 'execute_javascript' command over WebSocket to the Chrome extension, with timeout handling and response resolution.

  async sendCommand(cmd: BridgeCommand): Promise<BridgeResponse> {
    if (!this.isConnected()) {
      return {
        success: false,
        error: {
          code: 'NOT_CONNECTED',
          message: 'Chrome extension is not connected. Ensure the extension is installed, enabled, and the browser is running.',
        },
      };
    }
  
    const id = crypto.randomUUID();
    const timeout = cmd.timeout ?? DEFAULT_TIMEOUT;
  
    return new Promise<BridgeResponse>((resolve, reject) => {
      const timer = setTimeout(() => {
        this.pending.delete(id);
        resolve({
          success: false,
          error: {
            code: 'TIMEOUT',
            message: `Command '${cmd.command}' timed out after ${timeout}ms`,
          },
        });
      }, timeout);
  
      this.pending.set(id, { resolve, reject, timer });
  
      const message = {
        id,
        type: 'request',
        command: cmd.command,
        params: cmd.params,
        tabId: cmd.tabId,
        apiKey: cmd.apiKey,
        timestamp: Date.now(),
      };
  
      this.client!.send(JSON.stringify(message));
    });
  }