@zenrows/mcp 2.1.2 → 2.2.2

package/dist/http.js

@@ -57,7 +57,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 +71,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: {
@@ -138,7 +138,7 @@ app.all("/mcp", async (c) => {
             "WWW-Authenticate": `Bearer realm="${AUTH_SERVER}", 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,12 +1,38 @@
 #!/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 { createServer } from "./server.js";
-const apiKey = process.env.ZENROWS_API_KEY;
-if (!apiKey) {
-    process.stderr.write("Error: ZENROWS_API_KEY environment variable is required\n");
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+let apiKey;
+try {
+    const existing = resolveApiKey();
+    if (existing.key) {
+        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)";
+        process.stderr.write(`No API key — will auto-signup via: ${signup}\n`);
+    }
+    const resolved = await ensureApiKey({
+        userAgent: `zenrows/mcp ${pkg.version}`,
+        onProvision: (acct) => {
+            process.stderr.write(`Created a Zenrows Free plan account.\n` +
+                `Claim it anytime (keeps your usage): ${acct.claimUrl}\n` +
+                `Key stored in ${getZenrowsDir()}/secrets.json\n`);
+        },
+    });
+    apiKey = resolved.apiKey;
+}
+catch (err) {
+    const msg = err instanceof AuthError
+        ? `Error: ${err.message}\n`
+        : `Error: ${err instanceof Error ? err.message : String(err)}\n`;
+    process.stderr.write(msg);
     process.exit(1);
 }
 const server = createServer(apiKey);
 const transport = new StdioServerTransport();
 await server.connect(transport);
-process.stderr.write("Zenrows MCP server running on stdio\n");
+process.stderr.write(`Zenrows MCP server running on stdio (secrets dir: ${getZenrowsDir()})\n`);

package/dist/server.js

@@ -1,7 +1,12 @@
 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";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
 const ZENROWS_API_URL = "https://api.zenrows.com/v1/";
@@ -23,24 +28,22 @@ export function createServer(apiKey, clientName) {
             readOnlyHint: true,
             destructiveHint: false,
         },
-        description: `Scrape any webpage and return its content using Zenrows.
+        description: `Scrape any webpage and return its content using Zenrows (Fetch).
 
-Use this tool to fetch webpage content for analysis. By default it returns clean
-markdown, which is ideal for LLM processing.
+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)
-- css_extractor: you only need specific elements, not the whole page
-- autoparse: structured data pages like products or articles
 
 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 }
-  Extract:  { url: "https://shop.com", css_extractor: '{"title":"h1","price":".price"}' }`,
+  Protected:{ url: "https://protected.com", js_render: true, premium_proxy: true }`,
         inputSchema: {
             url: z.string().url().describe("The webpage URL to scrape"),
             js_render: z
@@ -157,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;
@@ -187,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,
             };
         }
@@ -232,7 +235,7 @@ Examples:
     }));
     server.registerPrompt("extract_structured_data", {
         title: "Extract Structured Data",
-        description: "Scrape a webpage and extract specific structured data using CSS selectors.",
+        description: "Extract specific structured data from a webpage using CSS selectors.",
         argsSchema: {
             url: z.string().url().describe("The webpage URL to extract data from"),
             fields: z
@@ -245,7 +248,7 @@ Examples:
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Scrape ${url} using the Zenrows MCP scrape tool with css_extractor set to ${fields}. Return the extracted data as a clean JSON object.`,
+                    text: `Use the Zenrows MCP extract tool on ${url} with mode=css and css_extractor set to ${fields}. Return the extracted data as a clean JSON object.`,
                 },
             },
         ],
@@ -267,7 +270,40 @@ 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.
+    server.registerResource("zenrows-account", "zenrows://account", {
+        description: "Local Zenrows agent account metadata (claim URL for unclaimed Free plans). Re-reads ~/.zenrows or $ZENROWS_HOME on each read.",
+        mimeType: "application/json",
+    }, async () => {
+        const acct = readAccount();
+        const home = getZenrowsDir();
+        const body = acct
+            ? {
+                accountId: acct.accountId,
+                unclaimed: acct.unclaimed,
+                claimUrl: acct.claimUrl,
+                createdAt: acct.createdAt,
+                zenrowsHome: home,
+            }
+            : {
+                unclaimed: false,
+                message: "No local agent account file (key from env or missing).",
+                zenrowsHome: home,
+            };
+        return {
+            contents: [
+                {
+                    uri: "zenrows://account",
+                    mimeType: "application/json",
+                    text: JSON.stringify(body, null, 2),
+                },
+            ],
+        };
+    });
     return server;
 }

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.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBatchTools(server: McpServer, apiKey: string): void;

package/dist/tools/batch.js

@@ -0,0 +1,245 @@
+import { createRequire } from "module";
+import { z } from "zod";
+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, hint) {
+    const raw = typeof data === "string" ? data : JSON.stringify(data);
+    return {
+        content: [
+            {
+                type: "text",
+                text: appendClaimHint(raw, {
+                    status: hint?.status,
+                    code: hint?.code,
+                    message: hint?.message ?? raw,
+                    body: raw,
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+function json(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+function batchErr(e) {
+    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),
+    });
+}
+function normalizeParams(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string")
+            out[k] = v;
+        else if (typeof v === "boolean" || typeof v === "number")
+            out[k] = String(v);
+        else
+            out[k] = JSON.stringify(v);
+    }
+    return out;
+}
+const taskSchema = z.object({
+    url: z.string().url().describe("Target URL for this task"),
+    external_id: z.string().optional().describe("Optional stable id echoed back on results"),
+    metadata: z.unknown().optional().describe("Opaque per-task metadata carried through to results"),
+    zenrows_params: z
+        .record(z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe("Per-task Zenrows scrape params (js_render, premium_proxy, extract, autoparse, …)"),
+});
+export function registerBatchTools(server, apiKey) {
+    const ua = `zenrows/mcp ${pkg.version}`;
+    const call = { apiKey, userAgent: ua };
+    server.registerTool("batch_create", {
+        annotations: { title: "Create Batch Job", readOnlyHint: false, destructiveHint: false },
+        description: `Submit a cloud Batch job that fans out many URLs asynchronously (Zenrows Batch API beta).
+
+NOT the same as browser_batch — this hits https://async.api.zenrows.com/v1 with X-API-Key.
+Use for large URL lists; prefer scrape/extract for one-off pages.
+
+Returns job_id + latest_run.status/stats. Poll with batch_status / batch_wait, then batch_results.
+If you get BATCH_ACCESS_DENIED, the account lacks Batch beta access.`,
+        inputSchema: {
+            tasks: z
+                .array(taskSchema)
+                .optional()
+                .describe("List of tasks (each needs a url). Prefer this over urls when you need per-task params."),
+            urls: z
+                .array(z.string().url())
+                .optional()
+                .describe("Shorthand: list of URLs (converted to tasks). Ignored when tasks is provided."),
+            js_render: z.boolean().optional().describe("Job-level js_render for all tasks"),
+            premium_proxy: z.boolean().optional().describe("Job-level premium_proxy for all tasks"),
+            proxy_country: z
+                .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"),
+            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_timeout_ms: z
+                .number()
+                .int()
+                .min(1000)
+                .max(3_600_000)
+                .optional()
+                .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 }));
+        if (!tasksIn.length) {
+            return err({
+                code: "INVALID_USAGE",
+                message: "Provide tasks (preferred) or urls with at least one URL.",
+            });
+        }
+        const jobParams = { ...(params.zenrows_params ?? {}) };
+        if (params.js_render)
+            jobParams.js_render = true;
+        if (params.premium_proxy)
+            jobParams.premium_proxy = true;
+        if (params.proxy_country)
+            jobParams.proxy_country = params.proxy_country.toLowerCase();
+        if (params.response_type)
+            jobParams.response_type = params.response_type;
+        const body = {
+            type: "regular",
+            status: "closed",
+            tasks: tasksIn.map((t) => {
+                const task = { url: t.url };
+                if (t.external_id)
+                    task.external_id = t.external_id;
+                if (t.metadata !== undefined)
+                    task.metadata = t.metadata;
+                if (t.zenrows_params)
+                    task.zenrows_params = normalizeParams(t.zenrows_params);
+                return task;
+            }),
+            ...(Object.keys(jobParams).length ? { zenrows_params: normalizeParams(jobParams) } : {}),
+        };
+        try {
+            const job = await createJob(body, call);
+            const finished = params.wait === true
+                ? await waitForJob(job.job_id, {
+                    ...call,
+                    pollTimeoutMs: params.wait_timeout_ms ?? 600_000,
+                })
+                : job;
+            const run = finished.latest_run ?? {};
+            return json({
+                ok: true,
+                job_id: finished.job_id,
+                status: run.status,
+                stats: run.stats,
+                job: finished,
+            });
+        }
+        catch (e) {
+            return batchErr(e);
+        }
+    });
+    server.registerTool("batch_status", {
+        annotations: { title: "Batch Job Status", readOnlyHint: true, destructiveHint: false },
+        description: "Get status and stats for a Zenrows Batch job (latest_run.status + latest_run.stats).",
+        inputSchema: {
+            job_id: z.string().describe("Batch job id returned by batch_create"),
+        },
+    }, async ({ job_id }) => {
+        try {
+            const job = await getJob(job_id, call);
+            const run = job.latest_run ?? {};
+            return json({
+                ok: true,
+                job_id: job.job_id,
+                status: run.status,
+                stats: run.stats,
+                job,
+            });
+        }
+        catch (e) {
+            return batchErr(e);
+        }
+    });
+    server.registerTool("batch_results", {
+        annotations: { title: "Batch Job Results", readOnlyHint: true, destructiveHint: false },
+        description: `List result rows for a Batch job (cursor-paginated server-side; returns the full list).
+
+Each row may include task_id, external_id, status, and a short-lived result_url for the body.
+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)"),
+        },
+    }, async ({ job_id, status }) => {
+        try {
+            const results = await listResults(job_id, { ...call, status });
+            return json({ ok: true, job_id, count: results.length, results });
+        }
+        catch (e) {
+            return batchErr(e);
+        }
+    });
+    server.registerTool("batch_cancel", {
+        annotations: { title: "Cancel Batch Job", readOnlyHint: false, destructiveHint: true },
+        description: "Stop an in-flight Batch job run (POST /jobs/:id/stop).",
+        inputSchema: {
+            job_id: z.string().describe("Batch job id to stop"),
+        },
+    }, async ({ job_id }) => {
+        try {
+            const job = await stopJob(job_id, call);
+            const run = job.latest_run ?? {};
+            return json({
+                ok: true,
+                job_id: job.job_id,
+                status: run.status,
+                stats: run.stats,
+                job,
+            });
+        }
+        catch (e) {
+            return batchErr(e);
+        }
+    });
+    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).",
+        inputSchema: {
+            job_id: z.string().describe("Batch job id"),
+            timeout_ms: z
+                .number()
+                .int()
+                .min(1000)
+                .max(3_600_000)
+                .optional()
+                .describe("Max wait time in ms (default 600000)"),
+        },
+    }, async ({ job_id, timeout_ms }) => {
+        try {
+            const job = await waitForJob(job_id, { ...call, pollTimeoutMs: timeout_ms ?? 600_000 });
+            const run = job.latest_run ?? {};
+            return json({
+                ok: true,
+                job_id: job.job_id,
+                status: run.status,
+                stats: run.stats,
+                job,
+            });
+        }
+        catch (e) {
+            return batchErr(e);
+        }
+    });
+}