chrome-debugger-mcp 1.0.0

package/dist/chrome-manager.d.ts

@@ -0,0 +1,167 @@
+import { CallFrame, ChromeTarget } from "chrome-remote-interface";
+export interface PauseInfo {
+    reason: string;
+    callFrames: CallFrame[];
+    hitBreakpoints?: string[];
+}
+export interface VariableInfo {
+    name: string;
+    value: string;
+    type: string;
+    subtype?: string;
+    structuredValue?: unknown;
+}
+export interface ScopeGroup {
+    type: string;
+    name?: string;
+    variables: VariableInfo[];
+}
+export interface DebuggerStatus {
+    connected: boolean;
+    paused: boolean;
+    pauseReason?: string;
+    hitBreakpoints?: string[];
+    callStack?: Array<{
+        index: number;
+        functionName: string;
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+    }>;
+}
+export type PauseListener = (info: PauseInfo) => void;
+export declare class ChromeDebuggerManager {
+    private client;
+    private pauseInfo;
+    private pauseWaiters;
+    private pauseListeners;
+    private connected;
+    private connectedTargetUrl;
+    /** Whether a reloadPage() is in progress – avoids treating that load as "resumed" unexpectedly */
+    private reloading;
+    private reloadResetTimer;
+    get isConnected(): boolean;
+    get isPaused(): boolean;
+    get currentPauseInfo(): PauseInfo | null;
+    onPause(listener: PauseListener): void;
+    /** Probe whether Chrome's CDP HTTP endpoint is responding on the given port. */
+    isDebugPortAlive(port?: number): Promise<boolean>;
+    /** Return the Chrome executable path for the current OS. */
+    getChromePath(explicitPath?: string): string;
+    /**
+     * Launch Chrome with remote debugging enabled (dual-instance via --user-data-dir).
+     * If Chrome is already listening on the port, skips launch.
+     * dryRun=true only returns the command without executing.
+     * openDevTools=true adds --auto-open-devtools-for-tabs so DevTools opens automatically.
+     */
+    launchChrome(options?: {
+        port?: number;
+        userDataDir?: string;
+        dryRun?: boolean;
+        url?: string;
+        openDevTools?: boolean;
+        chromePath?: string;
+    }): Promise<{
+        command: string;
+        alreadyRunning: boolean;
+        launched: boolean;
+        message: string;
+        requiresManualLaunch?: boolean;
+    }>;
+    /** List all available Chrome tabs/targets on the given port. */
+    listTargets(port?: number): Promise<ChromeTarget[]>;
+    /**
+     * Connect to Chrome.
+     * @param port   Remote debugging port (default 9222).
+     * @param targetUrlFilter  A substring of the tab URL/title to connect to (e.g. "localhost:8080").
+     *                         Required when multiple page tabs are available.
+     */
+    connect(port?: number, targetUrlFilter?: string): Promise<string>;
+    disconnect(): Promise<void>;
+    /** Reload the page via CDP (more reliable than manual browser refresh). */
+    reloadPage(ignoreCache?: boolean): Promise<string>;
+    setBreakpoint(url: string, lineNumber: number, columnNumber?: number, condition?: string): Promise<{
+        breakpointId: string;
+        locations: any[];
+        pending: boolean;
+        hint?: string;
+    }>;
+    removeBreakpoint(breakpointId: string): Promise<void>;
+    /** Non-blocking status check – returns immediately with current state. */
+    getStatus(): DebuggerStatus & {
+        targetUrl?: string;
+    };
+    /**
+     * Wait up to `timeoutMs` for the debugger to pause.
+     *
+     * NOTE: MCP Inspector has a built-in request timeout (default ~10 s).
+     * If you see a -32001 timeout from Inspector, either:
+     *   1. Increase Inspector timeout in its UI to ≥ 60000
+     *   2. Use a shorter timeout here and retry with polling via getStatus()
+     */
+    waitForPause(timeoutMs?: number): Promise<PauseInfo>;
+    /**
+     * Wait for the NEXT debugger pause, then check whether it matches the target location.
+     *
+     * ⚠️ No auto-resume: execution stays paused after this returns, regardless of whether
+     * the pause matched. The caller (AI) decides what to do next:
+     *   - matched=true  → call getScopeVariables() / evaluate() to read variables
+     *   - matched=false → call resume() explicitly, then waitForSpecificPause() again if needed
+     *
+     * Matching uses two tiers:
+     *   Tier 1 (exact):    URL contains urlFragment AND |compiledLine - expectedLine| <= lineTolerance
+     *   Tier 2 (semantic): URL contains urlFragment AND reason === "debugger-statement"
+     *     CDP reports compiled line numbers; for transpiled/bundled code the line may differ
+     *     from source, but reason="debugger-statement" is a reliable signal that it IS the
+     *     debugger; statement we inserted.
+     *
+     * @param urlFragment   Substring of the script URL where debugger; was added
+     * @param expectedLine  0-based line number (editor line N → pass N-1)
+     * @param timeoutMs     How long to wait for any pause (default 90 s)
+     * @param lineTolerance ±line tolerance for Tier 1 (default 10)
+     */
+    waitForSpecificPause(urlFragment: string, expectedLine: number, timeoutMs?: number, lineTolerance?: number): Promise<{
+        matched: boolean;
+        reason: string;
+        pausedUrl: string;
+        pausedLine: number;
+        functionName: string;
+        callStack: ReturnType<ChromeDebuggerManager["getCallStackSummary"]>;
+        lineMatchedByTolerance: boolean;
+        note: string;
+    }>;
+    getScopeVariables(frameIndex?: number): Promise<ScopeGroup[]>;
+    evaluate(expression: string, frameIndex?: number): Promise<{
+        result: any;
+        exceptionDetails?: any;
+    }>;
+    resume(): Promise<void>;
+    stepInto(timeoutMs?: number): Promise<PauseInfo>;
+    stepOver(timeoutMs?: number): Promise<PauseInfo>;
+    stepOut(timeoutMs?: number): Promise<PauseInfo>;
+    pause(): Promise<void>;
+    getCallStackSummary(): Array<{
+        index: number;
+        functionName: string;
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+    }>;
+    private getObjectProperties;
+    private formatProperty;
+    private primitiveValue;
+    private formatRemoteObject;
+    private toStructuredValue;
+    private childrenToArray;
+    private describeStructuredValue;
+    private beginReloadCycle;
+    private finishReloadCycle;
+    private createPauseWait;
+    private stepAndWait;
+    private removePauseWaiter;
+    private rejectPauseWaiters;
+    private resetConnectionState;
+    private ensureConnected;
+    private ensurePaused;
+}
+//# sourceMappingURL=chrome-manager.d.ts.map

package/dist/chrome-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome-manager.d.ts","sourceRoot":"","sources":["../src/chrome-manager.ts"],"names":[],"mappings":"AAAA,OAAY,EAER,SAAS,EAGT,YAAY,EACb,MAAM,yBAAyB,CAAC;AAyDjC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;AAYtD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,kBAAkB,CAAc;IACxC,kGAAkG;IAClG,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAA8C;IAEtE,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAEvC;IAED,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAMtC,gFAAgF;IAC1E,gBAAgB,CAAC,IAAI,GAAE,MAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAa7D,4DAA4D;IAC5D,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM;IAwB5C;;;;;OAKG;IACG,YAAY,CAChB,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KAChB,GACL,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,OAAO,CAAC;QACxB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IAmEF,gEAAgE;IAC1D,WAAW,CAAC,IAAI,GAAE,MAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI/D;;;;;OAKG;IACG,OAAO,CACX,IAAI,GAAE,MAAa,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC;IAqHZ,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBjC,2EAA2E;IACvE,UAAU,CAAC,WAAW,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAYzD,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;QACT,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,GAAG,EAAE,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IA0BI,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D,0EAA0E;IAC1E,SAAS,IAAI,cAAc,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAqBpD;;;;;;;OAOG;IACG,YAAY,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,SAAS,CAAC;IAYjE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,oBAAoB,CACxB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAc,EACzB,aAAa,GAAE,MAAW,GACzB,OAAO,CAAC;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,UAAU,CAAC,qBAAqB,CAAC,qBAAqB,CAAC,CAAC,CAAC;QACpE,sBAAsB,EAAE,OAAO,CAAC;QAChC,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IA6CI,iBAAiB,CAAC,UAAU,GAAE,MAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA6BhE,QAAQ,CACZ,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,MAAU,GACrB,OAAO,CAAC;QAAE,MAAM,EAAE,GAAG,CAAC;QAAC,gBAAgB,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;IA+B7C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAKvB,QAAQ,CAAC,SAAS,GAAE,MAAwB,GAAG,OAAO,CAAC,SAAS,CAAC;IASjE,QAAQ,CAAC,SAAS,GAAE,MAAwB,GAAG,OAAO,CAAC,SAAS,CAAC;IASjE,OAAO,CAAC,SAAS,GAAE,MAAwB,GAAG,OAAO,CAAC,SAAS,CAAC;IAShE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,mBAAmB,IAAI,KAAK,CAAC;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;YAaY,mBAAmB;YAqBnB,cAAc;IA2B5B,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,kBAAkB;YA0BZ,iBAAiB;IAkC/B,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,eAAe;YAgCT,WAAW;IAuBzB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,YAAY;CAQrB"}