@browserless.io/mcp 1.6.2 → 1.7.1

package/build/src/tools/schemas.js

@@ -130,6 +130,22 @@ const TypeCommandSchema = z.object({
         text: z.string().describe('Text to type into the element'),
     }),
 });
+const LoadSecretCommandSchema = z.object({
+    method: z.literal('loadSecret'),
+    params: z.object({
+        ref: z
+            .string()
+            .describe('The credential reference/alias to inject (e.g. an op:// reference). ' +
+            'The secret value is resolved server-side and typed into the field — ' +
+            'you never see it. Use this for ALL passwords and usernames from a ' +
+            'secrets vault; never put a secret value in `type`.'),
+        selector: z
+            .string()
+            .optional()
+            .describe('CSS selector of the input to fill. If omitted, the secret is injected ' +
+            'into the currently focused element (click/focus the field first).'),
+    }),
+});
 const SelectCommandSchema = z.object({
     method: z.literal('select'),
     params: z.object({
@@ -392,6 +408,59 @@ const SolveCommandSchema = z.object({
         .optional()
         .default({}),
 });
+const UploadFileCommandSchema = z.object({
+    method: z.literal('uploadFile'),
+    params: z.object({
+        selector: z
+            .string()
+            .describe('CSS selector of the <input type="file"> element'),
+        files: z
+            .array(z
+            .object({
+            content: z
+                .string()
+                .optional()
+                .describe('Base64-encoded file content. LAST RESORT — only for tiny data ' +
+                'you already hold inline. Do NOT read a file into the ' +
+                'conversation, and never split/reassemble base64 by hand: use ' +
+                '`path` (stdio) or `handle` so the server moves the bytes.'),
+            handle: z
+                .string()
+                .optional()
+                .describe('A download handle from a prior getDownloads (a path in stdio ' +
+                'mode, a `browserless-download://` URI in HTTP mode). The MCP ' +
+                'server reads the stored file — works in both transports and ' +
+                'keeps the bytes out of the conversation. Use this to re-upload ' +
+                'a file you just downloaded.'),
+            path: z
+                .string()
+                .optional()
+                .describe('Local filesystem path to read and upload. stdio (local) mode ' +
+                'only — the MCP server reads and base64-encodes it. In HTTP ' +
+                'mode use `handle` or `content` instead.'),
+            name: z
+                .string()
+                .optional()
+                .describe('Filename reported to the page. Defaults to the basename of ' +
+                '`path`, else "file".'),
+            mimeType: z
+                .string()
+                .optional()
+                .describe('MIME type; inferred from the extension when omitted.'),
+        })
+            .refine((f) => [f.content, f.handle, f.path].filter((s) => s !== undefined)
+            .length === 1, {
+            message: 'Provide exactly one of "content", "handle", or "path" per file.',
+        }))
+            .min(1)
+            .describe('Files to attach. Combined decoded size is capped (server default ' +
+            '10MB, hard max 50MB).'),
+    }),
+});
+const GetDownloadsCommandSchema = z.object({
+    method: z.literal('getDownloads'),
+    params: z.object({}).optional().default({}),
+});
 const CloseCommandSchema = z.object({
     method: z.literal('close'),
     params: z.object({}).optional().default({}),
@@ -410,6 +479,7 @@ const specificCommandSchemas = [
     CloseTabCommandSchema,
     ClickCommandSchema,
     TypeCommandSchema,
+    LoadSecretCommandSchema,
     SelectCommandSchema,
     CheckboxCommandSchema,
     HoverCommandSchema,
@@ -425,6 +495,8 @@ const specificCommandSchemas = [
     LiveURLCommandSchema,
     SolveCommandSchema,
     ScreenshotCommandSchema,
+    UploadFileCommandSchema,
+    GetDownloadsCommandSchema,
     CloseCommandSchema,
 ];
 const KNOWN_METHODS = new Set(specificCommandSchemas.map((schema) => schema.shape.method.value));
@@ -446,7 +518,50 @@ export const AgentCommandSchema = z.union([
     z.discriminatedUnion('method', specificCommandSchemas),
     GenericCommandSchema,
 ]);
-export const AgentParamsSchema = z.object({
+// Proxy block for a profile-creation session. Mirrors the POST /profile body
+// proxy shape (type/sticky/country/city/state/preset) so it passes straight
+// through — distinct from the top-level agent proxy fields (proxy/proxyCountry…).
+const CreateProfileProxySchema = z.object({
+    type: z
+        .literal('residential')
+        .optional()
+        .describe('Routing tier. Only "residential" is supported today.'),
+    sticky: z
+        .boolean()
+        .optional()
+        .describe('Keep the same IP for the lifetime of the creation session.'),
+    country: z
+        .string()
+        .optional()
+        .describe('Two-letter country code (e.g. "us").'),
+    city: z.string().optional().describe('City-level targeting (plan-gated).'),
+    state: z.string().optional().describe('State/region targeting (plan-gated).'),
+    preset: z
+        .string()
+        .optional()
+        .describe('Named proxy preset (plan-dependent).'),
+});
+const CreateProfileSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(255)
+        .refine((s) => /^[^\s/?#]+$/.test(s), {
+        message: 'name must match /^[^\\s/?#]+$/ (no whitespace, /, ?, #)',
+    })
+        .describe('Name to save the profile under. Reused as the saveProfile name.'),
+    proxy: CreateProfileProxySchema.optional(),
+    browser: z.enum(['chrome', 'chromium', 'stealth']).optional(),
+    stealth: z.boolean().optional(),
+})
+    .describe('Open this session in profile-creation mode. The MCP tool POSTs /profile ' +
+    'with these params, attaches the agent WS to the returned creation session ' +
+    '(non-headless, 10-minute keepalive), and expects a saveProfile call before ' +
+    'close. Mutually exclusive with `profile`. Load the `auth-profile` skill ' +
+    '(via browserless_skill) for the full create-then-save recipe.');
+export const AgentParamsSchema = z
+    .object({
     method: z
         .string()
         .optional()
@@ -467,8 +582,12 @@ export const AgentParamsSchema = z.object({
         'type email + type password + click submit). Do NOT batch across navigations.'),
     proxy: ProxyOptionsSchema.optional().describe('Residential / external proxy config. Read once at session creation. ' +
         'Changing requires close() + a new session call.'),
-    profile: profileField('when the agent session connects', ' The profile is fixed for the lifetime of the agent session; ' +
-        'passing a different profile value opens a separate browser session.'),
+    profile: profileField('when the agent session connects', ' `profile` binds each call to its hydrated session — you MUST pass it on ' +
+        'every call in a multi-call flow, not just the first. A call that omits ' +
+        '`profile` runs in the default, un-hydrated session and will look logged ' +
+        'out; if that happens, re-issue the call WITH `profile` before concluding ' +
+        'the session expired. A different `profile` value opens a separate session.'),
+    createProfile: CreateProfileSchema.optional(),
     rationale: z
         .string()
         .optional()
@@ -484,4 +603,8 @@ export const AgentParamsSchema = z.object({
         'jargon, raw method names ("evaluate", "click"), JS, full URLs, or ' +
         'credentials. Include exactly one per `browserless_agent` call, even ' +
         'when batching commands.'),
+})
+    .refine((v) => !(v.profile && v.createProfile), {
+    message: '`profile` (hydrate an existing profile) and `createProfile` (author a new ' +
+        'one) cannot both be set',
 });

package/build/src/tools/smartscraper.js

@@ -47,9 +47,10 @@ export function registerSmartScraperTool(server, config, analytics) {
     const cache = new ResponseCache(config.cacheTtlMs);
     defineTool(server, config, analytics, {
         name: 'browserless_smartscraper',
-        description: 'Scrape any webpage using the Browserless smart scraper. ' +
-            'Returns page content in requested formats (markdown, html, screenshot, pdf, links). ' +
-            'Handles JavaScript-heavy pages, anti-bot measures, and multiple scraping strategies automatically.',
+        description: 'Scrape a SINGLE webpage and return its content as markdown or HTML. ' +
+            'Handles JavaScript-heavy pages and anti-bot measures automatically. ' +
+            'For content across MULTIPLE pages of a site, use browserless_crawl; ' +
+            "to list a site's URLs, use browserless_map.",
         parameters: SmartScraperParamsSchema,
         annotations: {
             title: 'Browserless Smart Scraper',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserless.io/mcp",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "description": "MCP (Model Context Protocol) server for the Browserless.io browser automation platform",
   "author": "browserless.io",
   "license": "SSPL-1.0",
@@ -84,7 +84,7 @@
     "@types/chai": "^5.2.2",
     "@types/ioredis-mock": "^8.2.7",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@types/sinon": "^21.0.1",
     "@types/ws": "^8.18.1",
     "c8": "^11.0.0",
@@ -108,6 +108,8 @@
       "minimatch": "^10.2.1",
       "glob": "^11.0.0",
       "serialize-javascript": "^7.0.5"
-    }
+    },
+    "hono": "^4.12.26",
+    "undici": "^7.28.0"
   }
 }

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

@@ -1,11 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import { AnalyticsHelper } from '../lib/analytics.js';
-import type { McpConfig } from '../@types/types.js';
-export declare const DownloadParamsSchema: z.ZodObject<{
-    code: z.ZodString;
-    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    profile: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare function registerDownloadTool(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/download.js

@@ -1,92 +0,0 @@
-import { UserError } from 'fastmcp';
-import { z } from 'zod';
-import { defineTool } from '../lib/define-tool.js';
-import { profileField } from './schemas.js';
-export const DownloadParamsSchema = z.object({
-    code: z
-        .string()
-        .describe('JavaScript (ESM) code to execute. The default export receives ' +
-        '{ page, context }. During execution the code should trigger a ' +
-        'file download in the browser (e.g. clicking a download link).'),
-    context: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe('Optional context object passed to the function.'),
-    timeout: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe('Request timeout in milliseconds'),
-    profile: profileField('before the download script runs'),
-});
-export function registerDownloadTool(server, config, analytics) {
-    defineTool(server, config, analytics, {
-        name: 'browserless_download',
-        description: 'Run custom Puppeteer code on Browserless and return the file that ' +
-            'Chrome downloads during execution. Your code should trigger a file ' +
-            'download (e.g. clicking a download link). The downloaded file is ' +
-            'returned with its original Content-Type. Useful for downloading ' +
-            'CSVs, PDFs, images, or any file from a website.',
-        parameters: DownloadParamsSchema,
-        annotations: {
-            title: 'Browserless Download',
-            readOnlyHint: false,
-            destructiveHint: true,
-            openWorldHint: true,
-        },
-        profileNotFoundMessage: (profile) => `Profile "${profile}" was not found for the configured API ` +
-            `token. Create the profile with Browserless.saveProfile in a ` +
-            `live session first, or omit the profile parameter to run the ` +
-            `download anonymously.`,
-        run: async ({ client, params, log }) => {
-            const response = await client.download({
-                code: params.code,
-                context: params.context,
-                timeout: params.timeout,
-                profile: params.profile,
-            });
-            log.debug(`Download response: ok=${response.ok}, status=${response.statusCode}, ` +
-                `contentType=${response.contentType}, size=${response.size}, ` +
-                `disposition=${response.contentDisposition}`);
-            return response;
-        },
-        analyticsProps: (params, result) => ({
-            ok: result.ok,
-            status_code: result.statusCode,
-            content_type: result.contentType,
-            size: result.size,
-            profile_used: !!params.profile,
-        }),
-        format: (response) => {
-            if (!response.ok) {
-                throw new UserError(`Download failed (status ${response.statusCode}): ${response.data.slice(0, 500)}`);
-            }
-            const filenameMatch = response.contentDisposition?.match(/filename[^;=\n]*=["']?([^"';\n]*)["']?/);
-            const filename = filenameMatch?.[1] ?? 'downloaded-file';
-            const blocks = [];
-            if (response.isBinary) {
-                blocks.push({
-                    type: 'text',
-                    text: `[Downloaded file: "${filename}" – ${response.contentType}, ` +
-                        `${response.size} bytes, base64-encoded]\n${response.data}`,
-                });
-            }
-            else {
-                blocks.push({ type: 'text', text: response.data });
-            }
-            blocks.push({
-                type: 'text',
-                text: [
-                    '---',
-                    `Filename: ${filename}`,
-                    `Content-Type: ${response.contentType}`,
-                    `Status: ${response.statusCode}`,
-                    `Size: ${response.size} bytes`,
-                    '---',
-                ].join('\n'),
-            });
-            return blocks;
-        },
-    });
-}