@browserless.io/mcp 1.7.1 → 1.8.0

package/build/src/lib/http-auth.d.ts

@@ -1,3 +1,4 @@
+import type { Context } from 'hono';
 import type { McpConfig } from '../@types/types.js';
 export interface ResolvedBrowserlessAuth {
     token: string;
@@ -20,3 +21,4 @@ export interface AuthInput {
  * callback and the custom `/upload` route so both gate on the same rules.
  */
 export declare const resolveBrowserlessAuth: (input: AuthInput, config: Pick<McpConfig, "browserlessApiUrl" | "supabaseUrl" | "supabaseServiceRoleKey">) => Promise<ResolvedBrowserlessAuth>;
+export declare const guardRouteAuth: (c: Context, config: Parameters<typeof resolveBrowserlessAuth>[1]) => Promise<Response | null>;

package/build/src/lib/http-auth.js

@@ -7,22 +7,22 @@ import { resolveApiKey } from './account-resolver.js';
  * callback and the custom `/upload` route so both gate on the same rules.
  */
 export const resolveBrowserlessAuth = async (input, config) => {
-    const headerToken = input.authHeader?.startsWith('Bearer ')
-        ? input.authHeader.slice(7)
-        : input.authHeader;
     const apiUrl = input.apiUrlHeader ?? input.browserlessUrlQuery ?? config.browserlessApiUrl;
     // A pre-created session id to attach to, threaded by the autologin runner.
     // The agent tool opens /chromium/agent?sessionId=<this> instead of doing its
     // own POST /profile.
-    const attachSessionId = input.sessionIdHeader ?? input.sessionIdQuery ?? undefined;
+    const attachSessionId = input.sessionIdHeader ?? input.sessionIdQuery;
+    const headerToken = input.authHeader?.startsWith('Bearer ')
+        ? input.authHeader.slice(7)
+        : input.authHeader;
     // JWTs have 3 dot-separated base64url segments; plain API keys do not.
     const isJwt = headerToken ? headerToken.split('.').length === 3 : false;
-    if (headerToken && !isJwt) {
-        return { token: headerToken, apiUrl, attachSessionId };
-    }
-    if (input.tokenQuery) {
-        return { token: input.tokenQuery, apiUrl, attachSessionId };
+    // A plain key (header or ?token=) is used directly and wins over JWT exchange.
+    const plainKey = (isJwt ? undefined : headerToken) ?? input.tokenQuery;
+    if (plainKey) {
+        return { token: plainKey, apiUrl, attachSessionId };
     }
+    // A JWT is exchanged for the account's Browserless API key via PostgREST.
     if (isJwt && headerToken) {
         const { apiKey } = await resolveApiKey(config.supabaseUrl, config.supabaseServiceRoleKey, headerToken);
         return { token: apiKey, apiUrl, attachSessionId };
@@ -31,3 +31,17 @@ export const resolveBrowserlessAuth = async (input, config) => {
         'Pass it as Authorization: Bearer <token> header, ' +
         '?token= query parameter, or authenticate via OAuth.');
 };
+export const guardRouteAuth = async (c, config) => {
+    try {
+        await resolveBrowserlessAuth({
+            authHeader: c.req.header('authorization'),
+            tokenQuery: c.req.query('token'),
+            apiUrlHeader: c.req.header('x-browserless-api-url'),
+            browserlessUrlQuery: c.req.query('browserlessUrl'),
+        }, config);
+        return null;
+    }
+    catch {
+        return c.json({ ok: false, error: 'Unauthorized' }, 401);
+    }
+};

package/build/src/lib/redis-oauth-proxy.d.ts

@@ -5,9 +5,8 @@ export declare class RedisOAuthProxy extends OAuthProxy {
     constructor(config: OAuthProxyConfig, redis: Redis);
     private get _internal();
     registerClient(request: DCRRequest): Promise<DCRResponse>;
-    private isClientRegistered;
+    private getClientRedirectUris;
     authorize(params: AuthorizationParams): Promise<Response>;
     handleCallback(request: Request): Promise<Response>;
     exchangeAuthorizationCode(request: TokenRequest): Promise<TokenResponse>;
-    destroy(): void;
 }

package/build/src/lib/redis-oauth-proxy.js

@@ -1,4 +1,4 @@
-import { OAuthProxy, OAuthProxyError, } from 'fastmcp/auth';
+import { OAuthProxy, OAuthProxyError, PKCEUtils, } from 'fastmcp/auth';
 /**
  * Redis-backed OAuthProxy using Redis as the single source of truth for OAuth
  * flow state (transactions, authorization codes, DCRs), so the steps of one
@@ -17,10 +17,11 @@ import { OAuthProxy, OAuthProxyError, } from 'fastmcp/auth';
 const KEY_PREFIX = 'mcp:oauth:';
 const TX_PREFIX = `${KEY_PREFIX}tx:`;
 const CODE_PREFIX = `${KEY_PREFIX}code:`;
-const CLIENT_PREFIX = `${KEY_PREFIX}client:`;
+const CLIENT_ID_PREFIX = `${KEY_PREFIX}client-id:`;
 const DEFAULT_TRANSACTION_TTL = 600;
 const DEFAULT_CODE_TTL = 300;
-const DEFAULT_CLIENT_TTL = 3600;
+// DCR clients are reused for weeks; a short TTL would expire one mid-life.
+const DEFAULT_CLIENT_TTL = 90 * 24 * 60 * 60;
 const DATE_FIELDS = new Set(['createdAt', 'expiresAt', 'issuedAt']);
 function serialize(obj) {
     return JSON.stringify(obj, (_key, value) => {
@@ -51,44 +52,25 @@ export class RedisOAuthProxy extends OAuthProxy {
         if (this.config.consentRequired) {
             throw new Error('RedisOAuthProxy requires consentRequired: false — consent flow is not supported in multi-instance mode');
         }
+        // We return upstream tokens directly (no token swap); fail fast otherwise.
+        if (this.config.enableTokenSwap) {
+            throw new Error('RedisOAuthProxy requires enableTokenSwap: false — token-swap mode is not supported');
+        }
     }
     get _internal() {
         return this;
     }
     async registerClient(request) {
-        // Delegate validation/response to the parent, then mirror the accepted
-        // URIs into Redis so every instance can honor the v4 redirect_uri check.
-        // (The parent's in-memory Map is also populated but we never read it.)
+        // Store the client's redirect_uris under the issued client_id so any
+        // instance can validate per-client (the parent's Map is process-local).
         const response = await super.registerClient(request);
         const ttl = this._internal.config.clientRegistrationTtl ?? DEFAULT_CLIENT_TTL;
-        // Snapshot pre-existence so rollback doesn't DEL a valid prior
-        // registration of the same URI (two DCR calls sharing a redirect_uri).
-        // allSettled → a probe failure is fail-fast with no writes attempted.
-        const probes = await Promise.allSettled(response.redirect_uris.map(async (uri) => ({
-            uri,
-            existed: (await this.redis.exists(`${CLIENT_PREFIX}${uri}`)) > 0,
-        })));
-        const probeFailed = probes.find((p) => p.status === 'rejected');
-        if (probeFailed) {
-            throw probeFailed.reason;
-        }
-        const redisPreExisting = new Set(probes
-            .filter((p) => p.status === 'fulfilled' && p.value.existed)
-            .map((p) => p.value.uri));
-        const writes = await Promise.allSettled(response.redirect_uris.map((uri) => this.redis.set(`${CLIENT_PREFIX}${uri}`, '1', 'EX', ttl)));
-        const writeFailed = writes.find((w) => w.status === 'rejected');
-        if (writeFailed) {
-            // Best-effort cleanup of Redis keys this call introduced; if these
-            // deletes also fail the originating error still wins.
-            await Promise.allSettled(response.redirect_uris
-                .filter((uri) => !redisPreExisting.has(uri))
-                .map((uri) => this.redis.del(`${CLIENT_PREFIX}${uri}`)));
-            throw writeFailed.reason;
-        }
+        await this.redis.set(`${CLIENT_ID_PREFIX}${response.client_id}`, JSON.stringify(response.redirect_uris), 'EX', ttl);
         return response;
     }
-    async isClientRegistered(uri) {
-        return (await this.redis.exists(`${CLIENT_PREFIX}${uri}`)) === 1;
+    async getClientRedirectUris(clientId) {
+        const json = await this.redis.get(`${CLIENT_ID_PREFIX}${clientId}`);
+        return json ? JSON.parse(json) : null;
     }
     async authorize(params) {
         if (!params.client_id || !params.redirect_uri || !params.response_type) {
@@ -97,15 +79,13 @@ export class RedisOAuthProxy extends OAuthProxy {
         if (params.response_type !== 'code') {
             throw new OAuthProxyError('unsupported_response_type', "Only 'code' response type is supported");
         }
-        // RFC 6749 §5.2 — reject any client_id other than the single upstream
-        // identity this proxy fronts. Ported from fastmcp v4 OAuthProxy.authorize.
-        if (params.client_id !== this._internal.config.upstreamClientId) {
+        // redirect_uri must be one registered for THIS client_id — a global check
+        // would let any client pair with any other's URI (CWE-601).
+        const registeredUris = await this.getClientRedirectUris(params.client_id);
+        if (!registeredUris) {
             throw new OAuthProxyError('invalid_client', 'Unknown client_id');
         }
-        // RFC 6749 §3.1.2.3 / RFC 6819 §4.1.5 — redirect_uri must be one
-        // previously registered via DCR; skipping this is CWE-601 (auth-code
-        // theft). We read the shared Redis registry so cross-instance DCR counts.
-        if (!(await this.isClientRegistered(params.redirect_uri))) {
+        if (!registeredUris.includes(params.redirect_uri)) {
             throw new OAuthProxyError('invalid_request', 'redirect_uri is not registered for this client');
         }
         if (params.code_challenge && !params.code_challenge_method) {
@@ -132,10 +112,10 @@ export class RedisOAuthProxy extends OAuthProxy {
             throw new OAuthProxyError('invalid_request', 'Invalid or expired state');
         }
         const transaction = deserialize(txJson);
-        // Defense-in-depth: reject if the transaction's stored callback URL is no
-        // longer registered. Guards against DCR revocation mid-flow and any path
-        // that could have persisted an unvalidated URI.
-        if (!(await this.isClientRegistered(transaction.clientCallbackUrl))) {
+        // Defense-in-depth: the callback URL must still be bound to this client
+        // (guards against mid-flow DCR revocation/expiry).
+        const txUris = await this.getClientRedirectUris(transaction.clientId);
+        if (!txUris || !txUris.includes(transaction.clientCallbackUrl)) {
             await this.redis.del(`${TX_PREFIX}${state}`);
             throw new OAuthProxyError('invalid_request', 'Transaction callback URL is not registered');
         }
@@ -144,11 +124,14 @@ export class RedisOAuthProxy extends OAuthProxy {
         // We read from it, persist to Redis, then clean up the Map entry.
         const clientCode = this._internal.generateAuthorizationCode(transaction, upstreamTokens);
         const codeData = this._internal.clientCodes.get(clientCode);
-        if (codeData) {
-            const codeTtl = this._internal.config.authorizationCodeTtl || DEFAULT_CODE_TTL;
-            await this.redis.set(`${CODE_PREFIX}${clientCode}`, serialize(codeData), 'EX', codeTtl);
-            this._internal.clientCodes.delete(clientCode);
-        }
+        // generateAuthorizationCode just populated the Map; if a cleanup race
+        // emptied it, fail loud rather than redirect with an unpersisted code.
+        if (!codeData) {
+            throw new OAuthProxyError('server_error', 'Failed to persist authorization code');
+        }
+        const codeTtl = this._internal.config.authorizationCodeTtl || DEFAULT_CODE_TTL;
+        await this.redis.set(`${CODE_PREFIX}${clientCode}`, serialize(codeData), 'EX', codeTtl);
+        this._internal.clientCodes.delete(clientCode);
         // Remove consumed transaction
         await this.redis.del(`${TX_PREFIX}${state}`);
         const redirectUrl = new URL(transaction.clientCallbackUrl);
@@ -163,10 +146,9 @@ export class RedisOAuthProxy extends OAuthProxy {
         if (request.grant_type !== 'authorization_code') {
             throw new OAuthProxyError('unsupported_grant_type', 'Only authorization_code grant type is supported');
         }
-        // RFC 6749 §5.2 — reject unknown clients at token exchange too, so a
-        // stolen authorization code cannot be redeemed by an arbitrary caller.
-        // Ported from fastmcp v4 OAuthProxy.exchangeAuthorizationCode.
-        if (request.client_id !== this._internal.config.upstreamClientId) {
+        // Reject unknown clients here too; the code↔client binding below enforces
+        // that only the owning client can redeem the code.
+        if (!(await this.getClientRedirectUris(request.client_id))) {
             throw new OAuthProxyError('invalid_client', 'Unknown client_id');
         }
         // Atomically read-and-delete the code. The parent's in-memory `used` flag
@@ -180,19 +162,15 @@ export class RedisOAuthProxy extends OAuthProxy {
         if (clientCode.clientId !== request.client_id) {
             throw new OAuthProxyError('invalid_client', 'Client ID mismatch');
         }
-        if (clientCode.codeChallenge && !request.code_verifier) {
-            throw new OAuthProxyError('invalid_request', 'code_verifier required for PKCE');
-        }
-        if (clientCode.codeChallenge && request.code_verifier) {
-            // Delegate PKCE validation to parent by placing code in Map temporarily.
-            // Redis key is already consumed by GETDEL above, so no additional del
-            // is needed in finally — only the local Map cleanup.
-            this._internal.clientCodes.set(request.code, clientCode);
-            try {
-                return await super.exchangeAuthorizationCode(request);
+        // PKCE inline, not via super (the parent re-checks client_id against a
+        // process-local Map). One-time-use is enforced by the GETDEL above, not the
+        // parent's `used` flag.
+        if (clientCode.codeChallenge) {
+            if (!request.code_verifier) {
+                throw new OAuthProxyError('invalid_request', 'code_verifier required for PKCE');
             }
-            finally {
-                this._internal.clientCodes.delete(request.code);
+            if (!PKCEUtils.validateChallenge(request.code_verifier, clientCode.codeChallenge, clientCode.codeChallengeMethod)) {
+                throw new OAuthProxyError('invalid_grant', 'Invalid PKCE verifier');
             }
         }
         const response = {
@@ -203,12 +181,12 @@ export class RedisOAuthProxy extends OAuthProxy {
         if (clientCode.upstreamTokens.refreshToken) {
             response.refresh_token = clientCode.upstreamTokens.refreshToken;
         }
+        if (clientCode.upstreamTokens.idToken) {
+            response.id_token = clientCode.upstreamTokens.idToken;
+        }
         if (clientCode.upstreamTokens.scope?.length > 0) {
             response.scope = clientCode.upstreamTokens.scope.join(' ');
         }
         return response;
     }
-    destroy() {
-        super.destroy();
-    }
 }

package/build/src/resources/download-route.js

@@ -1,6 +1,6 @@
 import { readFile, rm } from 'node:fs/promises';
 import { consumeDownload } from '../lib/download-store.js';
-import { resolveBrowserlessAuth } from '../lib/http-auth.js';
+import { guardRouteAuth } from '../lib/http-auth.js';
 /**
  * Registers `GET /download/:id` on the HTTP-stream server. getDownloads surfaces
  * a download as a notification (metadata only) plus this URL; the client fetches
@@ -17,17 +17,9 @@ import { resolveBrowserlessAuth } from '../lib/http-auth.js';
 export function registerDownloadRoute(server, config) {
     const app = server.getApp();
     app.get('/download/:id', async (c) => {
-        try {
-            await resolveBrowserlessAuth({
-                authHeader: c.req.header('authorization'),
-                tokenQuery: c.req.query('token'),
-                apiUrlHeader: c.req.header('x-browserless-api-url'),
-                browserlessUrlQuery: c.req.query('browserlessUrl'),
-            }, config);
-        }
-        catch {
-            return c.json({ ok: false, error: 'Unauthorized' }, 401);
-        }
+        const denied = await guardRouteAuth(c, config);
+        if (denied)
+            return denied;
         // Single-use: consume removes it from the registry so a second GET 404s.
         const record = consumeDownload(c.req.param('id'));
         if (!record) {

package/build/src/resources/upload-route.js

@@ -1,5 +1,5 @@
 import { downloadUri, storeDownload, FILE_TRANSFER_MAX_BYTES, } from '../lib/download-store.js';
-import { resolveBrowserlessAuth } from '../lib/http-auth.js';
+import { guardRouteAuth } from '../lib/http-auth.js';
 // Registers `POST /upload` (httpStream only): clients push a file's bytes over
 // plain HTTP and get back a handle to pass to the agent's `uploadFile`.
 //   curl -s -F file=@/path/to/file "<mcpBaseUrl>/upload?token=<token>"
@@ -7,19 +7,11 @@ import { resolveBrowserlessAuth } from '../lib/http-auth.js';
 export function registerUploadRoute(server, config) {
     const app = server.getApp();
     app.post('/upload', async (c) => {
-        // Raw Hono routes bypass FastMCP's authenticate, so gate the route on the
-        // same Browserless token rules as the MCP surface — no anonymous drops.
-        try {
-            await resolveBrowserlessAuth({
-                authHeader: c.req.header('authorization'),
-                tokenQuery: c.req.query('token'),
-                apiUrlHeader: c.req.header('x-browserless-api-url'),
-                browserlessUrlQuery: c.req.query('browserlessUrl'),
-            }, config);
-        }
-        catch {
-            return c.json({ ok: false, error: 'Unauthorized' }, 401);
-        }
+        // Raw Hono routes bypass FastMCP's authenticate, so gate on the same token
+        // rules as the MCP surface — no anonymous drops.
+        const denied = await guardRouteAuth(c, config);
+        if (denied)
+            return denied;
         let file;
         try {
             const body = await c.req.parseBody();

package/build/src/skills/file-transfers.md

@@ -22,6 +22,7 @@ Just trigger the download in the agent — navigate to the file URL, or click a
 - A short, size-scaled grace wait lets quick downloads land on the **same** call. A slower one shows up as **in-progress with a byte count** ("downloading 2.0MB / 10MB") — just keep using the browser; it'll appear completed on a later response. As long as you keep touching the browser, the download state stays fresh.
 - Files **larger than the cap** aren't transferred: you get a `FileTooLarge` note with the **source URL** — fetch it directly (e.g. `curl`) if you have network access.
 - You decide whether to save each file. (`getDownloads` still exists for an explicit poll, but it's rarely needed.)
+- A **screenshot** can be captured straight to disk with `screenshot { toDisk: true }` instead of returned inline — it then behaves exactly like a download here (same handle/path/URL, same reuse). See the **screenshots** skill.
 
 **Local (stdio) mode:** the file is already on the local disk (`BROWSERLESS_DOWNLOAD_DIR`, default a temp dir). The response lists the saved **path** — use/move it, or hand it straight back to `uploadFile { path }`. Nothing more to fetch.
 

package/build/src/skills/screenshots.md

@@ -30,6 +30,24 @@ Capture smallest region that answers the question.
 - **WebP** — better compression than JPEG
 - **`omitBackground: true`** — for transparent elements
 
+## Save to disk instead of seeing it
+
+By default a screenshot comes back as an inline image you see right away — that
+costs vision tokens and lives in context. If you only need the file _later_
+(hand it to the user, or re-upload it elsewhere) and don't need to look at it
+now, add **`toDisk: true`**:
+
+```json
+{ "method": "screenshot", "params": { "selector": "#invoice", "toDisk": true } }
+```
+
+You will **not** see the image. The response gives a reusable handle — a local
+path (stdio) or a single-use GET URL (HTTP) — exactly like a download. Reuse it
+with `uploadFile`, or hand the path/URL to the user. See the **file-transfers**
+skill for the handle/path/URL rules and TTL. Note: to actually _look_ at a
+disk-saved shot you'd have to load it back into context — so only use `toDisk`
+when you don't need to view it.
+
 ## Pattern: capture-after-action
 
 ```json

package/build/src/tools/agent.d.ts

@@ -35,4 +35,7 @@ type FormatOpts = {
     token?: string;
 };
 export declare const formatDownloads: (downloads: DownloadEntry[], prefix: string, skills: string, opts: FormatOpts) => Promise<Content[]>;
+export declare const formatScreenshotToDisk: (result: unknown, cmd: {
+    params?: Record<string, unknown>;
+}, caption: string, skills: string, opts: FormatOpts) => Promise<Content[] | null>;
 export declare function registerAgentTools(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/agent.js

@@ -25,19 +25,29 @@ const SCREENSHOT_MIME = {
     webp: 'image/webp',
     png: 'image/png',
 };
+const getScreenshotPayload = (result, cmd) => {
+    const base64 = typeof result?.base64 === 'string'
+        ? result.base64
+        : '';
+    if (!base64)
+        return null;
+    const requestedType = typeof cmd.params?.type === 'string' ? cmd.params.type : 'png';
+    return {
+        base64,
+        mimeType: SCREENSHOT_MIME[requestedType] ?? 'image/png',
+        requestedType,
+    };
+};
 /**
  * Build the MCP response for a screenshot command, or null when there's no
  * base64 payload (caller falls back to JSON text). Returns the image as a
  * vision content block (~1.5K tokens) vs. ~67K inlining the base64 as text.
  */
 export const formatScreenshotContent = (result, cmd, caption, skills) => {
-    const base64 = typeof result?.base64 === 'string'
-        ? result.base64
-        : '';
-    if (!base64)
+    const payload = getScreenshotPayload(result, cmd);
+    if (!payload)
         return null;
-    const requestedType = typeof cmd.params?.type === 'string' ? cmd.params.type : 'png';
-    const mimeType = SCREENSHOT_MIME[requestedType] ?? 'image/png';
+    const { base64, mimeType } = payload;
     const decodedBytes = Math.floor(base64.length * 0.75);
     const sizeLabel = decodedBytes >= 1_048_576
         ? `${(decodedBytes / 1_048_576).toFixed(1)} MB`
@@ -177,6 +187,25 @@ export const formatDownloads = async (downloads, prefix, skills, opts) => {
         content.push({ type: 'text', text: skills });
     return content;
 };
+// persist the bytes we already got back to the download store and surface a reusable handle
+export const formatScreenshotToDisk = async (result, cmd, caption, skills, opts) => {
+    const payload = getScreenshotPayload(result, cmd);
+    if (!payload)
+        return null;
+    const { base64, mimeType, requestedType } = payload;
+    const ext = requestedType === 'jpeg' ? 'jpg' : requestedType;
+    const record = await storeDownload(`screenshot.${ext}`, mimeType, Buffer.from(base64, 'base64'), opts.sessionId);
+    const text = [
+        caption.trimEnd(),
+        `Screenshot saved to disk (not shown inline):\n- ${describeReadyDownload(record, opts)}`,
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+    const content = [{ type: 'text', text }];
+    if (skills)
+        content.push({ type: 'text', text: skills });
+    return content;
+};
 const SkillIdSchema = z.enum(skillsRegistry.map((s) => s.id));
 const SkillToolParamsSchema = z.object({
     id: SkillIdSchema.describe('The skill to load (see tool description for the full list).'),
@@ -298,9 +327,18 @@ export function registerAgentTools(server, config, analytics) {
                     }
                     log.info(`agent: ${cmd.method} ${JSON.stringify(cmd.params)}`);
                     agentSession.skillState.cmdIndex += 1;
+                    // `toDisk` is a local directive (route the screenshot to the download
+                    // store); it's not a CDP screenshot param, so strip it before sending
+                    // or Chrome rejects the unknown key. The original cmd keeps it so the
+                    // result formatter can tell it should save instead of inline.
+                    let outboundParams = cmd.params;
+                    if (cmd.method === 'screenshot' && 'toDisk' in cmd.params) {
+                        outboundParams = { ...cmd.params };
+                        delete outboundParams.toDisk;
+                    }
                     let resp;
                     try {
-                        resp = await send(agentSession, cmd.method, cmd.params);
+                        resp = await send(agentSession, cmd.method, outboundParams);
                     }
                     catch (sendErr) {
                         destroySession(mcpSessionId, token, proxy, profile, createProfile, attachSessionId);
@@ -372,7 +410,7 @@ export function registerAgentTools(server, config, analytics) {
                 const reportable = closedDuringBatch ? results.slice(0, -1) : results;
                 const last = reportable[reportable.length - 1];
                 const lastResult = last.result;
-                const lastCmd = commands[commands.length - 1];
+                const lastCmd = commands[reportable.length - 1];
                 const closedSuffix = closedDuringBatch
                     ? '\n\nBrowser session closed.'
                     : '';
@@ -437,6 +475,22 @@ export function registerAgentTools(server, config, analytics) {
                         token,
                     });
                 }
+                else if (last.method === 'screenshot' &&
+                    lastCmd.params?.toDisk === true) {
+                    // Screenshot saved to disk → reusable handle, no inline image.
+                    const saved = await formatScreenshotToDisk(lastResult, lastCmd, batchPrefix, skillsText, {
+                        transport: config.transport,
+                        sessionId: mcpSessionId,
+                        mcpBaseUrl: config.mcpBaseUrl,
+                        token,
+                    });
+                    baseContent = saved ?? [
+                        {
+                            type: 'text',
+                            text: appendSkills(batchPrefix + JSON.stringify(lastResult, null, 2), triggered),
+                        },
+                    ];
+                }
                 else {
                     // Screenshot → image content block; otherwise JSON text.
                     const shot = last.method === 'screenshot'

package/build/src/tools/schemas.d.ts

@@ -219,6 +219,7 @@ export declare const AgentCommandSchema: z.ZodUnion<readonly [z.ZodDiscriminated
         }, z.core.$strip>>;
         waitForImages: z.ZodOptional<z.ZodBoolean>;
         timeout: z.ZodOptional<z.ZodNumber>;
+        toDisk: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
 }, z.core.$strip>, z.ZodObject<{
     method: z.ZodLiteral<"uploadFile">;
@@ -481,6 +482,7 @@ export declare const AgentParamsSchema: z.ZodObject<{
             }, z.core.$strip>>;
             waitForImages: z.ZodOptional<z.ZodBoolean>;
             timeout: z.ZodOptional<z.ZodNumber>;
+            toDisk: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
     }, z.core.$strip>, z.ZodObject<{
         method: z.ZodLiteral<"uploadFile">;

package/build/src/tools/schemas.js

@@ -353,6 +353,14 @@ const ScreenshotCommandSchema = z.object({
             .number()
             .optional()
             .describe('Timeout in milliseconds (default 30000)'),
+        toDisk: z
+            .boolean()
+            .optional()
+            .describe('Save the screenshot to disk instead of returning it inline. ' +
+            'You will NOT see the image; the response gives a reusable handle ' +
+            '(local path in stdio, single-use GET URL over HTTP) exactly like a ' +
+            'download — reuse it with uploadFile or hand it to the user. Use when ' +
+            'you only need the file later, not to look at now (see file-transfers).'),
     })
         .optional()
         .default({})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserless.io/mcp",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "MCP (Model Context Protocol) server for the Browserless.io browser automation platform",
   "author": "browserless.io",
   "license": "SSPL-1.0",
@@ -100,7 +100,8 @@
     "typescript-eslint": "^8.60.0"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24",
+    "npm": ">=11.10.0"
   },
   "overrides": {
     "mocha": {