feat: add 13 JavaScript Debugger tools via CDP Debugger domain

Add full debugger capabilities: enable/disable, breakpoints (set/remove/list),
pause state inspection, stepping (over/into/out), call frame evaluation,
script source retrieval, and script listing.

New file: src/tools/debugger.ts
Modified: McpPage (per-page debugger state + CDP event listeners),
McpContext (13 debugger method implementations),
ToolDefinition (Context interface extension),
tools.ts (tool registration), types.ts (debugger interfaces)

Author: soul-cat

src/McpContext.ts

@@ -1126,4 +1126,135 @@ export class McpContext implements Context {
   getExtension(id: string): InstalledExtension | undefined {
     return this.#extensionRegistry.getById(id);
   }
+
+  // ── Debugger methods ──
+  async enableDebugger(targetPage?: Page): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    await mcpPage.enableDebugger();
+  }
+
+  async disableDebugger(targetPage?: Page): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    await mcpPage.disableDebugger();
+  }
+
+  isDebuggerEnabled(targetPage?: Page): boolean {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#mcpPages.get(page);
+    return mcpPage?.debuggerState.enabled ?? false;
+  }
+  getDebuggerPausedState(targetPage?: Page) {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    return mcpPage.debuggerState.paused;
+  }
+  getDebuggerScripts(targetPage?: Page) {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    return [...mcpPage.debuggerState.scripts.values()];
+  }
+  getBreakpoints(targetPage?: Page) {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    return [...mcpPage.debuggerState.breakpoints.values()];
+  }
+  async setBreakpoint(
+    targetPage: Page | undefined,
+    url: string,
+    lineNumber: number,
+    columnNumber?: number,
+    condition?: string,
+  ) {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    const result = await session.send('Debugger.setBreakpointByUrl', {
+      urlRegex: url.replace(/[.*+?^$()|[\]\\]/g, '\\$&'),
+      lineNumber,
+      columnNumber,
+      condition,
+    });
+    const info = {
+      breakpointId: result.breakpointId,
+      url,
+      lineNumber,
+      columnNumber,
+      condition,
+      locations: (result.locations ?? []).map(loc => ({
+        scriptId: loc.scriptId,
+        lineNumber: loc.lineNumber,
+        columnNumber: loc.columnNumber ?? 0,
+      })),
+    };
+    mcpPage.debuggerState.breakpoints.set(info.breakpointId, info);
+    return info;
+  }
+  async removeBreakpoint(
+    targetPage: Page | undefined,
+    breakpointId: string,
+  ): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    await session.send('Debugger.removeBreakpoint', {breakpointId});
+    mcpPage.debuggerState.breakpoints.delete(breakpointId);
+  }
+  async resumeDebugger(targetPage?: Page): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    await session.send('Debugger.resume');
+  }
+  async stepOver(targetPage?: Page): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    await session.send('Debugger.stepOver');
+  }
+  async stepInto(targetPage?: Page): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    await session.send('Debugger.stepInto');
+  }
+  async stepOut(targetPage?: Page): Promise<void> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    await session.send('Debugger.stepOut');
+  }
+  async evaluateOnCallFrame(
+    targetPage: Page | undefined,
+    callFrameId: string,
+    expression: string,
+  ): Promise<string> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    const result = await session.send(
+      'Debugger.evaluateOnCallFrame',
+      {callFrameId, expression, returnByValue: true},
+    );
+    const remoteObj = result.result;
+    if (remoteObj.type === 'undefined') return 'undefined';
+    if (remoteObj.value !== undefined) {
+      return JSON.stringify(remoteObj.value);
+    }
+    return remoteObj.description ?? String(remoteObj.type);
+  }
+  async getScriptSource(
+    targetPage: Page | undefined,
+    scriptId: string,
+  ): Promise<string> {
+    const page = targetPage ?? this.getSelectedPage();
+    const mcpPage = this.#getMcpPage(page);
+    const session = mcpPage.getCdpSession();
+    const result = await session.send(
+      'Debugger.getScriptSource',
+      {scriptId},
+    );
+    return result.scriptSource;
+  }
 }

src/McpPage.ts

@@ -4,8 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type {Dialog, Page, Viewport} from './third_party/index.js';
+import type {CDPSession, Dialog, Page, Protocol, Viewport} from './third_party/index.js';
 import type {
+  DebuggerBreakpointInfo,
+  DebuggerPausedState,
+  DebuggerScriptInfo,
+  DebuggerState,
   EmulationSettings,
   GeolocationOptions,
   TextSnapshot,
@@ -34,6 +38,86 @@ export class McpPage {
   isolatedContextName?: string;
   devToolsPage?: Page;
 
+  // Debugger
+  debuggerState: DebuggerState = {
+    enabled: false,
+    paused: null,
+    breakpoints: new Map(),
+    scripts: new Map(),
+  };
+  #cdpSession: CDPSession | null = null;
+
+  async enableDebugger(): Promise<void> {
+    if (this.debuggerState.enabled) return;
+    // @ts-expect-error internal Puppeteer API
+    const session = this.page._client() as CDPSession;
+    this.#cdpSession = session;
+    session.on('Debugger.paused', this.#onDebuggerPaused);
+    session.on('Debugger.resumed', this.#onDebuggerResumed);
+    session.on('Debugger.scriptParsed', this.#onScriptParsed);
+    await session.send('Debugger.enable');
+    this.debuggerState.enabled = true;
+  }
+
+  async disableDebugger(): Promise<void> {
+    if (!this.debuggerState.enabled || !this.#cdpSession) return;
+    this.#cdpSession.off('Debugger.paused', this.#onDebuggerPaused);
+    this.#cdpSession.off('Debugger.resumed', this.#onDebuggerResumed);
+    this.#cdpSession.off('Debugger.scriptParsed', this.#onScriptParsed);
+    await this.#cdpSession.send('Debugger.disable');
+    this.debuggerState = {
+      enabled: false,
+      paused: null,
+      breakpoints: new Map(),
+      scripts: new Map(),
+    };
+    this.#cdpSession = null;
+  }
+
+  getCdpSession(): CDPSession {
+    if (!this.#cdpSession) {
+      throw new Error('Debugger is not enabled. Call debugger_enable first.');
+    }
+    return this.#cdpSession;
+  }
+  #onDebuggerPaused = (params: Protocol.Debugger.PausedEvent): void => {
+    const callFrames = params.callFrames.map(frame => ({
+      callFrameId: frame.callFrameId,
+      functionName: frame.functionName,
+      url: frame.url ?? '',
+      lineNumber: frame.location.lineNumber ?? 0,
+      columnNumber: frame.location.columnNumber ?? 0,
+      scopeChain: frame.scopeChain.map(scope => ({
+        type: scope.type,
+        name: scope.name,
+        objectId: scope.object.objectId,
+      })),
+    }));
+    this.debuggerState.paused = {
+      callFrames,
+      reason: params.reason ?? 'unknown',
+      hitBreakpoints: params.hitBreakpoints,
+    };
+  };
+  #onDebuggerResumed = (): void => {
+    this.debuggerState.paused = null;
+  };
+
+  #onScriptParsed = (params: Protocol.Debugger.ScriptParsedEvent): void => {
+    const scriptId = params.scriptId;
+    const url = params.url ?? '';
+    if (!url) return;
+    this.debuggerState.scripts.set(scriptId, {
+      scriptId,
+      url,
+      startLine: params.startLine ?? 0,
+      startColumn: params.startColumn ?? 0,
+      endLine: params.endLine ?? 0,
+      endColumn: params.endColumn ?? 0,
+      sourceMapURL: params.sourceMapURL,
+    });
+  };
+
   // Dialog
   #dialog?: Dialog;
   #dialogHandler: (dialog: Dialog) => void;
@@ -81,5 +165,6 @@ export class McpPage {
 
   dispose(): void {
     this.page.off('dialog', this.#dialogHandler);
+    void this.disableDebugger().catch(() => {});
   }
 }

src/tools/ToolDefinition.ts

@@ -14,7 +14,13 @@ import type {
   Viewport,
 } from '../third_party/index.js';
 import type {InsightName, TraceResult} from '../trace-processing/parse.js';
-import type {TextSnapshotNode, GeolocationOptions} from '../types.js';
+import type {
+  TextSnapshotNode,
+  GeolocationOptions,
+  DebuggerPausedState,
+  DebuggerBreakpointInfo,
+  DebuggerScriptInfo,
+} from '../types.js';
 import type {InstalledExtension} from '../utils/ExtensionRegistry.js';
 import type {PaginationOptions} from '../utils/types.js';
 
@@ -189,6 +195,31 @@ export type Context = Readonly<{
   uninstallExtension(id: string): Promise<void>;
   listExtensions(): InstalledExtension[];
   getExtension(id: string): InstalledExtension | undefined;
+  // Debugger
+  enableDebugger(page: Page): Promise<void>;
+  disableDebugger(page: Page): Promise<void>;
+  isDebuggerEnabled(page: Page): boolean;
+  getDebuggerPausedState(page: Page): DebuggerPausedState | null;
+  setBreakpoint(
+    page: Page,
+    url: string,
+    lineNumber: number,
+    columnNumber?: number,
+    condition?: string,
+  ): Promise<DebuggerBreakpointInfo>;
+  removeBreakpoint(page: Page, breakpointId: string): Promise<void>;
+  getBreakpoints(page: Page): DebuggerBreakpointInfo[];
+  resumeDebugger(page: Page): Promise<void>;
+  stepOver(page: Page): Promise<void>;
+  stepInto(page: Page): Promise<void>;
+  stepOut(page: Page): Promise<void>;
+  evaluateOnCallFrame(
+    page: Page,
+    callFrameId: string,
+    expression: string,
+  ): Promise<string>;
+  getScriptSource(page: Page, scriptId: string): Promise<string>;
+  getDebuggerScripts(page: Page): DebuggerScriptInfo[];
 }>;
 
 export function defineTool<Schema extends zod.ZodRawShape>(