@browserless.io/mcp 1.7.2 → 1.8.0

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.2",
+  "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": {