@browserless.io/mcp 1.7.0 → 1.7.2

package/README.md

@@ -24,9 +24,9 @@ No local install — see [Configuration](#configuration) for per-client snippets
 
 | Tool                       | Description                                                                                                                                                                                                                                                                                                                                                                        |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `browserless_smartscraper` | Scrape any webpage using cascading strategies (HTTP fetch, proxy, headless browser, captcha solving). Returns content in requested formats: `markdown`, `html`, `screenshot`, `pdf`, `links`.                                                                                                                                                                                      |
+| `browserless_smartscraper` | 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, use `browserless_crawl`; to list a site's URLs, use `browserless_map`.                                                                                                                                  |
 | `browserless_search`       | Search the web using Browserless and optionally scrape each result. Supports web, news, and image search with geo-targeting and time filters.                                                                                                                                                                                                                                      |
-| `browserless_map`          | Discover and map all URLs on a website. Crawls via sitemaps and link extraction. Returns URLs with optional titles and descriptions. Useful for site audits and content discovery.                                                                                                                                                                                                 |
+| `browserless_map`          | Discover and map all URLs on a website. Scans via sitemaps and link extraction. Returns URLs with optional titles and descriptions. Useful for site audits and content discovery.                                                                                                                                                                                                  |
 | `browserless_crawl`        | Crawl a website and scrape every discovered page. Supports depth control, path filtering, sitemap strategies, and configurable scrape options. Returns scraped content and metadata for each page.                                                                                                                                                                                 |
 | `browserless_performance`  | Run Lighthouse audits on any URL. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category or supply performance budgets.                                                                                                                                                                                            |
 | `browserless_function`     | Execute custom Puppeteer JavaScript on the Browserless cloud. The function receives a `page` object and optional `context`; return `{ data, type }` to control the payload and Content-Type.                                                                                                                                                                                       |

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/tools/map.js

@@ -42,7 +42,7 @@ 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. ' +
+            'Scans 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.',

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.7.0",
+  "version": "1.7.2",
   "description": "MCP (Model Context Protocol) server for the Browserless.io browser automation platform",
   "author": "browserless.io",
   "license": "SSPL-1.0",