@zenrows/mcp 2.2.0 → 2.2.3

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

@@ -0,0 +1,16 @@
+export declare function isQuotaOrPlanError(opts?: {
+    status?: number;
+    body?: string;
+    code?: string;
+    message?: string;
+}): boolean;
+/**
+ * If the local agent account is still unclaimed and this looks like a quota/plan
+ * failure, append the claim URL so agents can nudge the user.
+ */
+export declare function appendClaimHint(text: string, opts?: {
+    status?: number;
+    body?: string;
+    code?: string;
+    message?: string;
+}): string;

package/dist/auth/claim-hint.js

@@ -0,0 +1,71 @@
+/**
+ * Append a claim-account nudge when an unclaimed Free agent hits quota/plan limits.
+ */
+import { readAccount } from "./ensure-key.js";
+const CLAIM_NUDGE = "Claim your Free account to keep usage and upgrade: ";
+/**
+ * Codes that are not an allowance problem, so a claim nudge would be noise.
+ *
+ * AUTH006 is the concurrency limit, and is belt-and-braces: it comes back as 429, so it
+ * would not reach the 402 branch below in the first place. It is listed to keep the
+ * intent legible rather than because anything depends on it.
+ *
+ * AUTH004 used to be listed here on the belief that it
+ * was concurrency too — it is not. AUTH004 is "Usage Exceeded": the allowance itself is
+ * spent (docs `api-error-codes#AUTH004`; gateway logs carry `err: "usage exceeded"`,
+ * `msg: "user allowance failure"`). Skipping it suppressed the nudge at the one moment it
+ * is worth the most — an unclaimed Free agent that has just run through its allowance and
+ * would otherwise lose the account along with its usage history.
+ */
+const SKIP_CODES = new Set(["AUTH006"]);
+function extractCode(body, code) {
+    if (code && typeof code === "string")
+        return code;
+    if (!body)
+        return undefined;
+    try {
+        const j = JSON.parse(body);
+        if (typeof j.code === "string")
+            return j.code;
+        const m = typeof j.error === "string" ? j.error.match(/\((AUTH\d+)\)/) : null;
+        return m?.[1];
+    }
+    catch {
+        const m = body.match(/\b(AUTH\d+|BATCH_QUOTA_EXCEEDED)\b/);
+        return m?.[1];
+    }
+}
+export function isQuotaOrPlanError(opts = {}) {
+    const code = extractCode(opts.body, opts.code);
+    if (code && SKIP_CODES.has(code))
+        return false;
+    if (opts.status === 402)
+        return true;
+    if (code === "BATCH_QUOTA_EXCEEDED")
+        return true;
+    const hay = `${opts.message ?? ""} ${opts.body ?? ""} ${code ?? ""}`;
+    if (/\bHTTP\s*402\b/i.test(hay) || /\berror\s+402\b/i.test(hay))
+        return true;
+    return /\b(no credit|credits?\s+(exhausted|exceeded|available)|quota exceeded|subscription has no credit)\b/i.test(hay);
+}
+/**
+ * If the local agent account is still unclaimed and this looks like a quota/plan
+ * failure, append the claim URL so agents can nudge the user.
+ */
+export function appendClaimHint(text, opts = {}) {
+    const probe = {
+        status: opts.status,
+        body: opts.body ?? text,
+        code: opts.code,
+        message: opts.message ?? text,
+    };
+    if (!isQuotaOrPlanError(probe))
+        return text;
+    const acct = readAccount();
+    if (!acct?.unclaimed || !acct.claimUrl)
+        return text;
+    const hint = `${CLAIM_NUDGE}${acct.claimUrl}`;
+    if (text.includes(acct.claimUrl) || text.includes(CLAIM_NUDGE.trim()))
+        return text;
+    return `${text}\n\n${hint}`;
+}

package/dist/http.js

@@ -28,6 +28,27 @@ function extractApiKey(req) {
 }
 const AUTH_SERVER = process.env.OAUTH_AUTH_SERVER ?? "https://app.zenrows.com";
 const MCP_SERVER = process.env.MCP_SERVER ?? "https://mcp.zenrows.com";
+/**
+ * The scope this resource issues, named after what it actually grants.
+ *
+ * The access token IS the account's Zenrows API key: the authorization server hands
+ * the key back at /oauth/mcp/token, and every tool here calls the API with it. So an
+ * approved client can do anything the key can do, and one scope named `api` is the
+ * whole truth.
+ *
+ * It used to be declared as `[]`, which is worse than saying nothing: an empty list
+ * reads to a least-privilege client as "this resource has no scopes", when what we
+ * meant was "we never wrote them down".
+ *
+ * Splitting this — reading a page under one scope, spending credits on a
+ * 100,000-URL batch under another — is not an edit to this array. The token would
+ * have to carry the grant, and today it cannot: it is an opaque API key, minted by
+ * app.zenrows.com, and a raw key pasted straight into the Authorization header is a
+ * supported way to connect. Until the token can say what it was granted, this list
+ * must not claim more than one, because a scope we do not enforce is a lie told to
+ * exactly the clients careful enough to read it.
+ */
+const SCOPES_SUPPORTED = ["api"];
 app.get("/mcp/.well-known/oauth-authorization-server", (c) => c.redirect("/.well-known/oauth-authorization-server", 301));
 // RFC 9728 — OAuth Protected Resource Metadata
 // MCP clients fetch this first to discover the authorization server(s) for this resource.
@@ -35,7 +56,8 @@ app.get("/.well-known/oauth-protected-resource", (c) => c.json({
     resource: MCP_SERVER,
     authorization_servers: [MCP_SERVER],
     bearer_methods_supported: ["header", "query"],
-    scopes_supported: [],
+    scopes_supported: SCOPES_SUPPORTED,
+    resource_documentation: "https://docs.zenrows.com",
 }));
 // RFC 8414 — OAuth Authorization Server Metadata
 // Issuer must match the URL of the server serving this document (MCP_SERVER, not AUTH_SERVER),
@@ -49,6 +71,7 @@ app.get("/.well-known/oauth-authorization-server", (c) => c.json({
     grant_types_supported: ["authorization_code"],
     code_challenge_methods_supported: ["S256"],
     token_endpoint_auth_methods_supported: ["none"],
+    scopes_supported: SCOPES_SUPPORTED,
 }));
 // MCP Server Card (SEP-2127 canonical + SEP-1649 legacy paths).
 // Lets agents discover this remote MCP before connecting.
@@ -57,7 +80,7 @@ function mcpServerCard() {
         $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
         name: "io.zenrows/mcp",
         version: pkg.version,
-        description: "ZenRows MCP — scrape and extract from protected sites via the Universal Scraper API (anti-bot bypass, JS rendering, proxies).",
+        description: "Zenrows MCP — scrape and extract from protected sites via Fetch (anti-bot bypass, JS rendering, proxies).",
         websiteUrl: "https://www.zenrows.com/mcp",
         remotes: [
             {
@@ -71,9 +94,9 @@ function mcpServerCard() {
         // Older SEP-1649-shaped fields some scanners still expect.
         protocolVersion: "2025-06-18",
         serverInfo: {
-            name: "ZenRows",
+            name: "Zenrows",
             version: pkg.version,
-            description: "ZenRows Universal Scraper API via MCP",
+            description: "Zenrows Fetch API via MCP",
             homepage: "https://www.zenrows.com/mcp",
         },
         transport: {
@@ -135,10 +158,12 @@ app.all("/mcp", async (c) => {
         return c.json({
             error: "Missing API key. Use Authorization: Bearer <key> header or ?apikey=<key> query param.",
         }, 401, {
-            "WWW-Authenticate": `Bearer realm="${AUTH_SERVER}", resource_metadata="${MCP_SERVER}/.well-known/oauth-protected-resource"`,
+            // RFC 6750: name the scope in the challenge too, so a client learns what it is
+            // being asked for without a second fetch of the metadata document.
+            "WWW-Authenticate": `Bearer realm="${AUTH_SERVER}", scope="${SCOPES_SUPPORTED.join(" ")}", resource_metadata="${MCP_SERVER}/.well-known/oauth-protected-resource"`,
             // CloudFront strips WWW-Authenticate — add Link header as RFC 8615 fallback
             // so MCP clients can still discover the OAuth server
-            "Link": `<${MCP_SERVER}/.well-known/oauth-protected-resource>; rel="oauth-protected-resource"`,
+            Link: `<${MCP_SERVER}/.well-known/oauth-protected-resource>; rel="oauth-protected-resource"`,
         });
     }
     const transport = new WebStandardStreamableHTTPServerTransport({

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "module";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { AuthError, ensureApiKey, getZenrowsDir, resolveApiKey, } from "./auth/ensure-key.js";
+import { AuthError, ensureApiKey, getZenrowsDir, resolveApiKey } from "./auth/ensure-key.js";
 import { createServer } from "./server.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -12,8 +12,7 @@ try {
         process.stderr.write(`Using existing API key from ${existing.source} (secrets dir: ${getZenrowsDir()})\n`);
     }
     else {
-        const signup = process.env.ZENROWS_AGENT_SIGNUP_URL?.trim() ||
-            "https://app.zenrows.com/api/agent/signup (default prod)";
+        const signup = process.env.ZENROWS_AGENT_SIGNUP_URL?.trim() || "https://app.zenrows.com/api/agent/signup (default prod)";
         process.stderr.write(`No API key — will auto-signup via: ${signup}\n`);
     }
     const resolved = await ensureApiKey({

package/dist/server.js

@@ -1,7 +1,9 @@
 import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { appendClaimHint } from "./auth/claim-hint.js";
 import { getZenrowsDir, readAccount } from "./auth/ensure-key.js";
+import { registerAccountTools } from "./tools/account.js";
 import { registerBatchTools } from "./tools/batch.js";
 import { registerBrowserTools } from "./tools/browser.js";
 import { registerExtractTool } from "./tools/extract.js";
@@ -158,11 +160,7 @@ Examples:
         // '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") {
+        if (!params.autoparse && !params.css_extractor && !params.outputs && !isScreenshot && effectiveType !== "html") {
             searchParams.set("response_type", effectiveType);
         }
         let response;
@@ -188,8 +186,12 @@ Examples:
         }
         if (!response.ok) {
             const body = await response.text();
+            const text = appendClaimHint(`Zenrows error ${response.status}: ${body}`, {
+                status: response.status,
+                body,
+            });
             return {
-                content: [{ type: "text", text: `Zenrows error ${response.status}: ${body}` }],
+                content: [{ type: "text", text }],
                 isError: true,
             };
         }
@@ -270,6 +272,7 @@ Examples:
     }));
     registerExtractTool(server, apiKey, getClientName);
     registerBatchTools(server, apiKey);
+    registerAccountTools(server, apiKey);
     const BROWSER_URL = process.env.ZENROWS_BROWSER_URL ?? "https://mcp.zenrows.com";
     registerBrowserTools(server, apiKey, BROWSER_URL, getClientName);
     // Always expose account resource; handler re-reads disk so ZENROWS_HOME is visible.

package/dist/tools/account.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type TextContent = {
+    type: "text";
+    text: string;
+};
+export type AccountOpts = {
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Read the plan's usage. Split out from the handler so it can be exercised without an
+ * MCP server or a live account — the endpoint is the one thing here we cannot try
+ * against production from a test.
+ */
+export declare function runAccountUsage(apiKey: string, opts?: AccountOpts): Promise<{
+    content: TextContent[];
+}>;
+export declare function registerAccountTools(server: McpServer, apiKey: string, opts?: AccountOpts): void;
+export {};

package/dist/tools/account.js

@@ -0,0 +1,98 @@
+import { createRequire } from "module";
+import { appendClaimHint } from "../auth/claim-hint.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+/**
+ * Let an agent read its own allowance before it runs out of it.
+ *
+ * Until now nothing on this server could answer "how many credits do I have left?".
+ * Responses carry `X-Request-Cost` and `X-Request-Credits` — what a call *cost*, after
+ * the fact — but no counterpart to `Concurrency-Limit` / `Concurrency-Remaining`, so an
+ * agent could total its own spend and still not know the ceiling. It found out by
+ * hitting a 402 telling it to buy a subscription (ACT-1581, ACT-1577).
+ *
+ * `/v1/subscriptions/self/details` has always had the answer. It does not count against
+ * concurrency, which is what makes it safe to call before a batch or on a retry.
+ */
+const SUBSCRIPTION_DETAILS_URL = "https://api.zenrows.com/v1/subscriptions/self/details";
+function err(text, opts = {}) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: appendClaimHint(text, {
+                    status: opts.status,
+                    body: opts.body ?? text,
+                    message: text,
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+function json(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+/**
+ * Read the plan's usage. Split out from the handler so it can be exercised without an
+ * MCP server or a live account — the endpoint is the one thing here we cannot try
+ * against production from a test.
+ */
+export async function runAccountUsage(apiKey, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(SUBSCRIPTION_DETAILS_URL, {
+            headers: {
+                "X-API-Key": apiKey,
+                "User-Agent": `zenrows-mcp/${pkg.version}`,
+            },
+        });
+    }
+    catch (e) {
+        return err(`Could not reach the Zenrows subscription endpoint: ${e.message}`);
+    }
+    const body = await res.text();
+    if (!res.ok) {
+        return err(`Zenrows returned ${res.status} for the subscription details endpoint.\n${body}`, {
+            status: res.status,
+            body,
+        });
+    }
+    // Passed through verbatim. The response shape is not part of any documented contract,
+    // so reshaping it here would mean inventing field names that could drift away from
+    // what the API actually sends.
+    try {
+        return json(JSON.parse(body));
+    }
+    catch {
+        return json({ raw: body });
+    }
+}
+export function registerAccountTools(server, apiKey, opts = {}) {
+    server.registerTool("account_usage", {
+        annotations: {
+            title: "Check Credit Usage",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        description: `Read the current plan's credit allowance and how much of it is spent.
+
+Call this BEFORE a large batch, and after any 402 / AUTH004, to find out whether the
+account is out of credits and when the allowance renews. It is free and does not consume
+a concurrency slot, so it is safe to poll between runs.
+
+Credit costs per request: 1 basic, 5 js_render, 10 premium_proxy, 25 both. On a small
+plan a few hundred protected requests can exhaust a month, so check before fanning out.
+
+AUTH004 ("usage exceeded") means this allowance is spent. It renews at the end of the
+billing period, so it is not a permanent block: never retry-loop against it. If the
+human does not want to wait for the renewal, relay the way to continue now: add a
+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.`,
+        inputSchema: {},
+    }, async () => runAccountUsage(apiKey, opts));
+}

package/dist/tools/batch.js

@@ -1,11 +1,23 @@
 import { createRequire } from "module";
 import { z } from "zod";
-import { BatchError, createJob, getJob, listResults, stopJob, waitForJob, } from "../batch-api.js";
+import { appendClaimHint } from "../auth/claim-hint.js";
+import { BatchError, createJob, getJob, listResults, stopJob, waitForJob } from "../batch-api.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
-function err(data) {
+function err(data, hint) {
+    const raw = typeof data === "string" ? data : JSON.stringify(data);
     return {
-        content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data) }],
+        content: [
+            {
+                type: "text",
+                text: appendClaimHint(raw, {
+                    status: hint?.status,
+                    code: hint?.code,
+                    message: hint?.message ?? raw,
+                    body: raw,
+                }),
+            },
+        ],
         isError: true,
     };
 }
@@ -13,8 +25,9 @@ function json(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
 function batchErr(e) {
-    if (e instanceof BatchError)
-        return err(e.toJSON());
+    if (e instanceof BatchError) {
+        return err(e.toJSON(), { status: e.status, code: e.code, message: e.message });
+    }
     return err({
         code: "BATCH_FAILED",
         message: e instanceof Error ? e.message : String(e),
@@ -70,18 +83,12 @@ If you get BATCH_ACCESS_DENIED, the account lacks Batch beta access.`,
                 .string()
                 .optional()
                 .describe("Job-level ISO country code (requires premium_proxy or mode=auto)"),
-            response_type: z
-                .enum(["markdown", "plaintext", "html", "pdf"])
-                .optional()
-                .describe("Job-level response_type"),
+            response_type: z.enum(["markdown", "plaintext", "html", "pdf"]).optional().describe("Job-level response_type"),
             zenrows_params: z
                 .record(z.union([z.string(), z.number(), z.boolean()]))
                 .optional()
                 .describe("Additional job-level zenrows_params merged with the flags above"),
-            wait: z
-                .boolean()
-                .optional()
-                .describe("If true, poll until the job reaches a terminal state before returning"),
+            wait: z.boolean().optional().describe("If true, poll until the job reaches a terminal state before returning"),
             wait_timeout_ms: z
                 .number()
                 .int()
@@ -91,9 +98,7 @@ If you get BATCH_ACCESS_DENIED, the account lacks Batch beta access.`,
                 .describe("Max wait time when wait=true (default 600000)"),
         },
     }, async (params) => {
-        const tasksIn = params.tasks && params.tasks.length > 0
-            ? params.tasks
-            : (params.urls ?? []).map((url) => ({ url }));
+        const tasksIn = params.tasks && params.tasks.length > 0 ? params.tasks : (params.urls ?? []).map((url) => ({ url }));
         if (!tasksIn.length) {
             return err({
                 code: "INVALID_USAGE",
@@ -122,9 +127,7 @@ If you get BATCH_ACCESS_DENIED, the account lacks Batch beta access.`,
                     task.zenrows_params = normalizeParams(t.zenrows_params);
                 return task;
             }),
-            ...(Object.keys(jobParams).length
-                ? { zenrows_params: normalizeParams(jobParams) }
-                : {}),
+            ...(Object.keys(jobParams).length ? { zenrows_params: normalizeParams(jobParams) } : {}),
         };
         try {
             const job = await createJob(body, call);
@@ -177,10 +180,7 @@ Each row may include task_id, external_id, status, and a short-lived result_url
 Download result_url soon — presigned links expire.`,
         inputSchema: {
             job_id: z.string().describe("Batch job id"),
-            status: z
-                .enum(["successful", "failed", "all"])
-                .optional()
-                .describe("Filter results by status (default: all)"),
+            status: z.enum(["successful", "failed", "all"]).optional().describe("Filter results by status (default: all)"),
         },
     }, async ({ job_id, status }) => {
         try {

package/dist/tools/browser.js

@@ -1,10 +1,14 @@
 import { z } from "zod";
+import { appendClaimHint } from "../auth/claim-hint.js";
 import { browserFetch, browserError } from "./browser-fetch.js";
 function ok() {
     return { content: [{ type: "text", text: JSON.stringify({ ok: true }) }] };
 }
 function err(msg) {
-    return { content: [{ type: "text", text: msg }], isError: true };
+    return {
+        content: [{ type: "text", text: appendClaimHint(msg, { body: msg, message: msg }) }],
+        isError: true,
+    };
 }
 function json(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
@@ -14,7 +18,11 @@ export function registerBrowserTools(server, apiKey, browserUrl, getClientName)
     const tfetch = (toolName) => (method, path, body) => browserFetch(method, path, apiKey, browserUrl, body, getClientName(), toolName);
     // ─── Session ─────────────────────────────────────────────────────────────
     server.registerTool("browser_navigate", {
-        annotations: { title: "Open Browser & Navigate", readOnlyHint: false, destructiveHint: false },
+        annotations: {
+            title: "Open Browser & Navigate",
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
         description: `Open a Zenrows Browser Sessions session and navigate to a URL.
 
 This is the entry point for all browser automation. It creates a new session backed by
@@ -32,7 +40,10 @@ When to use options:
                 .string()
                 .optional()
                 .describe("ISO 3166-1 alpha-2 country code for geo-targeted proxy (e.g. 'US', 'GB', 'DE')"),
-            proxy_region: z.string().optional().describe("World region code for geo-targeted proxy (eu=Europe, na=North America, ap=Asia Pacific, sa=South America, af=Africa, me=Middle East)"),
+            proxy_region: z
+                .string()
+                .optional()
+                .describe("World region code for geo-targeted proxy (eu=Europe, na=North America, ap=Asia Pacific, sa=South America, af=Africa, me=Middle East)"),
         },
     }, async (params) => {
         const fetch = tfetch("browser_navigate");
@@ -51,7 +62,9 @@ When to use options:
         const session = result.data;
         let navResult;
         try {
-            navResult = await fetch("POST", `/browser/sessions/${session.session_id}/navigate`, { url: params.url });
+            navResult = await fetch("POST", `/browser/sessions/${session.session_id}/navigate`, {
+                url: params.url,
+            });
         }
         catch (e) {
             // Best-effort cleanup — session was created but navigation failed, free the slot.
@@ -63,7 +76,12 @@ When to use options:
             return err(`Navigation failed: ${browserError(navResult)}`);
         }
         const nav = navResult.data;
-        return json({ session_id: session.session_id, url: nav.url, title: nav.title, expires_at: session.expires_at });
+        return json({
+            session_id: session.session_id,
+            url: nav.url,
+            title: nav.title,
+            expires_at: session.expires_at,
+        });
     });
     server.registerTool("browser_close", {
         annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: false },
@@ -181,7 +199,11 @@ When to use options:
     }, async ({ session_id, selector, text, clear_first }) => {
         const fetch = tfetch("browser_type");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/type`, { selector, text, clear_first });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/type`, {
+                selector,
+                text,
+                clear_first,
+            });
             if (!result.ok)
                 return err(`Type failed: ${browserError(result)}`);
             return ok();
@@ -201,7 +223,10 @@ When to use options:
     }, async ({ session_id, selector, value }) => {
         const fetch = tfetch("browser_fill");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/fill`, { selector, value });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/fill`, {
+                selector,
+                value,
+            });
             if (!result.ok)
                 return err(`Fill failed: ${browserError(result)}`);
             return ok();
@@ -221,7 +246,10 @@ When to use options:
     }, async ({ session_id, selector, value }) => {
         const fetch = tfetch("browser_select_option");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/select`, { selector, value });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/select`, {
+                selector,
+                value,
+            });
             if (!result.ok)
                 return err(`Select failed: ${browserError(result)}`);
             return ok();
@@ -317,7 +345,10 @@ When to use options:
     }, async ({ session_id, direction, distance }) => {
         const fetch = tfetch("browser_scroll");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/scroll`, { direction, distance });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/scroll`, {
+                direction,
+                distance,
+            });
             if (!result.ok)
                 return err(`Scroll failed: ${browserError(result)}`);
             return ok();
@@ -416,7 +447,9 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, selector }) => {
         const fetch = tfetch("browser_get_text");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/get_text`, { selector });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/get_text`, {
+                selector,
+            });
             if (!result.ok)
                 return err(`Failed to get text: ${browserError(result)}`);
             const data = result.data;
@@ -437,7 +470,10 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, selector, attribute }) => {
         const fetch = tfetch("browser_get_attribute");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/get_attribute`, { selector, attribute });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/get_attribute`, {
+                selector,
+                attribute,
+            });
             if (!result.ok)
                 return err(`Failed to get attribute: ${browserError(result)}`);
             return json(result.data);
@@ -456,7 +492,9 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, selector }) => {
         const fetch = tfetch("browser_get_html");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/get_html`, { selector });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/get_html`, {
+                selector,
+            });
             if (!result.ok)
                 return err(`Failed to get HTML: ${browserError(result)}`);
             const data = result.data;
@@ -467,7 +505,11 @@ labels, and states — everything needed to drive browser interactions.`,
         }
     });
     server.registerTool("browser_query_selector_all", {
-        annotations: { title: "Query All Matching Elements", readOnlyHint: true, destructiveHint: false },
+        annotations: {
+            title: "Query All Matching Elements",
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
         description: "Find all elements matching a CSS selector and return their text, HTML, and attributes.",
         inputSchema: {
             session_id: sessionId,
@@ -476,7 +518,9 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, selector }) => {
         const fetch = tfetch("browser_query_selector_all");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/query_selector_all`, { selector });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/query_selector_all`, {
+                selector,
+            });
             if (!result.ok)
                 return err(`Query failed: ${browserError(result)}`);
             return json(result.data);
@@ -491,7 +535,10 @@ labels, and states — everything needed to drive browser interactions.`,
         description: "Take a screenshot of the current page or a specific element. Use for visual verification or when the accessibility tree is not sufficient.",
         inputSchema: {
             session_id: sessionId,
-            full_page: z.boolean().optional().describe("Capture full page including content below the fold (default false)"),
+            full_page: z
+                .boolean()
+                .optional()
+                .describe("Capture full page including content below the fold (default false)"),
             selector: z
                 .string()
                 .optional()
@@ -500,7 +547,10 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, full_page, selector }) => {
         const fetch = tfetch("browser_screenshot");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/screenshot`, { full_page, selector });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/screenshot`, {
+                full_page,
+                selector,
+            });
             if (!result.ok)
                 return err(`Screenshot failed: ${browserError(result)}`);
             const data = result.data;
@@ -530,7 +580,11 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, print_background, landscape, scale }) => {
         const fetch = tfetch("browser_generate_pdf");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/generate_pdf`, { print_background, landscape, scale });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/generate_pdf`, {
+                print_background,
+                landscape,
+                scale,
+            });
             if (!result.ok)
                 return err(`PDF generation failed: ${browserError(result)}`);
             const data = result.data;
@@ -558,12 +612,18 @@ labels, and states — everything needed to drive browser interactions.`,
         inputSchema: {
             session_id: sessionId,
             selector: z.string().describe("CSS selector to wait for"),
-            visible: z.boolean().optional().describe("Also require the element to be visible, not just present in the DOM (default false)"),
+            visible: z
+                .boolean()
+                .optional()
+                .describe("Also require the element to be visible, not just present in the DOM (default false)"),
         },
     }, async ({ session_id, selector, visible }) => {
         const fetch = tfetch("browser_wait_for_selector");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/wait_for_selector`, { selector, visible });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/wait_for_selector`, {
+                selector,
+                visible,
+            });
             if (!result.ok)
                 return err(`Wait for selector failed: ${browserError(result)}`);
             return ok();
@@ -577,7 +637,13 @@ labels, and states — everything needed to drive browser interactions.`,
         description: "Wait for the page to navigate to a new URL. IMPORTANT: call this BEFORE the action that triggers navigation (e.g. before browser_click on a submit button), not after — the navigation event may already have fired and this will hang until timeout. If the page stays on the same URL (AJAX/SPA), skip this tool entirely. Optional timeout_ms (default 30000ms).",
         inputSchema: {
             session_id: sessionId,
-            timeout_ms: z.number().int().min(1000).max(60000).optional().describe("How long to wait in milliseconds (default 30000, max 60000)"),
+            timeout_ms: z
+                .number()
+                .int()
+                .min(1000)
+                .max(60000)
+                .optional()
+                .describe("How long to wait in milliseconds (default 30000, max 60000)"),
         },
     }, async ({ session_id, timeout_ms }) => {
         const fetch = tfetch("browser_wait_for_navigation");
@@ -669,7 +735,9 @@ labels, and states — everything needed to drive browser interactions.`,
         try {
             // Remap http_only → httpOnly to match Chrome DevTools Protocol / Rod's JSON field names.
             const mapped = cookies.map(({ http_only, ...rest }) => ({ ...rest, httpOnly: http_only }));
-            const result = await fetch("POST", `/browser/sessions/${session_id}/cookies`, { cookies: mapped });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/cookies`, {
+                cookies: mapped,
+            });
             if (!result.ok)
                 return err(`Failed to set cookies: ${browserError(result)}`);
             return ok();
@@ -707,7 +775,11 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, action, key, value }) => {
         const fetch = tfetch("browser_local_storage");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/local_storage`, { action, key, value });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/local_storage`, {
+                action,
+                key,
+                value,
+            });
             if (!result.ok)
                 return err(`Local storage operation failed: ${browserError(result)}`);
             return json(result.data);
@@ -746,7 +818,9 @@ labels, and states — everything needed to drive browser interactions.`,
     }, async ({ session_id, tab_id }) => {
         const fetch = tfetch("browser_switch_tab");
         try {
-            const result = await fetch("POST", `/browser/sessions/${session_id}/switch_tab`, { tab_id });
+            const result = await fetch("POST", `/browser/sessions/${session_id}/switch_tab`, {
+                tab_id,
+            });
             if (!result.ok)
                 return err(`Failed to switch tab: ${browserError(result)}`);
             return ok();
@@ -763,14 +837,23 @@ labels, and states — everything needed to drive browser interactions.`,
         z.object({ type: z.literal("reload") }),
         z.object({ type: z.literal("click"), selector: z.string() }),
         z.object({ type: z.literal("hover"), selector: z.string() }),
-        z.object({ type: z.literal("type"), selector: z.string(), text: z.string(), clear_first: z.boolean().optional() }),
+        z.object({
+            type: z.literal("type"),
+            selector: z.string(),
+            text: z.string(),
+            clear_first: z.boolean().optional(),
+        }),
         z.object({ type: z.literal("fill"), selector: z.string(), value: z.string() }),
         z.object({ type: z.literal("select"), selector: z.string(), value: z.string() }),
         z.object({ type: z.literal("check"), selector: z.string() }),
         z.object({ type: z.literal("uncheck"), selector: z.string() }),
         z.object({ type: z.literal("focus"), selector: z.string() }),
         z.object({ type: z.literal("press_key"), key: z.string() }),
-        z.object({ type: z.literal("scroll"), direction: z.enum(["up", "down", "left", "right"]), distance: z.number().optional() }),
+        z.object({
+            type: z.literal("scroll"),
+            direction: z.enum(["up", "down", "left", "right"]),
+            distance: z.number().optional(),
+        }),
         z.object({ type: z.literal("drag"), source_selector: z.string(), target_selector: z.string() }),
         z.object({ type: z.literal("get_accessibility_tree") }),
         z.object({ type: z.literal("get_url") }),
@@ -779,8 +862,16 @@ labels, and states — everything needed to drive browser interactions.`,
         z.object({ type: z.literal("get_attribute"), selector: z.string(), attribute: z.string() }),
         z.object({ type: z.literal("get_html"), selector: z.string().optional() }),
         z.object({ type: z.literal("query_selector_all"), selector: z.string() }),
-        z.object({ type: z.literal("screenshot"), full_page: z.boolean().optional(), selector: z.string().optional() }),
-        z.object({ type: z.literal("wait_for_selector"), selector: z.string(), visible: z.boolean().optional() }),
+        z.object({
+            type: z.literal("screenshot"),
+            full_page: z.boolean().optional(),
+            selector: z.string().optional(),
+        }),
+        z.object({
+            type: z.literal("wait_for_selector"),
+            selector: z.string(),
+            visible: z.boolean().optional(),
+        }),
         z.object({ type: z.literal("wait_for_navigation") }),
         z.object({ type: z.literal("wait"), ms: z.number().int().min(0).max(30000) }),
         z.object({ type: z.literal("evaluate"), script: z.string() }),
@@ -813,49 +904,69 @@ labels, and states — everything needed to drive browser interactions.`,
                 return r.data;
             }
             case "click": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/click`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/click`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "hover": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/hover`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/hover`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "type": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/type`, { selector: action.selector, text: action.text, clear_first: action.clear_first });
+                const r = await fetch("POST", `/browser/sessions/${sid}/type`, {
+                    selector: action.selector,
+                    text: action.text,
+                    clear_first: action.clear_first,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "fill": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/fill`, { selector: action.selector, value: action.value });
+                const r = await fetch("POST", `/browser/sessions/${sid}/fill`, {
+                    selector: action.selector,
+                    value: action.value,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "select": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/select`, { selector: action.selector, value: action.value });
+                const r = await fetch("POST", `/browser/sessions/${sid}/select`, {
+                    selector: action.selector,
+                    value: action.value,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "check": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/check`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/check`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "uncheck": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/uncheck`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/uncheck`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "focus": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/focus`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/focus`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
@@ -867,13 +978,19 @@ labels, and states — everything needed to drive browser interactions.`,
                 return { ok: true };
             }
             case "scroll": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/scroll`, { direction: action.direction, distance: action.distance });
+                const r = await fetch("POST", `/browser/sessions/${sid}/scroll`, {
+                    direction: action.direction,
+                    distance: action.distance,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
             }
             case "drag": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/drag`, { source_selector: action.source_selector, target_selector: action.target_selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/drag`, {
+                    source_selector: action.source_selector,
+                    target_selector: action.target_selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
@@ -897,31 +1014,43 @@ labels, and states — everything needed to drive browser interactions.`,
                 return r.data;
             }
             case "get_text": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/get_text`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/get_text`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return r.data.text;
             }
             case "get_attribute": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/get_attribute`, { selector: action.selector, attribute: action.attribute });
+                const r = await fetch("POST", `/browser/sessions/${sid}/get_attribute`, {
+                    selector: action.selector,
+                    attribute: action.attribute,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return r.data;
             }
             case "get_html": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/get_html`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/get_html`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return r.data.html;
             }
             case "query_selector_all": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/query_selector_all`, { selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/query_selector_all`, {
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return r.data;
             }
             case "screenshot": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/screenshot`, { full_page: action.full_page, selector: action.selector });
+                const r = await fetch("POST", `/browser/sessions/${sid}/screenshot`, {
+                    full_page: action.full_page,
+                    selector: action.selector,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 // Return as data URI string so it fits in the JSON result array.
@@ -930,7 +1059,10 @@ labels, and states — everything needed to drive browser interactions.`,
                 return { mime_type: d.mime_type, data: d.data };
             }
             case "wait_for_selector": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/wait_for_selector`, { selector: action.selector, visible: action.visible });
+                const r = await fetch("POST", `/browser/sessions/${sid}/wait_for_selector`, {
+                    selector: action.selector,
+                    visible: action.visible,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return { ok: true };
@@ -948,7 +1080,9 @@ labels, and states — everything needed to drive browser interactions.`,
                 return { ok: true };
             }
             case "evaluate": {
-                const r = await fetch("POST", `/browser/sessions/${sid}/evaluate`, { script: action.script });
+                const r = await fetch("POST", `/browser/sessions/${sid}/evaluate`, {
+                    script: action.script,
+                });
                 if (!r.ok)
                     throw new Error(browserError(r));
                 return r.data;
@@ -956,7 +1090,11 @@ labels, and states — everything needed to drive browser interactions.`,
         }
     }
     server.registerTool("browser_batch", {
-        annotations: { title: "Run Batch of Browser Actions", readOnlyHint: false, destructiveHint: false },
+        annotations: {
+            title: "Run Batch of Browser Actions",
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
         description: `Execute a sequence of browser actions in a single call against an existing session.
 
 Use this when you already know the full sequence of steps — it reduces round trips and
@@ -969,7 +1107,11 @@ Note: screenshots in batch results are returned as base64 strings inside the JSO
 For proper image rendering, use browser_screenshot directly.`,
         inputSchema: {
             session_id: sessionId,
-            actions: z.array(batchAction).min(1).max(50).describe("Ordered list of actions to perform. Each action has a 'type' field plus type-specific parameters."),
+            actions: z
+                .array(batchAction)
+                .min(1)
+                .max(50)
+                .describe("Ordered list of actions to perform. Each action has a 'type' field plus type-specific parameters."),
             stop_on_error: z.boolean().optional().describe("Stop executing on the first failed action (default true)"),
         },
     }, async ({ session_id, actions, stop_on_error = true }) => {
@@ -986,7 +1128,12 @@ For proper image rendering, use browser_screenshot directly.`,
                 results.push({ step: i, type: action.type, error: msg });
                 if (stop_on_error) {
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ completed: i, total: actions.length, results }) }],
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ completed: i, total: actions.length, results }),
+                            },
+                        ],
                         isError: true,
                     };
                 }

package/dist/tools/extract.js

@@ -1,10 +1,14 @@
 import { createRequire } from "module";
 import { z } from "zod";
+import { appendClaimHint } from "../auth/claim-hint.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
 const ZENROWS_API_URL = "https://api.zenrows.com/v1/";
 function err(text) {
-    return { content: [{ type: "text", text }], isError: true };
+    return {
+        content: [{ type: "text", text: appendClaimHint(text, { body: text, message: text }) }],
+        isError: true,
+    };
 }
 function json(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
@@ -187,10 +191,7 @@ For full-page markdown/HTML/screenshots, use scrape instead.`,
                 .string()
                 .optional()
                 .describe('Required when mode=css. JSON map of field→selector, e.g. \'{"title":"h1","price":".price"}\''),
-            js_render: z
-                .boolean()
-                .optional()
-                .describe("Enable headless JS rendering (SPAs / dynamic content)"),
+            js_render: z.boolean().optional().describe("Enable headless JS rendering (SPAs / dynamic content)"),
             premium_proxy: z
                 .boolean()
                 .optional()
@@ -199,14 +200,8 @@ For full-page markdown/HTML/screenshots, use scrape instead.`,
                 .string()
                 .optional()
                 .describe("ISO 3166-1 alpha-2 country code. Requires premium_proxy or mode_auto."),
-            mode_auto: z
-                .boolean()
-                .optional()
-                .describe("Enable Adaptive Stealth Mode (mode=auto) for tougher sites"),
-            wait_for: z
-                .string()
-                .optional()
-                .describe("CSS selector to wait for before extracting. Requires js_render."),
+            mode_auto: z.boolean().optional().describe("Enable Adaptive Stealth Mode (mode=auto) for tougher sites"),
+            wait_for: z.string().optional().describe("CSS selector to wait for before extracting. Requires js_render."),
             wait: z
                 .number()
                 .int()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/mcp",
-  "version": "2.2.0",
+  "version": "2.2.3",
   "description": "Zenrows MCP server — Fetch, Extract, Batch, and Browser Sessions for AI coding assistants",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   ],
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
+    "check:server-json": "node scripts/sync-server-json-version.mjs --check",
     "clean": "rm -rf dist",
     "dev": "node --env-file=.env --import tsx src/index.ts",
     "dev:http": "node --env-file=.env --import tsx src/http.ts",
@@ -20,8 +21,9 @@
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm run lint && npm test",
+    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm run lint && npm test && npm run check:server-json",
     "publish-beta": "npm publish --tag beta",
+    "sync:server-json": "node scripts/sync-server-json-version.mjs",
     "test": "node --import tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit"
   },