@browserless.io/mcp 1.6.0

package/build/src/tools/search.js

@@ -0,0 +1,184 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { defineTool } from '../lib/define-tool.js';
+export const SearchSourceSchema = z.enum(['web', 'news', 'images']);
+export const SearchCategorySchema = z.enum(['github', 'research', 'pdf']);
+export const TimeBasedOptionsSchema = z.enum(['day', 'week', 'month', 'year']);
+export const SearchScrapeOptionsSchema = z.object({
+    formats: z
+        .array(z.enum(['markdown', 'html', 'links', 'screenshot']))
+        .optional()
+        .describe('Output formats for scraped content'),
+    onlyMainContent: z
+        .boolean()
+        .optional()
+        .describe('Extract only the main content using Readability'),
+    includeTags: z
+        .array(z.string())
+        .optional()
+        .describe('Only include content from these HTML tags'),
+    excludeTags: z
+        .array(z.string())
+        .optional()
+        .describe('Exclude content from these HTML tags'),
+});
+export const SearchParamsSchema = z.object({
+    query: z.string().min(1).describe('The search query string'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .default(10)
+        .describe('Maximum number of results to return (default: 10, max: 100)'),
+    lang: z
+        .string()
+        .optional()
+        .default('en')
+        .describe('Language code for search results (default: "en")'),
+    country: z
+        .string()
+        .optional()
+        .describe('Country code for geo-targeted results'),
+    location: z
+        .string()
+        .optional()
+        .describe('Location string for geo-targeted results'),
+    tbs: TimeBasedOptionsSchema.optional().describe('Time-based filter: "day", "week", "month", "year"'),
+    sources: z
+        .array(SearchSourceSchema)
+        .optional()
+        .default(['web'])
+        .describe('Search sources: "web", "news", "images" (default: ["web"])'),
+    categories: z
+        .array(SearchCategorySchema)
+        .optional()
+        .describe('Filter by categories: "github", "research", "pdf"'),
+    scrapeOptions: SearchScrapeOptionsSchema.optional().describe('Options for scraping each search result'),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Request timeout in milliseconds'),
+});
+export function registerSearchTool(server, config, analytics) {
+    defineTool(server, config, analytics, {
+        name: 'browserless_search',
+        description: 'Search the web using Browserless and optionally scrape each result. ' +
+            'Performs web searches via SearXNG and can return results from web, news, or images. ' +
+            'Optionally scrape each result URL to get markdown, HTML, links, or screenshots. ' +
+            'Useful for research, gathering information, and finding relevant web pages.',
+        parameters: SearchParamsSchema,
+        annotations: {
+            title: 'Browserless Search',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        run: async ({ client, params, log }) => {
+            const response = await client.search({
+                query: params.query,
+                limit: params.limit,
+                lang: params.lang,
+                country: params.country,
+                location: params.location,
+                tbs: params.tbs,
+                sources: params.sources,
+                categories: params.categories,
+                scrapeOptions: params.scrapeOptions,
+                timeout: params.timeout,
+            });
+            log.debug(`Search response: success=${response.success}, totalResults=${response.totalResults}`);
+            return response;
+        },
+        analyticsProps: (params, result) => ({
+            query: params.query,
+            limit: params.limit ?? 10,
+            sources: (params.sources ?? ['web']).join(','),
+            success: result.success,
+            total_results: result.totalResults,
+        }),
+        format: (response, params) => {
+            if (!response.success) {
+                throw new UserError(`Search failed: ${response.error ?? 'Unknown error'}`);
+            }
+            const blocks = [];
+            if (response.data.web && response.data.web.length > 0) {
+                const webResults = response.data.web
+                    .map((result, index) => {
+                    let text = `### ${index + 1}. ${result.title}\n`;
+                    text += `**URL:** ${result.url}\n`;
+                    if (result.description)
+                        text += `**Description:** ${result.description}\n`;
+                    if (result.markdown) {
+                        const truncated = result.markdown.length > 1000
+                            ? `${result.markdown.slice(0, 1000)}...`
+                            : result.markdown;
+                        text += `\n**Content:**\n${truncated}\n`;
+                    }
+                    return text;
+                })
+                    .join('\n---\n');
+                blocks.push({
+                    type: 'text',
+                    text: `## Web Results (${response.data.web.length})\n\n${webResults}`,
+                });
+            }
+            if (response.data.news && response.data.news.length > 0) {
+                const newsResults = response.data.news
+                    .map((result, index) => {
+                    let text = `### ${index + 1}. ${result.title}\n`;
+                    text += `**URL:** ${result.url}\n`;
+                    if (result.date)
+                        text += `**Date:** ${result.date}\n`;
+                    if (result.description)
+                        text += `**Description:** ${result.description}\n`;
+                    return text;
+                })
+                    .join('\n---\n');
+                blocks.push({
+                    type: 'text',
+                    text: `## News Results (${response.data.news.length})\n\n${newsResults}`,
+                });
+            }
+            if (response.data.images && response.data.images.length > 0) {
+                const imageResults = response.data.images
+                    .map((result, index) => {
+                    let text = `### ${index + 1}. ${result.title ?? 'Image'}\n`;
+                    if (result.imageUrl)
+                        text += `**Image URL:** ${result.imageUrl}\n`;
+                    if (result.url)
+                        text += `**Source:** ${result.url}\n`;
+                    if (result.imageWidth && result.imageHeight) {
+                        text += `**Size:** ${result.imageWidth}x${result.imageHeight}\n`;
+                    }
+                    return text;
+                })
+                    .join('\n---\n');
+                blocks.push({
+                    type: 'text',
+                    text: `## Image Results (${response.data.images.length})\n\n${imageResults}`,
+                });
+            }
+            if (blocks.length === 0) {
+                blocks.push({
+                    type: 'text',
+                    text: `No results found for query: "${params.query}"`,
+                });
+            }
+            blocks.push({
+                type: 'text',
+                text: [
+                    '---',
+                    `Query: ${params.query}`,
+                    `Total Results: ${response.totalResults}`,
+                    `Sources: ${(params.sources ?? ['web']).join(', ')}`,
+                    '---',
+                ].join('\n'),
+            });
+            return blocks;
+        },
+    });
+}

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

@@ -0,0 +1,42 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { AnalyticsHelper } from '../lib/analytics.js';
+import type { McpConfig } from '../@types/types.js';
+/**
+ * Output formats that can be requested.
+ * Mirrors the Firecrawl "formats" convention used by the Browserless API.
+ */
+export declare const ScrapeFormatSchema: z.ZodEnum<{
+    screenshot: "screenshot";
+    pdf: "pdf";
+    markdown: "markdown";
+    links: "links";
+    html: "html";
+}>;
+export declare const SmartScraperParamsSchema: z.ZodObject<{
+    url: z.ZodURL;
+    formats: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        screenshot: "screenshot";
+        pdf: "pdf";
+        markdown: "markdown";
+        links: "links";
+        html: "html";
+    }>>>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    profile: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SmartScraperResponseSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    statusCode: z.ZodNullable<z.ZodNumber>;
+    content: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>;
+    contentType: z.ZodNullable<z.ZodString>;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    strategy: z.ZodString;
+    attempted: z.ZodArray<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+    screenshot: z.ZodNullable<z.ZodString>;
+    pdf: z.ZodNullable<z.ZodString>;
+    markdown: z.ZodNullable<z.ZodString>;
+    links: z.ZodNullable<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare function registerSmartScraperTool(server: FastMCP, config: McpConfig, analytics?: AnalyticsHelper): void;

package/build/src/tools/smartscraper.js

@@ -0,0 +1,136 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { defineTool, validateHttpUrl } from '../lib/define-tool.js';
+import { profileField } from './schemas.js';
+import { ResponseCache } from '../lib/cache.js';
+/**
+ * Output formats that can be requested.
+ * Mirrors the Firecrawl "formats" convention used by the Browserless API.
+ */
+export const ScrapeFormatSchema = z.enum([
+    'markdown',
+    'html',
+    'screenshot',
+    'pdf',
+    'links',
+]);
+export const SmartScraperParamsSchema = z.object({
+    url: z.url().describe('The URL to scrape (must be http or https)'),
+    formats: z
+        .array(ScrapeFormatSchema)
+        .optional()
+        .default(['markdown'])
+        .describe('Output formats to include: "markdown", "html", "screenshot", "pdf", "links". Defaults to ["markdown"].'),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Request timeout in milliseconds'),
+    profile: profileField('before scraping'),
+});
+export const SmartScraperResponseSchema = z.object({
+    ok: z.boolean(),
+    statusCode: z.number().nullable(),
+    content: z.union([z.string(), z.record(z.string(), z.unknown()), z.null()]),
+    contentType: z.string().nullable(),
+    headers: z.record(z.string(), z.string()),
+    strategy: z.string(),
+    attempted: z.array(z.string()),
+    message: z.string().nullable(),
+    screenshot: z.string().nullable(),
+    pdf: z.string().nullable(),
+    markdown: z.string().nullable(),
+    links: z.array(z.string()).nullable(),
+});
+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.',
+        parameters: SmartScraperParamsSchema,
+        annotations: {
+            title: 'Browserless Smart Scraper',
+            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 scrape ` +
+            `anonymously.`,
+        cache,
+        run: async ({ client, params }) => client.smartScrape({
+            url: params.url,
+            formats: params.formats,
+            timeout: params.timeout,
+            profile: params.profile,
+        }),
+        analyticsProps: (params, result) => ({
+            url: params.url,
+            formats: (params.formats ?? ['markdown']).join(','),
+            timeout: params.timeout ?? config.requestTimeout,
+            cache_hit: result.cacheHit,
+            ok: result.ok,
+            status_code: result.statusCode,
+            strategy: result.strategy,
+            profile_used: !!params.profile,
+        }),
+        format: (response) => {
+            if (!response.ok) {
+                throw new UserError(`Scraping failed: ${response.message ?? 'Unknown error'} ` +
+                    `(status: ${response.statusCode}, strategies attempted: ${response.attempted.join(', ')})`);
+            }
+            const blocks = [];
+            // Primary text content: prefer markdown > string content > object content > diagnostic
+            let textContent;
+            if (response.markdown) {
+                textContent = response.markdown;
+            }
+            else if (typeof response.content === 'string' && response.content) {
+                textContent = response.content;
+            }
+            else if (response.content && typeof response.content === 'object') {
+                textContent = JSON.stringify(response.content, null, 2);
+            }
+            else {
+                textContent = `[No page content returned by the API. Strategy: ${response.strategy}, Status: ${response.statusCode}]`;
+            }
+            blocks.push({ type: 'text', text: textContent });
+            blocks.push({
+                type: 'text',
+                text: [
+                    '---',
+                    `Strategy: ${response.strategy}`,
+                    `Status: ${response.statusCode}`,
+                    `Content-Type: ${response.contentType}`,
+                    `Strategies Attempted: ${response.attempted.join(', ')}`,
+                    '---',
+                ].join('\n'),
+            });
+            if (response.screenshot) {
+                blocks.push({
+                    type: 'image',
+                    data: response.screenshot,
+                    mimeType: 'image/png',
+                });
+            }
+            if (response.pdf) {
+                blocks.push({
+                    type: 'text',
+                    text: `[PDF Document - base64 encoded, ${response.pdf.length} characters]\n${response.pdf}`,
+                });
+            }
+            if (response.links && response.links.length > 0) {
+                blocks.push({
+                    type: 'text',
+                    text: `## Links (${response.links.length})\n${response.links.join('\n')}`,
+                });
+            }
+            return blocks;
+        },
+    });
+}

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@browserless.io/mcp",
+  "version": "1.6.0",
+  "description": "MCP (Model Context Protocol) server for the Browserless.io browser automation platform",
+  "author": "browserless.io",
+  "license": "SSPL-1.0",
+  "type": "module",
+  "main": "./build/src/index.js",
+  "types": "./build/src/index.d.ts",
+  "bin": {
+    "browserless-mcp": "./bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/src/index.d.ts",
+      "import": "./build/src/index.js"
+    },
+    "./skills": {
+      "types": "./build/src/skills/index.d.ts",
+      "import": "./build/src/skills/index.js"
+    },
+    "./agent-client": {
+      "types": "./build/src/lib/agent-client.d.ts",
+      "import": "./build/src/lib/agent-client.js"
+    },
+    "./schemas": {
+      "types": "./build/src/tools/schemas.d.ts",
+      "import": "./build/src/tools/schemas.js"
+    },
+    "./prompt": {
+      "types": "./build/src/skills/system-prompt.d.ts",
+      "import": "./build/src/skills/system-prompt.js"
+    },
+    "./errors": {
+      "types": "./build/src/lib/error-classifier.d.ts",
+      "import": "./build/src/lib/error-classifier.js"
+    },
+    "./format": {
+      "types": "./build/src/lib/agent-format.d.ts",
+      "import": "./build/src/lib/agent-format.js"
+    }
+  },
+  "files": [
+    "build/src/**/*.js",
+    "build/src/**/*.d.ts",
+    "build/src/**/*.md",
+    "bin/*",
+    "patches/**",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:skills && npm run build:types",
+    "build:skills": "mkdir -p build/src/skills && cp src/skills/*.md build/src/skills/",
+    "build:types": "mkdir -p build/src/@types && cp src/@types/*.d.ts build/src/@types/",
+    "clean": "rm -rf build",
+    "dev": "BROWSERLESS_TOKEN=${BROWSERLESS_TOKEN:-test} node --watch build/src/index.js",
+    "lint": "eslint src test",
+    "test": "npm run build && mocha",
+    "coverage": "npm run build && c8 --reporter=text --reporter=html --reporter=lcov --check-coverage --lines 80 --branches 70 --functions 80 mocha",
+    "start": "node build/src/index.js",
+    "start:http": "TRANSPORT=httpStream PORT=8080 node build/src/index.js",
+    "postinstall": "patch-package",
+    "prepack": "npm run build",
+    "prepare": "husky",
+    "prettier": "prettier '{src,test,bin,.github}/**/*.{js,ts,json,yml,yaml,md}' --log-level error --write"
+  },
+  "prettier": {
+    "semi": true,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "printWidth": 80
+  },
+  "dependencies": {
+    "@aws-sdk/client-sqs": "^3.1053.0",
+    "fastmcp": "^4.0.0",
+    "ioredis": "^5.10.1",
+    "patch-package": "^8.0.1",
+    "ws": "^8.21.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/chai": "^5.2.2",
+    "@types/ioredis-mock": "^8.2.7",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.9.1",
+    "@types/sinon": "^21.0.1",
+    "@types/ws": "^8.18.1",
+    "c8": "^11.0.0",
+    "chai": "^6.2.2",
+    "eslint": "^10.4.0",
+    "globals": "^17.6.0",
+    "husky": "^9.1.7",
+    "ioredis-mock": "^8.13.1",
+    "mocha": "^11.7.6",
+    "prettier": "^3.8.3",
+    "sinon": "^22.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "overrides": {
+    "mocha": {
+      "diff": "^8.0.3",
+      "minimatch": "^10.2.1",
+      "glob": "^11.0.0"
+    }
+  }
+}

package/patches/mcp-proxy+6.4.0.patch

@@ -0,0 +1,31 @@
+diff --git a/node_modules/mcp-proxy/dist/stdio-CyOk7u4Q.mjs b/node_modules/mcp-proxy/dist/stdio-CyOk7u4Q.mjs
+index bfd727e..3350845 100644
+--- a/node_modules/mcp-proxy/dist/stdio-CyOk7u4Q.mjs
++++ b/node_modules/mcp-proxy/dist/stdio-CyOk7u4Q.mjs
+@@ -15479,6 +15479,10 @@ const handleStreamRequest = async ({ activeTransports, authenticate, authMiddlew
+ 		const sessionId = req.headers["mcp-session-id"];
+ 		const activeTransport = sessionId ? activeTransports[sessionId] : void 0;
+ 		if (!sessionId) {
++			if (stateless) {
++				res.writeHead(405, { Allow: "POST" }).end("Method Not Allowed");
++				return true;
++			}
+ 			res.writeHead(400).end("No sessionId");
+ 			return true;
+ 		}
+diff --git a/node_modules/mcp-proxy/src/startHTTPServer.ts b/node_modules/mcp-proxy/src/startHTTPServer.ts
+index 80e8cb7..ac051a1 100644
+--- a/node_modules/mcp-proxy/src/startHTTPServer.ts
++++ b/node_modules/mcp-proxy/src/startHTTPServer.ts
+@@ -686,6 +686,11 @@ const handleStreamRequest = async <T extends ServerLike>({
+       | undefined = sessionId ? activeTransports[sessionId] : undefined;
+ 
+     if (!sessionId) {
++      if (stateless) {
++        res.writeHead(405, { Allow: "POST" }).end("Method Not Allowed");
++
++        return true;
++      }
+       res.writeHead(400).end("No sessionId");
+ 
+       return true;