@browserless.io/mcp 1.6.0

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

@@ -0,0 +1,24 @@
+import { FastMCP } from 'fastmcp';
+import type { Content } from 'fastmcp';
+import { z } from 'zod';
+import { AnalyticsHelper } from '../lib/analytics.js';
+import type { GenericApiResult, McpConfig } from '../@types/types.js';
+export declare const FunctionParamsSchema: 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>;
+/**
+ * Hard cap for text responses. Larger payloads are rejected with a clear
+ * remediation message instead of silently torching context. ~4 chars/token →
+ * 200,000 chars ≈ 50,000 tokens.
+ */
+export declare const MAX_TEXT_RESPONSE_CHARS = 200000;
+/**
+ * Convert a /function HTTP response into MCP content blocks: image/* and
+ * audio/* become vision/audio input, other binary becomes a resource blob,
+ * and text becomes TextContent (throws past MAX_TEXT_RESPONSE_CHARS).
+ */
+export declare const formatFunctionContent: (response: GenericApiResult) => Content[];
+export declare function registerFunctionTool(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/function.js

@@ -0,0 +1,144 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { defineTool } from '../lib/define-tool.js';
+import { profileField } from './schemas.js';
+export const FunctionParamsSchema = z.object({
+    code: z
+        .string()
+        .describe('JavaScript (ESM) code to execute. The default export receives ' +
+        '{ page, context } and should return { data, type } where data ' +
+        'is the response payload and type is the Content-Type string.'),
+    context: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Optional context object passed to the function as the second argument.'),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Request timeout in milliseconds'),
+    profile: profileField('before the function executes'),
+});
+/**
+ * Hard cap for text responses. Larger payloads are rejected with a clear
+ * remediation message instead of silently torching context. ~4 chars/token →
+ * 200,000 chars ≈ 50,000 tokens.
+ */
+export const MAX_TEXT_RESPONSE_CHARS = 200_000;
+const EXTENSION_BY_MIME = {
+    'application/pdf': '.pdf',
+    'application/zip': '.zip',
+    'application/octet-stream': '.bin',
+    'application/json': '.json',
+};
+const buildMetadata = (response) => [
+    '---',
+    `Content-Type: ${response.contentType}`,
+    `Status: ${response.statusCode}`,
+    `Size: ${response.size} bytes`,
+    '---',
+].join('\n');
+/**
+ * Convert a /function HTTP response into MCP content blocks: image/* and
+ * audio/* become vision/audio input, other binary becomes a resource blob,
+ * and text becomes TextContent (throws past MAX_TEXT_RESPONSE_CHARS).
+ */
+export const formatFunctionContent = (response) => {
+    const baseMime = response.contentType.split(';')[0].trim().toLowerCase();
+    const metadata = buildMetadata(response);
+    if (response.isBinary) {
+        if (baseMime.startsWith('image/')) {
+            return [
+                { type: 'text', text: metadata },
+                { type: 'image', data: response.data, mimeType: baseMime },
+            ];
+        }
+        if (baseMime.startsWith('audio/')) {
+            return [
+                { type: 'text', text: metadata },
+                { type: 'audio', data: response.data, mimeType: baseMime },
+            ];
+        }
+        const ext = EXTENSION_BY_MIME[baseMime] ?? '.bin';
+        return [
+            { type: 'text', text: metadata },
+            {
+                type: 'resource',
+                resource: {
+                    uri: `browserless://function/result${ext}`,
+                    mimeType: baseMime,
+                    blob: response.data,
+                },
+            },
+        ];
+    }
+    if (response.data.length > MAX_TEXT_RESPONSE_CHARS) {
+        const approxTokens = Math.round(response.data.length / 4);
+        const capTokens = Math.round(MAX_TEXT_RESPONSE_CHARS / 4);
+        throw new UserError(`Function returned ${response.data.length} chars (~${approxTokens} tokens), ` +
+            `exceeding the ${MAX_TEXT_RESPONSE_CHARS}-char (~${capTokens}-token) limit. ` +
+            `Either filter/summarize inside your function, or — for binary outputs — ` +
+            `return { type: "image/jpeg" } / "image/png" / "audio/mpeg" / "application/pdf" ` +
+            `from your function so the bytes come back as a proper content block instead of base64 text.`);
+    }
+    return [
+        { type: 'text', text: response.data },
+        { type: 'text', text: metadata },
+    ];
+};
+export function registerFunctionTool(server, config, analytics) {
+    defineTool(server, config, analytics, {
+        name: 'browserless_function',
+        description: 'Execute custom Puppeteer JavaScript code on the Browserless cloud. ' +
+            'Your function receives a Puppeteer `page` object and optional `context` data. ' +
+            'Return { data, type } to control the response payload and Content-Type. ' +
+            '\n\n' +
+            'For binary outputs, set `type` to a real MIME so the bytes come back as a proper ' +
+            'content block instead of base64 text:\n' +
+            '  - `image/png` / `image/jpeg` / `image/webp` → vision content block (~1.5K tokens)\n' +
+            '  - `audio/mpeg` / `audio/wav` → audio content block\n' +
+            '  - `application/pdf` and other binaries → resource content block (attachment)\n' +
+            '\n' +
+            'Text responses are capped at 200,000 characters (~50K tokens). Larger text payloads ' +
+            'will be rejected — filter or summarize inside your function, or switch to a binary ' +
+            'type if you actually meant to return bytes.\n' +
+            '\n' +
+            'Useful for complex scraping, form filling, or any browser automation that requires custom code.',
+        parameters: FunctionParamsSchema,
+        annotations: {
+            title: 'Browserless Function',
+            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 ` +
+            `function anonymously.`,
+        run: async ({ client, params, log }) => {
+            const response = await client.runFunction({
+                code: params.code,
+                context: params.context,
+                timeout: params.timeout,
+                profile: params.profile,
+            });
+            log.debug(`Function response: ok=${response.ok}, status=${response.statusCode}, ` +
+                `contentType=${response.contentType}, size=${response.size}`);
+            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(`Function execution failed (status ${response.statusCode}): ${response.data.slice(0, 500)}`);
+            }
+            return formatFunctionContent(response);
+        },
+    });
+}

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

@@ -0,0 +1,23 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { AnalyticsHelper } from '../lib/analytics.js';
+import type { McpConfig } from '../@types/types.js';
+export declare const SitemapModeSchema: z.ZodEnum<{
+    include: "include";
+    skip: "skip";
+    only: "only";
+}>;
+export declare const MapParamsSchema: z.ZodObject<{
+    url: z.ZodURL;
+    search: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    sitemap: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        include: "include";
+        skip: "skip";
+        only: "only";
+    }>>>;
+    includeSubdomains: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    ignoreQueryParameters: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function registerMapTool(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/map.js

@@ -0,0 +1,129 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { defineTool, validateHttpUrl } from '../lib/define-tool.js';
+export const SitemapModeSchema = z.enum(['include', 'skip', 'only']);
+export const MapParamsSchema = z.object({
+    url: z
+        .url()
+        .describe('The base URL to start mapping from (must be http or https)'),
+    search: z
+        .string()
+        .optional()
+        .describe('Search query to order results by relevance'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(5000)
+        .optional()
+        .default(100)
+        .describe('Maximum number of links to return (default: 100, max: 5000)'),
+    sitemap: SitemapModeSchema.optional()
+        .default('include')
+        .describe('Sitemap handling: "include" (default), "skip", "only"'),
+    includeSubdomains: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include URLs from subdomains (default: true)'),
+    ignoreQueryParameters: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Exclude URLs with query parameters (default: true)'),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Request timeout in milliseconds'),
+});
+export function registerMapTool(server, config, analytics) {
+    defineTool(server, config, analytics, {
+        name: 'browserless_map',
+        description: 'Discover and map all URLs on a website using Browserless. ' +
+            'Crawls a site via sitemaps and link extraction to find all pages. ' +
+            'Returns a list of URLs with optional titles and descriptions. ' +
+            'Use the search parameter to order results by relevance to a query. ' +
+            'Useful for site audits, content discovery, and building site maps.',
+        parameters: MapParamsSchema,
+        annotations: {
+            title: 'Browserless Map',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        validateUrl: (p) => validateHttpUrl(p.url),
+        run: async ({ client, params, log }) => {
+            const response = await client.map({
+                url: params.url,
+                search: params.search,
+                limit: params.limit,
+                sitemap: params.sitemap,
+                includeSubdomains: params.includeSubdomains,
+                ignoreQueryParameters: params.ignoreQueryParameters,
+                timeout: params.timeout,
+            });
+            if (!response.success) {
+                throw new UserError(`Map failed: ${response.error ?? 'Unknown error'}`);
+            }
+            log.debug(`Map response: success=${response.success}, links=${response.links?.length ?? 0}`);
+            return response;
+        },
+        analyticsProps: (params, result) => ({
+            url: params.url,
+            limit: params.limit ?? 100,
+            sitemap_mode: params.sitemap ?? 'include',
+            success: result.success,
+            links_found: result.links?.length ?? 0,
+        }),
+        format: (response, params) => {
+            const blocks = [];
+            if (response.links && response.links.length > 0) {
+                const linksText = response.links
+                    .map((link, index) => {
+                    let text = `${index + 1}. ${link.url}`;
+                    if (link.title)
+                        text += `\n   Title: ${link.title}`;
+                    if (link.description) {
+                        const truncated = link.description.length > 200
+                            ? `${link.description.slice(0, 200)}...`
+                            : link.description;
+                        text += `\n   Description: ${truncated}`;
+                    }
+                    return text;
+                })
+                    .join('\n\n');
+                blocks.push({
+                    type: 'text',
+                    text: `## Site Map Results (${response.links.length} URLs)\n\n${linksText}`,
+                });
+                const urlList = response.links.map((l) => l.url).join('\n');
+                blocks.push({
+                    type: 'text',
+                    text: `## URL List\n\n${urlList}`,
+                });
+            }
+            else {
+                blocks.push({
+                    type: 'text',
+                    text: `No URLs found for site: ${params.url}`,
+                });
+            }
+            blocks.push({
+                type: 'text',
+                text: [
+                    '---',
+                    `Base URL: ${params.url}`,
+                    `URLs Found: ${response.links?.length ?? 0}`,
+                    `Sitemap Mode: ${params.sitemap ?? 'include'}`,
+                    params.search ? `Search Query: ${params.search}` : '',
+                    '---',
+                ]
+                    .filter(Boolean)
+                    .join('\n'),
+            });
+            return blocks;
+        },
+    });
+}

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

@@ -0,0 +1,25 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { AnalyticsHelper } from '../lib/analytics.js';
+import type { McpConfig } from '../@types/types.js';
+export declare const LighthouseCategorySchema: z.ZodEnum<{
+    accessibility: "accessibility";
+    "best-practices": "best-practices";
+    performance: "performance";
+    pwa: "pwa";
+    seo: "seo";
+}>;
+export declare const PerformanceParamsSchema: z.ZodObject<{
+    url: z.ZodURL;
+    categories: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        accessibility: "accessibility";
+        "best-practices": "best-practices";
+        performance: "performance";
+        pwa: "pwa";
+        seo: "seo";
+    }>>>;
+    budgets: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    profile: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function registerPerformanceTool(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/performance.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { defineTool, validateHttpUrl } from '../lib/define-tool.js';
+import { profileField } from './schemas.js';
+export const LighthouseCategorySchema = z.enum([
+    'accessibility',
+    'best-practices',
+    'performance',
+    'pwa',
+    'seo',
+]);
+export const PerformanceParamsSchema = z.object({
+    url: z.url().describe('The URL to audit (must be http or https)'),
+    categories: z
+        .array(LighthouseCategorySchema)
+        .optional()
+        .describe('Lighthouse categories to audit: "accessibility", "best-practices", ' +
+        '"performance", "pwa", "seo". Omit for all categories.'),
+    budgets: z
+        .array(z.record(z.string(), z.unknown()))
+        .optional()
+        .describe('Lighthouse performance budgets array. ' +
+        'See https://developer.chrome.com/docs/lighthouse/performance/performance-budgets'),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Request timeout in milliseconds (audits can take 30s–120s)'),
+    profile: profileField('before the Lighthouse audit runs'),
+});
+export function registerPerformanceTool(server, config, analytics) {
+    defineTool(server, config, analytics, {
+        name: 'browserless_performance',
+        description: 'Run a Lighthouse performance audit on any URL via the Browserless /performance API. ' +
+            'Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. ' +
+            'Optionally filter by category or supply performance budgets. ' +
+            'Note: audits can take 30s–120s depending on the site.',
+        parameters: PerformanceParamsSchema,
+        annotations: {
+            title: 'Browserless Lighthouse Performance Audit',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        validateUrl: (p) => validateHttpUrl(p.url),
+        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 audit ` +
+            `the page anonymously.`,
+        run: async ({ client, params, log }) => {
+            const response = await client.performance({
+                url: params.url,
+                categories: params.categories,
+                budgets: params.budgets,
+                timeout: params.timeout,
+                profile: params.profile,
+            });
+            log.debug(`Performance response: type=${response.type}, ` +
+                `dataKeys=${Object.keys(response.data ?? {}).length}`);
+            return response;
+        },
+        analyticsProps: (params) => ({
+            url: params.url,
+            categories: (params.categories ?? []).join(','),
+            profile_used: !!params.profile,
+        }),
+        format: (response, params) => {
+            const blocks = [];
+            const data = response.data ?? {};
+            const categories = (data.categories ?? {});
+            const categoryEntries = Object.entries(categories);
+            if (categoryEntries.length > 0) {
+                const summary = categoryEntries
+                    .map(([id, cat]) => {
+                    const score = cat.score != null
+                        ? `${Math.round(cat.score * 100)}/100`
+                        : 'N/A';
+                    return `- ${cat.title ?? id}: ${score}`;
+                })
+                    .join('\n');
+                blocks.push({
+                    type: 'text',
+                    text: `## Lighthouse Scores\n${summary}`,
+                });
+            }
+            blocks.push({
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            });
+            const meta = [
+                '---',
+                `URL: ${params.url}`,
+                `Lighthouse Version: ${data.lighthouseVersion ?? 'unknown'}`,
+            ];
+            if (params.categories) {
+                meta.push(`Categories: ${params.categories.join(', ')}`);
+            }
+            meta.push('---');
+            blocks.push({ type: 'text', text: meta.join('\n') });
+            return blocks;
+        },
+    });
+}