@mehmoodqureshi/chrome-mcp 0.3.0 → 0.4.1

package/dist/src/executor/cdp-executor.js

@@ -26,6 +26,8 @@ const types_1 = require("./types");
 const SINGLETON_FILES = ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
 const STEALTH = `Object.defineProperty(navigator,'webdriver',{get:()=>undefined});`;
 const NON_CONTENT = /^(file|data|devtools|chrome|about):/i;
+/** Playwright errors that mean the page/context/browser died under us → DETACHED. */
+const CLOSED_TARGET = /Target closed|Browser has been closed|Target page, context or browser has been closed|Execution context was destroyed/i;
 /** Minimal CSS attribute-value escape for ref selectors (refs are `e\d+`, but be safe). */
 function cssEscape(s) {
     return s.replace(/["\\]/g, '\\$&');
@@ -250,6 +252,26 @@ class CdpExecutor {
         }
         throw new types_1.ExecutorError('SELECTOR_NOT_FOUND', 'provide a selector or a ref from snapshot()');
     }
+    /**
+     * Run a live-page operation, converting an opaque "target closed"/crashed
+     * error from Playwright into a clean DETACHED. On such a failure we also drop
+     * the cached context/tabs so the next call relaunches or reconnects cleanly.
+     * Any other error is rethrown unchanged.
+     */
+    async guard(fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (CLOSED_TARGET.test(msg)) {
+                this.context = null;
+                this.tabs.clear();
+                throw new types_1.ExecutorError('DETACHED', 'browser target closed or crashed; reconnect and retry');
+            }
+            throw err;
+        }
+    }
     // -- tabs ---------------------------------------------------------------
     async tabsList() {
         const ctx = await this.getContext();
@@ -284,107 +306,135 @@ class CdpExecutor {
         return w ?? 'load';
     }
     async navigate(args) {
-        const p = await this.resolveTab(args.tabId);
-        const resp = await p.goto(args.url, { waitUntil: this.toState(args.waitUntil) });
-        return { url: p.url(), title: await p.title().catch(() => ''), httpStatus: resp?.status() };
+        return this.guard(async () => {
+            const p = await this.resolveTab(args.tabId);
+            const resp = await p.goto(args.url, { waitUntil: this.toState(args.waitUntil) });
+            return { url: p.url(), title: await p.title().catch(() => ''), httpStatus: resp?.status() };
+        });
     }
     async back(tabId) {
-        const p = await this.resolveTab(tabId);
-        await p.goBack().catch(() => undefined);
-        return { url: p.url(), title: await p.title().catch(() => '') };
+        return this.guard(async () => {
+            const p = await this.resolveTab(tabId);
+            await p.goBack().catch(() => undefined);
+            return { url: p.url(), title: await p.title().catch(() => '') };
+        });
     }
     async forward(tabId) {
-        const p = await this.resolveTab(tabId);
-        await p.goForward().catch(() => undefined);
-        return { url: p.url(), title: await p.title().catch(() => '') };
+        return this.guard(async () => {
+            const p = await this.resolveTab(tabId);
+            await p.goForward().catch(() => undefined);
+            return { url: p.url(), title: await p.title().catch(() => '') };
+        });
     }
     async reload(args) {
-        const p = await this.resolveTab(args?.tabId);
-        await p.reload({ waitUntil: this.toState(args?.waitUntil) });
-        return { url: p.url(), title: await p.title().catch(() => '') };
+        return this.guard(async () => {
+            const p = await this.resolveTab(args?.tabId);
+            await p.reload({ waitUntil: this.toState(args?.waitUntil) });
+            return { url: p.url(), title: await p.title().catch(() => '') };
+        });
     }
     // -- interaction --------------------------------------------------------
     ok = { ok: true };
     async click(t, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        // Playwright already drives real (trusted) input, so `trusted` is a no-op here.
-        await this.locator(p, t).click({ button: opts?.button, clickCount: opts?.clickCount });
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            // Playwright already drives real (trusted) input, so `trusted` is a no-op here.
+            await this.locator(p, t).click({ button: opts?.button, clickCount: opts?.clickCount });
+            return this.ok;
+        });
     }
     async type(t, text, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        const loc = this.locator(p, t);
-        if (opts?.clear)
-            await loc.fill('');
-        if (opts?.keyEvents)
-            await loc.pressSequentially(text);
-        else
-            await loc.fill((opts?.clear ? '' : '') + text);
-        if (opts?.pressEnter)
-            await loc.press('Enter');
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            const loc = this.locator(p, t);
+            if (opts?.clear)
+                await loc.fill('');
+            if (opts?.keyEvents)
+                await loc.pressSequentially(text);
+            else
+                await loc.fill(text);
+            if (opts?.pressEnter)
+                await loc.press('Enter');
+            return this.ok;
+        });
     }
     async selectOption(t, values, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        // Try by value, then fall back to visible label.
-        const loc = this.locator(p, t);
-        try {
-            await loc.selectOption(values);
-        }
-        catch {
-            await loc.selectOption(values.map((label) => ({ label })));
-        }
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            // Try by value, then fall back to visible label.
+            const loc = this.locator(p, t);
+            try {
+                await loc.selectOption(values);
+            }
+            catch {
+                await loc.selectOption(values.map((label) => ({ label })));
+            }
+            return this.ok;
+        });
     }
     async fill(t, value, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        await this.locator(p, t).fill(value);
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            await this.locator(p, t).fill(value);
+            return this.ok;
+        });
     }
     async press(key, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        const combo = [...(opts?.modifiers ?? []), key].join('+');
-        await p.keyboard.press(combo);
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            const combo = [...(opts?.modifiers ?? []), key].join('+');
+            await p.keyboard.press(combo);
+            return this.ok;
+        });
     }
     async hover(t, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        await this.locator(p, t).hover();
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            await this.locator(p, t).hover();
+            return this.ok;
+        });
     }
     async scroll(opts) {
-        const p = await this.resolveTab(opts.tabId);
-        if (opts.target)
-            await this.locator(p, opts.target).scrollIntoViewIfNeeded();
-        else if (opts.x !== undefined || opts.y !== undefined)
-            await p.evaluate(([x, y]) => window.scrollTo(x ?? 0, y ?? 0), [opts.x, opts.y]);
-        else
-            await p.mouse.wheel(opts.deltaX ?? 0, opts.deltaY ?? 0);
-        return this.ok;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts.tabId);
+            if (opts.target)
+                await this.locator(p, opts.target).scrollIntoViewIfNeeded();
+            else if (opts.x !== undefined || opts.y !== undefined)
+                await p.evaluate(([x, y]) => window.scrollTo(x ?? 0, y ?? 0), [opts.x, opts.y]);
+            else
+                await p.mouse.wheel(opts.deltaX ?? 0, opts.deltaY ?? 0);
+            return this.ok;
+        });
     }
     // -- read ---------------------------------------------------------------
     async getText(t, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        const text = t ? await this.locator(p, t).innerText() : await p.locator('body').innerText();
-        return { text };
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            const text = t ? await this.locator(p, t).innerText() : await p.locator('body').innerText();
+            return { text };
+        });
     }
     async getHtml(t, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        if (!t)
-            return { html: await p.content() };
-        const loc = this.locator(p, t);
-        const html = opts?.outer ? await loc.evaluate((el) => el.outerHTML) : await loc.innerHTML();
-        return { html };
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            if (!t)
+                return { html: await p.content() };
+            const loc = this.locator(p, t);
+            const html = opts?.outer ? await loc.evaluate((el) => el.outerHTML) : await loc.innerHTML();
+            return { html };
+        });
     }
     async snapshot(opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        // Inject collectSnapshot's source and run it in the page (it can't close over module scope).
-        const raw = await p.evaluate(([fnSrc, interactiveOnly, max]) => {
-            // eslint-disable-next-line no-eval
-            const fn = (0, eval)(`(${fnSrc})`);
-            return fn(interactiveOnly, max);
-        }, [snapshot_1.collectSnapshot.toString(), opts?.interactiveOnly ?? true, opts?.max ?? 200]);
-        return raw;
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            // Inject collectSnapshot's source and run it in the page (it can't close over module scope).
+            const raw = await p.evaluate(([fnSrc, interactiveOnly, max]) => {
+                // eslint-disable-next-line no-eval
+                const fn = (0, eval)(`(${fnSrc})`);
+                return fn(interactiveOnly, max);
+            }, [snapshot_1.collectSnapshot.toString(), opts?.interactiveOnly ?? true, opts?.max ?? 200]);
+            return raw;
+        });
     }
     async getCookies(opts) {
         const p = await this.resolveTab(opts?.tabId);
@@ -399,69 +449,85 @@ class CdpExecutor {
         };
     }
     async storage(args) {
-        const p = await this.resolveTab(args.tabId);
-        return p.evaluate((a) => {
-            const store = a.session ? window.sessionStorage : window.localStorage;
-            if (a.op === 'set') {
-                store.setItem(String(a.key), String(a.value ?? ''));
-                return { ok: true };
-            }
-            if (a.op === 'remove') {
-                store.removeItem(String(a.key));
-                return { ok: true };
-            }
-            if (a.op === 'clear') {
-                store.clear();
-                return { ok: true };
-            }
-            if (a.key)
-                return { ok: true, value: store.getItem(a.key) };
-            const entries = {};
-            for (let i = 0; i < store.length; i++) {
-                const k = store.key(i);
-                if (k)
-                    entries[k] = store.getItem(k) ?? '';
-            }
-            return { ok: true, entries };
-        }, args);
+        return this.guard(async () => {
+            const p = await this.resolveTab(args.tabId);
+            return p.evaluate((a) => {
+                const store = a.session ? window.sessionStorage : window.localStorage;
+                if (a.op === 'set') {
+                    store.setItem(String(a.key), String(a.value ?? ''));
+                    return { ok: true };
+                }
+                if (a.op === 'remove') {
+                    store.removeItem(String(a.key));
+                    return { ok: true };
+                }
+                if (a.op === 'clear') {
+                    store.clear();
+                    return { ok: true };
+                }
+                if (a.key)
+                    return { ok: true, value: store.getItem(a.key) };
+                const entries = {};
+                for (let i = 0; i < store.length; i++) {
+                    const k = store.key(i);
+                    if (k)
+                        entries[k] = store.getItem(k) ?? '';
+                }
+                return { ok: true, entries };
+            }, args);
+        });
     }
     async screenshot(opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        const buf = opts?.target
-            ? await this.locator(p, opts.target).screenshot()
-            : await p.screenshot({ fullPage: opts?.fullPage });
-        const size = p.viewportSize() ?? { width: 0, height: 0 };
-        return { dataBase64: buf.toString('base64'), mimeType: 'image/png', width: size.width, height: size.height, truncated: false };
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            const buf = opts?.target
+                ? await this.locator(p, opts.target).screenshot()
+                : await p.screenshot({ fullPage: opts?.fullPage });
+            const size = p.viewportSize() ?? { width: 0, height: 0 };
+            return { dataBase64: buf.toString('base64'), mimeType: 'image/png', width: size.width, height: size.height, truncated: false };
+        });
     }
     async eval(expression, opts) {
-        const p = await this.resolveTab(opts?.tabId);
-        try {
-            const value = await p.evaluate((expr) => {
-                // eslint-disable-next-line no-eval
-                return (0, eval)(expr);
-            }, expression);
-            return { ok: true, value, type: typeof value };
-        }
-        catch (err) {
-            return { ok: false, error: err.message };
-        }
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            try {
+                const value = await p.evaluate((expr) => {
+                    // eslint-disable-next-line no-eval
+                    return (0, eval)(expr);
+                }, expression);
+                return (0, types_1.truncateEvalResult)({ ok: true, value, type: typeof value });
+            }
+            catch (err) {
+                const msg = err.message ?? '';
+                // A dead/crashed target must surface as DETACHED, not a swallowed EvalResult error.
+                if (CLOSED_TARGET.test(msg))
+                    throw err;
+                return { ok: false, error: msg };
+            }
+        });
     }
     async waitFor(opts) {
-        const p = await this.resolveTab(opts.tabId);
-        const timeout = opts.timeoutMs ?? 30_000;
-        const start = Date.now();
-        try {
-            if (opts.selector) {
-                await p.locator(opts.selector).first().waitFor({ state: opts.gone ? 'detached' : 'visible', timeout });
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts.tabId);
+            const timeout = opts.timeoutMs ?? 30_000;
+            const start = Date.now();
+            try {
+                if (opts.selector) {
+                    await p.locator(opts.selector).first().waitFor({ state: opts.gone ? 'detached' : 'visible', timeout });
+                }
+                else if (opts.textContains) {
+                    await p.waitForFunction((needle) => document.body?.innerText.includes(needle) ?? false, opts.textContains, { timeout });
+                }
+                return { matched: true, waitedMs: Date.now() - start };
             }
-            else if (opts.textContains) {
-                await p.waitForFunction((needle) => document.body?.innerText.includes(needle) ?? false, opts.textContains, { timeout });
+            catch (err) {
+                const msg = err.message ?? '';
+                // Crashed target must escalate to DETACHED; a plain timeout stays a non-match.
+                if (CLOSED_TARGET.test(msg))
+                    throw err;
+                return { matched: false, waitedMs: Date.now() - start };
             }
-            return { matched: true, waitedMs: Date.now() - start };
-        }
-        catch {
-            return { matched: false, waitedMs: Date.now() - start };
-        }
+        });
     }
     // -- privileged ---------------------------------------------------------
     async download(args) {
@@ -485,8 +551,43 @@ class CdpExecutor {
         if (!target)
             throw new types_1.ExecutorError('DOWNLOAD_FAILED', 'provide a url or a target');
         const [dl] = await Promise.all([p.waitForEvent('download'), this.locator(p, target).click()]);
-        await dl.saveAs(dest);
-        return { path: dest, backend: this.backend, bytes: 0, suggestedName: dl.suggestedFilename() };
+        let bytes = 0;
+        try {
+            // Surface a cancelled/interrupted download instead of reporting a phantom success.
+            const failure = await dl.failure();
+            if (failure)
+                throw new types_1.ExecutorError('DOWNLOAD_FAILED', `download failed: ${failure}`);
+            await dl.saveAs(dest);
+            bytes = (0, node_fs_1.statSync)(dest).size;
+        }
+        catch (err) {
+            if (err instanceof types_1.ExecutorError)
+                throw err;
+            throw new types_1.ExecutorError('DOWNLOAD_FAILED', `failed to save download: ${err.message}`);
+        }
+        return { path: dest, backend: this.backend, bytes, suggestedName: dl.suggestedFilename() };
+    }
+    async uploadFile(t, files, opts) {
+        return this.guard(async () => {
+            for (const f of files) {
+                try {
+                    (0, node_fs_1.statSync)(f);
+                }
+                catch {
+                    throw new types_1.ExecutorError('UPLOAD_FAILED', `file not found: ${f}`);
+                }
+            }
+            const p = await this.resolveTab(opts?.tabId);
+            try {
+                await this.locator(p, t).setInputFiles(files);
+            }
+            catch (err) {
+                if (err instanceof types_1.ExecutorError)
+                    throw err;
+                throw new types_1.ExecutorError('UPLOAD_FAILED', `could not set files on the input: ${err.message}`);
+            }
+            return this.ok;
+        });
     }
 }
 exports.CdpExecutor = CdpExecutor;

package/dist/src/executor/extension-executor.d.ts

@@ -122,4 +122,7 @@ export declare class ExtensionExecutor implements Executor {
         tabId?: TabId;
         suggestedName?: string;
     }): Promise<DownloadResult>;
+    uploadFile(t: Target, files: string[], opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
 }

package/dist/src/executor/extension-executor.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtensionExecutor = void 0;
+const types_1 = require("./types");
 /** Flatten a Target into the params a wire command carries. */
 function targetParams(t) {
     if (!t)
@@ -122,7 +123,8 @@ class ExtensionExecutor {
         return (await this.send('screenshot', { fullPage: opts?.fullPage, ...targetParams(opts?.target) }, { tabId: opts?.tabId }));
     }
     async eval(expression, opts) {
-        return (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise }, { tabId: opts?.tabId }));
+        const result = (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise }, { tabId: opts?.tabId }));
+        return (0, types_1.truncateEvalResult)(result);
     }
     async waitFor(opts) {
         return (await this.send('wait_for', { selector: opts.selector, textContains: opts.textContains, gone: opts.gone, timeoutMs: opts.timeoutMs }, { tabId: opts.tabId, timeoutMs: opts.timeoutMs ? opts.timeoutMs + 5_000 : undefined }));
@@ -131,6 +133,9 @@ class ExtensionExecutor {
     async download(args) {
         return (await this.send('download_file', { url: args.url, ...targetParams(args.target), suggestedName: args.suggestedName }, { tabId: args.tabId }));
     }
+    async uploadFile(t, files, opts) {
+        return (await this.send('upload_file', { ...targetParams(t), files }, { tabId: opts?.tabId }));
+    }
 }
 exports.ExtensionExecutor = ExtensionExecutor;
 //# sourceMappingURL=extension-executor.js.map

package/dist/src/executor/stub-executor.d.ts

@@ -66,4 +66,5 @@ export declare class StubExecutor implements Executor {
     download(args: {
         suggestedName?: string;
     }): Promise<DownloadResult>;
+    uploadFile(): Promise<ActionOk>;
 }

package/dist/src/executor/stub-executor.js

@@ -132,6 +132,9 @@ class StubExecutor {
             bytes: 0,
         };
     }
+    async uploadFile() {
+        return ok;
+    }
 }
 exports.StubExecutor = StubExecutor;
 //# sourceMappingURL=stub-executor.js.map

package/dist/src/executor/types.d.ts

@@ -50,7 +50,19 @@ export interface EvalResult {
     value?: unknown;
     type?: string;
     error?: string;
+    /** Set when `value` exceeded MAX_EVAL_BYTES and was replaced by a truncated JSON string. */
+    truncated?: boolean;
 }
+/** Hard cap on a serialized eval result before it is truncated (see `truncateEvalResult`). */
+export declare const MAX_EVAL_BYTES: number;
+/**
+ * Enforce the EvalResult size cap uniformly across backends. Attempts to
+ * JSON-serialize `value`; if the UTF-8 byte length exceeds MAX_EVAL_BYTES the
+ * value is replaced by the JSON sliced to the cap with a `...[truncated]`
+ * marker and `truncated: true` is set. Non-serializable values (stringify
+ * throws or yields undefined) are left untouched — this never throws.
+ */
+export declare function truncateEvalResult(result: EvalResult): EvalResult;
 export interface WaitResult {
     matched: boolean;
     ref?: string;
@@ -239,13 +251,22 @@ export interface Executor {
         tabId?: TabId;
         suggestedName?: string;
     }): Promise<DownloadResult>;
+    /**
+     * Set the files on a file `<input>` (target by selector or ref) from local
+     * absolute paths — the upload equivalent of a file-picker, without the OS
+     * dialog. Privileged: sends local files to the page, so it is gated by
+     * `allowUploads` and the destination domain allowlist.
+     */
+    uploadFile(t: Target, files: string[], opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
 }
 /**
  * Server-side executor error codes. A superset of the wire `ExecutorErrorCode`
  * (which only carries codes that originate inside the extension); these extra
  * codes describe failures on the server half (no backend, launch failed, etc.).
  */
-export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'BACKPRESSURE';
+export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'BACKPRESSURE';
 export declare class ExecutorError extends Error {
     readonly code: ExecutorErrorCodeLocal;
     constructor(code: ExecutorErrorCodeLocal, message: string);

package/dist/src/executor/types.js

@@ -11,7 +11,35 @@
  * `mcp/helpers.ts` from these primitives; only `download` is privileged.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExecutorError = void 0;
+exports.ExecutorError = exports.MAX_EVAL_BYTES = void 0;
+exports.truncateEvalResult = truncateEvalResult;
+/** Hard cap on a serialized eval result before it is truncated (see `truncateEvalResult`). */
+exports.MAX_EVAL_BYTES = 256 * 1024;
+/**
+ * Enforce the EvalResult size cap uniformly across backends. Attempts to
+ * JSON-serialize `value`; if the UTF-8 byte length exceeds MAX_EVAL_BYTES the
+ * value is replaced by the JSON sliced to the cap with a `...[truncated]`
+ * marker and `truncated: true` is set. Non-serializable values (stringify
+ * throws or yields undefined) are left untouched — this never throws.
+ */
+function truncateEvalResult(result) {
+    if (!result.ok || result.value === undefined)
+        return result;
+    let json;
+    try {
+        json = JSON.stringify(result.value);
+    }
+    catch {
+        return result; // not serializable — leave value as-is
+    }
+    if (json === undefined)
+        return result;
+    if (Buffer.byteLength(json, 'utf8') <= exports.MAX_EVAL_BYTES)
+        return result;
+    // Slice by bytes, then trim any partial trailing UTF-8 char before appending the marker.
+    const sliced = Buffer.from(json, 'utf8').subarray(0, exports.MAX_EVAL_BYTES).toString('utf8');
+    return { ...result, value: `${sliced}...[truncated]`, truncated: true };
+}
 class ExecutorError extends Error {
     code;
     constructor(code, message) {

package/dist/src/mcp/server.d.ts

@@ -10,9 +10,9 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 /** stderr only — never stdout in stdio mode. */
 export declare function logErr(message: string): void;
 /** Build a fresh `Server` with the full tool surface registered (no transport). */
-export declare function createServer(): Server;
+export declare function createServer(version?: string): Server;
 /** Start over stdio. Idempotent. */
-export declare function startMcpServer(): Promise<void>;
+export declare function startMcpServer(version?: string): Promise<void>;
 /** Stop and release the transport. Idempotent, best-effort. */
 export declare function stopMcpServer(): Promise<void>;
 export declare function isMcpServerRunning(): boolean;

package/dist/src/mcp/server.js

@@ -18,6 +18,8 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const tools_1 = require("./tools");
 const SERVER_NAME = 'chrome-mcp';
 const SERVER_VERSION = '0.1.0';
+/** Default version reported when no explicit version is passed in (legacy callers/tests). */
+const DEFAULT_VERSION = SERVER_VERSION;
 let server = null;
 let transport = null;
 /** stderr only — never stdout in stdio mode. */
@@ -25,8 +27,8 @@ function logErr(message) {
     process.stderr.write(`[chrome-mcp] ${message}\n`);
 }
 /** Build a fresh `Server` with the full tool surface registered (no transport). */
-function createServer() {
-    const srv = new index_js_1.Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+function createServer(version = DEFAULT_VERSION) {
+    const srv = new index_js_1.Server({ name: SERVER_NAME, version }, { capabilities: { tools: {} } });
     (0, tools_1.registerTools)(srv);
     srv.onerror = (err) => {
         logErr(`server error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
@@ -34,12 +36,12 @@ function createServer() {
     return srv;
 }
 /** Start over stdio. Idempotent. */
-async function startMcpServer() {
+async function startMcpServer(version = DEFAULT_VERSION) {
     if (server) {
         logErr('startMcpServer called but already running; ignoring.');
         return;
     }
-    const srv = createServer();
+    const srv = createServer(version);
     const tx = new stdio_js_1.StdioServerTransport();
     try {
         await srv.connect(tx);
@@ -52,7 +54,7 @@ async function startMcpServer() {
     }
     server = srv;
     transport = tx;
-    logErr(`${SERVER_NAME} v${SERVER_VERSION} connected over stdio.`);
+    logErr(`${SERVER_NAME} v${version} connected over stdio.`);
 }
 /** Stop and release the transport. Idempotent, best-effort. */
 async function stopMcpServer() {

package/dist/src/mcp/tools.d.ts

@@ -25,6 +25,8 @@ interface ToolCtx {
 }
 type ToolHandler = (args: Record<string, unknown>, ctx: ToolCtx) => Promise<CallToolResult>;
 export declare const TOOL_HANDLERS: Record<string, ToolHandler>;
+/** Reset limiter state — for tests that exercise the ceiling. */
+export declare function resetRateLimiter(): void;
 export declare function dispatchToolCall(name: string, rawArgs: unknown): Promise<CallToolResult>;
 /** Assert the catalog and the dispatch table describe the same tool set. */
 export declare function assertNoDrift(): void;