@zenrows/mcp 2.2.4 → 2.4.0

package/dist/auth/claim-hint.d.ts

@@ -1,3 +1,15 @@
+/**
+ * A per-key credit cap: Fetch, Extract and Browser answer 402 AUTH014, Batch answers
+ * 402 `api_key_cap_reached`. The account still has credits and its other keys still
+ * work, so "buy credits" or "claim your account" would send the user the wrong way.
+ */
+export declare const KEY_CAP_CODES: ReadonlySet<string>;
+export declare const KEY_CAP_NUDGE = "This API key reached one of its credit caps. The account's other API keys still work. Raise or remove the cap at https://app.zenrows.com/settings/api-keys, or wait until it resets (the error detail says when).";
+export declare function isKeyCapError(opts?: {
+    body?: string;
+    code?: string;
+    message?: string;
+}): boolean;
 export declare function isQuotaOrPlanError(opts?: {
     status?: number;
     body?: string;

package/dist/auth/claim-hint.js

@@ -18,6 +18,13 @@ const CLAIM_NUDGE = "Claim your Free account to keep usage and upgrade: ";
  * would otherwise lose the account along with its usage history.
  */
 const SKIP_CODES = new Set(["AUTH006"]);
+/**
+ * A per-key credit cap: Fetch, Extract and Browser answer 402 AUTH014, Batch answers
+ * 402 `api_key_cap_reached`. The account still has credits and its other keys still
+ * work, so "buy credits" or "claim your account" would send the user the wrong way.
+ */
+export const KEY_CAP_CODES = new Set(["AUTH014", "api_key_cap_reached", "BATCH_KEY_CAP_REACHED"]);
+export const KEY_CAP_NUDGE = "This API key reached one of its credit caps. The account's other API keys still work. Raise or remove the cap at https://app.zenrows.com/settings/api-keys, or wait until it resets (the error detail says when).";
 function extractCode(body, code) {
     if (code && typeof code === "string")
         return code;
@@ -35,7 +42,15 @@ function extractCode(body, code) {
         return m?.[1];
     }
 }
+export function isKeyCapError(opts = {}) {
+    const code = extractCode(opts.body, opts.code);
+    if (code && KEY_CAP_CODES.has(code))
+        return true;
+    return /\b(AUTH014|api_key_cap_reached)\b/.test(`${opts.message ?? ""} ${opts.body ?? ""}`);
+}
 export function isQuotaOrPlanError(opts = {}) {
+    if (isKeyCapError(opts))
+        return false;
     const code = extractCode(opts.body, opts.code);
     if (code && SKIP_CODES.has(code))
         return false;
@@ -59,6 +74,9 @@ export function appendClaimHint(text, opts = {}) {
         code: opts.code,
         message: opts.message ?? text,
     };
+    if (isKeyCapError(probe)) {
+        return text.includes(KEY_CAP_NUDGE) ? text : `${text}\n\n${KEY_CAP_NUDGE}`;
+    }
     if (!isQuotaOrPlanError(probe))
         return text;
     const acct = readAccount();

package/dist/batch-api.js

@@ -9,7 +9,7 @@ export function batchBase() {
     const base = env && env.trim() ? env.trim() : DEFAULT_BATCH_API_BASE;
     return base.replace(/\/+$/, "");
 }
-export const TERMINAL_STATUSES = new Set(["completed", "stopped", "deleted"]);
+export const TERMINAL_STATUSES = new Set(["completed", "failed", "stopped", "deleted"]);
 export class BatchError extends Error {
     code;
     status;
@@ -118,6 +118,14 @@ function problemToError(status, body, method, path) {
             detail: cause,
         });
     }
+    if (status === 402 && serverCode === "api_key_cap_reached") {
+        return new BatchError({
+            code: "BATCH_KEY_CAP_REACHED",
+            message: "This API key reached one of its credit caps, so the Batch API refused the request. The account's other API keys still work. Raise or remove the cap at https://app.zenrows.com/settings/api-keys, or wait until it resets (see detail).",
+            status,
+            detail: cause,
+        });
+    }
     if (status === 402) {
         return new BatchError({
             code: "BATCH_QUOTA_EXCEEDED",

package/dist/server.d.ts

@@ -1,2 +1,24 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface ScrapeParams {
+    url: string;
+    js_render?: boolean | null;
+    premium_proxy?: boolean | null;
+    proxy_country?: string | null;
+    response_type?: "markdown" | "plaintext" | "pdf" | "html" | null;
+    autoparse?: boolean | null;
+    css_extractor?: string | null;
+    wait_for?: string | null;
+    wait?: number | null;
+    js_instructions?: string | null;
+    outputs?: string | null;
+    screenshot?: boolean | null;
+    screenshot_fullpage?: boolean | null;
+    screenshot_selector?: string | null;
+}
+/**
+ * Builds the Fetch query string. Uses Adaptive Stealth Mode (mode=auto) unless the
+ * agent or the env forces js_render / premium_proxy, which the API won't combine
+ * with mode=auto. Mirrors the CLI's defaultMode "auto".
+ */
+export declare function buildScrapeParams(apiKey: string, params: ScrapeParams): URLSearchParams;
 export declare function createServer(apiKey: string, clientName?: string): McpServer;

package/dist/server.js

@@ -13,6 +13,54 @@ const ZENROWS_API_URL = "https://api.zenrows.com/v1/";
 const DEFAULT_JS_RENDER = process.env.ZENROWS_JS_RENDER === "true";
 const DEFAULT_PREMIUM_PROXY = process.env.ZENROWS_PREMIUM_PROXY === "true";
 const DEFAULT_RESPONSE_TYPE = process.env.ZENROWS_RESPONSE_TYPE ?? "markdown";
+/**
+ * Builds the Fetch query string. Uses Adaptive Stealth Mode (mode=auto) unless the
+ * agent or the env forces js_render / premium_proxy, which the API won't combine
+ * with mode=auto. Mirrors the CLI's defaultMode "auto".
+ */
+export function buildScrapeParams(apiKey, params) {
+    const searchParams = new URLSearchParams({
+        apikey: apiKey,
+        url: params.url,
+    });
+    const isScreenshot = !!(params.screenshot || params.screenshot_fullpage || params.screenshot_selector);
+    const jsRender = !!params.js_render || DEFAULT_JS_RENDER;
+    const premiumProxy = !!params.premium_proxy || DEFAULT_PREMIUM_PROXY;
+    if (!jsRender && !premiumProxy) {
+        searchParams.set("mode", "auto");
+    }
+    else {
+        if (jsRender || isScreenshot)
+            searchParams.set("js_render", "true");
+        if (premiumProxy)
+            searchParams.set("premium_proxy", "true");
+    }
+    if (params.proxy_country)
+        searchParams.set("proxy_country", params.proxy_country.toUpperCase());
+    if (params.autoparse)
+        searchParams.set("autoparse", "true");
+    if (params.css_extractor)
+        searchParams.set("css_extractor", params.css_extractor);
+    if (params.wait_for)
+        searchParams.set("wait_for", params.wait_for);
+    if (params.wait != null)
+        searchParams.set("wait", String(params.wait));
+    if (params.js_instructions)
+        searchParams.set("js_instructions", params.js_instructions);
+    if (params.outputs)
+        searchParams.set("outputs", params.outputs);
+    if (isScreenshot)
+        searchParams.set("screenshot", "true");
+    if (params.screenshot_fullpage)
+        searchParams.set("screenshot_fullpage", "true");
+    if (params.screenshot_selector)
+        searchParams.set("screenshot_selector", params.screenshot_selector);
+    const effectiveType = params.response_type ?? DEFAULT_RESPONSE_TYPE;
+    if (!params.autoparse && !params.css_extractor && !params.outputs && !isScreenshot && effectiveType !== "html") {
+        searchParams.set("response_type", effectiveType);
+    }
+    return searchParams;
+}
 export function createServer(apiKey, clientName) {
     const server = new McpServer({
         name: "zenrows",
@@ -34,35 +82,38 @@ Use for full-page content (markdown/HTML/PDF/screenshot). For structured JSON
 fields (products, articles, listings), prefer the extract tool when it fits —
 it returns parsed fields instead of a full page body.
 
-When to enable options:
-- js_render: page uses React/Vue/Angular, loads content dynamically, or content
-  appears missing on the first attempt
-- premium_proxy: site returns 403/blocked errors even with js_render enabled
-- wait_for: specific content loads after initial render (requires js_render)
+By default the request uses Adaptive Stealth Mode: Zenrows picks JS rendering
+and premium proxies per page, escalates only when the site blocks, and charges
+only for the configuration that succeeds. Pass just the URL for protected,
+dynamic, or blocked pages; do not turn on js_render or premium_proxy to get past
+a block.
+
+Set js_render or premium_proxy only to force a fixed configuration. Doing so
+switches off Adaptive Stealth Mode, and every request is billed at that
+configuration's cost (premium_proxy with js_render is 25x a basic request).
 
 Examples:
-  Basic:    { url: "https://example.com" }
-  Dynamic:  { url: "https://spa.com", js_render: true }
-  Protected:{ url: "https://protected.com", js_render: true, premium_proxy: true }`,
+  Default:  { url: "https://example.com" }
+  Geo:      { url: "https://example.com", proxy_country: "US" }
+  Forced:   { url: "https://spa.com", js_render: true }`,
         inputSchema: {
             url: z.string().url().describe("The webpage URL to scrape"),
             js_render: z
                 .boolean()
                 .nullish()
-                .default(false)
-                .describe("Enable JavaScript rendering via headless browser. Required for SPAs " +
-                "(React, Vue, Angular) and pages that load content dynamically."),
+                .describe("Force JavaScript rendering on every request. Overrides Adaptive Stealth Mode, " +
+                "which already renders JavaScript when a page needs it. Leave unset unless you need a fixed configuration."),
             premium_proxy: z
                 .boolean()
                 .nullish()
-                .default(false)
-                .describe("Use premium residential proxies to bypass anti-bot protection. " +
-                "Required for heavily protected sites. Implies higher credit cost."),
+                .describe("Force premium residential proxies on every request (10x credit cost). Overrides " +
+                "Adaptive Stealth Mode, which already escalates to premium proxies when a site blocks. " +
+                "Leave unset unless you need a fixed configuration."),
             proxy_country: z
                 .string()
                 .nullish()
                 .describe("Country for geo-targeted scraping. ISO 3166-1 alpha-2 code (e.g. 'US', 'GB', 'DE'). " +
-                "Requires premium_proxy=true."),
+                "Works in Adaptive Stealth Mode; if you set js_render without premium_proxy, it requires premium_proxy=true."),
             response_type: z
                 .enum(["markdown", "plaintext", "pdf", "html"])
                 .nullish()
@@ -87,7 +138,7 @@ Examples:
                 .string()
                 .nullish()
                 .describe("CSS selector to wait for before capturing. Use when key content loads " +
-                "after the initial page render. Requires js_render=true."),
+                "after the initial page render. Works in Adaptive Stealth Mode or with js_render=true."),
             wait: z
                 .number()
                 .int()
@@ -95,11 +146,11 @@ Examples:
                 .max(30000)
                 .nullish()
                 .describe("Milliseconds to wait after page load before capturing content. " +
-                "Max 30000 (30s). Requires js_render=true."),
+                "Max 30000 (30s). Works in Adaptive Stealth Mode or with js_render=true."),
             js_instructions: z
                 .string()
                 .nullish()
-                .describe("JSON array of browser interactions to run before scraping. Requires js_render=true. " +
+                .describe("JSON array of browser interactions to run before scraping. Works in Adaptive Stealth Mode or with js_render=true. " +
                 'Example: [{"click":"#load-more"},{"wait":1000},{"wait_for":".results"}]'),
             outputs: z
                 .string()
@@ -124,45 +175,7 @@ Examples:
                 'Example: ".product-card". Returns an image instead of text content.'),
         },
     }, async (params) => {
-        const searchParams = new URLSearchParams({
-            apikey: apiKey,
-            url: params.url,
-        });
-        if (params.js_render ||
-            DEFAULT_JS_RENDER ||
-            params.screenshot ||
-            params.screenshot_fullpage ||
-            params.screenshot_selector)
-            searchParams.set("js_render", "true");
-        if (params.premium_proxy || DEFAULT_PREMIUM_PROXY)
-            searchParams.set("premium_proxy", "true");
-        if (params.proxy_country)
-            searchParams.set("proxy_country", params.proxy_country.toUpperCase());
-        if (params.autoparse)
-            searchParams.set("autoparse", "true");
-        if (params.css_extractor)
-            searchParams.set("css_extractor", params.css_extractor);
-        if (params.wait_for)
-            searchParams.set("wait_for", params.wait_for);
-        if (params.wait != null)
-            searchParams.set("wait", String(params.wait));
-        if (params.js_instructions)
-            searchParams.set("js_instructions", params.js_instructions);
-        if (params.outputs)
-            searchParams.set("outputs", params.outputs);
-        if (params.screenshot || params.screenshot_fullpage || params.screenshot_selector)
-            searchParams.set("screenshot", "true");
-        if (params.screenshot_fullpage)
-            searchParams.set("screenshot_fullpage", "true");
-        if (params.screenshot_selector)
-            searchParams.set("screenshot_selector", params.screenshot_selector);
-        // response_type is mutually exclusive with autoparse, css_extractor, outputs, and screenshot params.
-        // 'html' is the Zenrows default (no param); all other values are passed through.
-        const isScreenshot = params.screenshot || params.screenshot_fullpage || params.screenshot_selector;
-        const effectiveType = params.response_type ?? DEFAULT_RESPONSE_TYPE;
-        if (!params.autoparse && !params.css_extractor && !params.outputs && !isScreenshot && effectiveType !== "html") {
-            searchParams.set("response_type", effectiveType);
-        }
+        const searchParams = buildScrapeParams(apiKey, params);
         let response;
         try {
             response = await fetch(`${ZENROWS_API_URL}?${searchParams}`, {
@@ -265,7 +278,7 @@ Examples:
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Scrape ${url} using the Zenrows MCP scrape tool with js_render set to true. The page requires JavaScript execution to load its content. Return the full rendered content in markdown format.`,
+                    text: `Scrape ${url} using the Zenrows MCP scrape tool. Pass only the URL: Adaptive Stealth Mode renders JavaScript when the page needs it. Return the full rendered content in markdown format.`,
                 },
             },
         ],

package/dist/tools/account.js

@@ -92,7 +92,13 @@ human does not want to wait for the renewal, relay the way to continue now: add
 credit pack at https://app.zenrows.com/billing?topup=open (opens the purchase
 directly) or upgrade at https://app.zenrows.com/plans. Prices are per plan; quote them
 only from this tool's response, never from memory.
-AUTH006 is the concurrency limit, which is a different thing entirely.`,
+AUTH006 is the concurrency limit, which is a different thing entirely.
+
+AUTH014 (Batch: api_key_cap_reached) is different from AUTH004: the account still has
+credits, but this API key hit one of its own credit caps. Other keys keep working. The
+response's api_key.caps lists the calling key's caps: window, credits, used_credits,
+remaining_credits, resets_at, and unavailable (usage could not be read). Relay the
+resets_at time, or raise or remove the cap at https://app.zenrows.com/settings/api-keys.`,
         inputSchema: {},
     }, async () => runAccountUsage(apiKey, opts));
 }

package/dist/tools/batch.js

@@ -215,7 +215,7 @@ Download result_url soon — presigned links expire.`,
     });
     server.registerTool("batch_wait", {
         annotations: { title: "Wait for Batch Job", readOnlyHint: true, destructiveHint: false },
-        description: "Poll batch_status until the job reaches a terminal state (completed, stopped, or deleted).",
+        description: "Poll batch_status until the job reaches a terminal state (completed, failed, stopped, or deleted). A run that hits an API key credit cap ends as failed with failure_reason api_key_cap_reached.",
         inputSchema: {
             job_id: z.string().describe("Batch job id"),
             timeout_ms: z

package/dist/tools/browser-fetch.js

@@ -19,12 +19,28 @@ export async function browserFetch(method, path, apiKey, browserUrl, body, clien
     let data;
     const contentType = response.headers.get("content-type") ?? "";
     const text = await response.text();
-    data = contentType.includes("application/json") && text ? JSON.parse(text) : text;
+    // Errors come back as application/problem+json (e.g. 402 AUTH014), so match any JSON type.
+    data = text;
+    if (text && /[/+]json\b/.test(contentType)) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            // keep the raw text
+        }
+    }
     return { ok: response.ok, status: response.status, data };
 }
 export function browserError(result) {
     if (typeof result.data === "object" && result.data !== null && "error" in result.data) {
         return String(result.data.error);
     }
+    if (typeof result.data === "object" && result.data !== null && "code" in result.data) {
+        const d = result.data;
+        return `HTTP ${result.status} (${String(d.code)}): ${String(d.detail ?? d.title ?? "")}`.trim();
+    }
+    if (typeof result.data === "string" && result.data.trim()) {
+        return `HTTP ${result.status}: ${result.data.trim().slice(0, 300)}`;
+    }
     return `HTTP ${result.status}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/mcp",
-  "version": "2.2.4",
+  "version": "2.4.0",
   "description": "Zenrows MCP server — Fetch, Extract, Batch, and Browser Sessions for AI coding assistants",
   "type": "module",
   "bin": {