@fouradata/mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FourA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @fouradata/mcp
+
+[FourA Web Scraping API](https://foura.ai/) as three [Model Context Protocol](https://modelcontextprotocol.io) tools. Plug it into Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP client and you can fetch arbitrary public web pages, bypass anti-bot challenges, and render JavaScript-heavy sites — all without writing a line of integration code.
+
+Three tools, one API key.
+
+## Quick Start — hosted
+
+Grab a key at [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) (one click, shown once on creation, format `pk_live_...`). Then drop this into your MCP client's config:
+
+```json
+{
+  "mcpServers": {
+    "foura": {
+      "url": "https://mcp.foura.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer pk_live_..."
+      }
+    }
+  }
+}
+```
+
+That's it. Restart the client and `foura_single`, `foura_proxy`, `foura_browser` show up in your tool list.
+
+Same JSON works in every major client — just point it at the right file:
+
+| Client | Where the config lives |
+|---|---|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Claude Code | `claude mcp add --transport http foura https://mcp.foura.ai/mcp --header "Authorization: Bearer pk_live_..."` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (MCP extension) | `.vscode/mcp.json` in your workspace |
+
+## Quick Start — local stdio
+
+Prefer to run the server in-process on your machine? Use npx:
+
+```json
+{
+  "mcpServers": {
+    "foura": {
+      "command": "npx",
+      "args": ["-y", "@fouradata/mcp"],
+      "env": {
+        "FOURA_API_KEY": "pk_live_..."
+      }
+    }
+  }
+}
+```
+
+The package downloads and runs on first launch. No global install needed.
+
+## The Three Tools
+
+### `foura_single` — fast HTTP
+
+One HTTP request, response back. Typically 200ms–2s. Use it for static pages, JSON APIs, server-rendered HTML — the bread and butter of scraping. Set `unblocker: true` if the target is picky about wire-level signals.
+
+```jsonc
+{
+  "method": "GET",
+  "url": "https://example.com",
+  "unblocker": true
+}
+```
+
+You can pass custom headers, a body, per-stage timeouts, redirect controls, JSON auto-parse, a binary-buffer mode, and built-in response validation (`validate.status.accept`, `validate.data.fail`, and so on). If `foura_single` comes back with a 403 or captcha, escalate to `foura_proxy`. If the page needs JavaScript, escalate to `foura_browser`.
+
+### `foura_proxy` — rotating proxies with retry
+
+Same shape as `foura_single`, but routed through a pool of proxies with automatic retry on failure. Per-host scoring picks the proxies most likely to succeed against this particular target, so you're not burning attempts on known-bad routes.
+
+```jsonc
+{
+  "maxTries": 5,
+  "request": {
+    "method": "GET",
+    "url": "https://example.com/pricing",
+    "unblocker": true
+  }
+}
+```
+
+Typical latency 1–5s. The response includes the proxy ID that succeeded and the total number of tries — handy when you're debugging why a site keeps blocking you.
+
+### `foura_browser` — full browser session
+
+A real browser session. JavaScript runs, the DOM finishes rendering, cookies come back with the response. Use it when the page is a single-page app, when content lazy-loads after first paint, or when there's an anti-bot challenge that needs a real browser to clear.
+
+```jsonc
+{
+  "url": "https://example.com/spa",
+  "timeout_ms": 15000,
+  "checkText": "data-table"
+}
+```
+
+Slowest of the three (2–10s), but it's the only tool that handles JavaScript end-to-end. `checkText` fails the request if a substring you expect doesn't appear in the rendered HTML — useful when a page returns 200 but the actual content is missing.
+
+## Authentication
+
+Your `Bearer` token (or the `FOURA_API_KEY` env var in stdio mode) forwards to the FourA API as `X-API-Key`. One key, all three tools.
+
+Keys are managed in the [dashboard](https://foura.ai/dashboard#api-keys) — shown once on creation, rotate or deactivate any time. Errors come back to the MCP client with the full envelope (`retryAfter`, `current.{concurrency,rpm}`, `limits.maxRpm`) so the LLM can self-throttle without you stepping in. Full reference: [foura.ai/docs/api/errors](https://foura.ai/docs/api/errors).
+
+## Limits
+
+- **Large responses get offloaded.** Anything above 50 KB is cached on the MCP server and returned as a `resource_link` with a preview. Your client calls `resources/read` to pull the full body only when it actually needs it. Cached payloads expire after an hour.
+- **Private targets are refused.** Requests to private or reserved IP ranges (RFC 5735, 6598, and IPv6 reserved blocks) are blocked at the MCP layer. We only forward to public hosts.
+- **Rate limits** are enforced by the FourA API per service. Concurrency + RPM. Details at [foura.ai/docs/api/rate-limits](https://foura.ai/docs/api/rate-limits).
+
+## Self-Hosting
+
+The MCP server runs in one container, statelessly — each request brings its own key, so there's no session state, no sticky load balancing, nothing to coordinate. Scale horizontally behind any load balancer.
+
+Configurable environment:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `3076` | HTTP listen port |
+| `FOURA_API_BASE` | `https://api.foura.ai/api` | Upstream FourA REST base URL |
+| `FOURA_MCP_PAYLOADS_DIR` | `/data/payloads` | Where >50 KB responses are cached on disk |
+
+A public GitHub mirror lands with `v1.0`; until then the source lives in a private repo. Ping `support@foura.ai` if you need early access to the container image.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).
+
+## Links
+
+- API documentation: <https://foura.ai/docs>
+- MCP specification: <https://modelcontextprotocol.io>
+- Get a key: <https://foura.ai/dashboard#api-keys>

package/bin/foura-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/stdio.js";

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+export declare function withApiKey<T>(key: string, fn: () => Promise<T>): Promise<T>;
+export declare function getApiKey(): string;

package/dist/auth.js

@@ -0,0 +1,32 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Shared FourA auth.
+ *
+ * The API key authenticates the CALLER, not the endpoint — one key opens
+ * /single/, /proxy/, and /browser/. So this lives in one place and is
+ * imported by every tool. (Schemas, paths, and per-endpoint behavior remain
+ * fully duplicated across tool files — see
+ * feedback_foura_endpoints_independent_schemas.)
+ *
+ * Dual-mode:
+ *   - stdio: the user sets FOURA_API_KEY in env (e.g. via claude_desktop_config).
+ *   - HTTP: each incoming /mcp request supplies its own key via
+ *     Authorization: Bearer pk_live_..., which the transport scopes into
+ *     AsyncLocalStorage before invoking the tool handler.
+ */
+const apiKeyContext = new AsyncLocalStorage();
+export function withApiKey(key, fn) {
+    return apiKeyContext.run(key, fn);
+}
+export function getApiKey() {
+    const fromContext = apiKeyContext.getStore();
+    if (fromContext)
+        return fromContext;
+    const fromEnv = process.env.FOURA_API_KEY;
+    if (fromEnv)
+        return fromEnv;
+    throw new Error("FOURA_API_KEY not provided. In stdio mode set the FOURA_API_KEY env var. " +
+        "In HTTP mode send Authorization: Bearer pk_live_... Get a key at " +
+        "https://foura.ai/dashboard#api-keys");
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,MAAM,aAAa,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAEtD,MAAM,UAAU,UAAU,CAAI,GAAW,EAAE,EAAoB;IAC7D,OAAO,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,MAAM,WAAW,GAAG,aAAa,CAAC,QAAQ,EAAE,CAAC;IAC7C,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC1C,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,IAAI,KAAK,CACb,2EAA2E;QACzE,mEAAmE;QACnE,qCAAqC,CACxC,CAAC;AACJ,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http.js

@@ -0,0 +1,71 @@
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "./server.js";
+import { withApiKey } from "./auth.js";
+const PORT = Number(process.env.PORT ?? 3076);
+const SERVER_VERSION = "0.1.1";
+const app = express();
+app.use(express.json({ limit: "4mb" }));
+app.get("/healthz", (_req, res) => {
+    res.json({ ok: true, name: "foura-mcp", version: SERVER_VERSION });
+});
+function extractBearer(req) {
+    const auth = req.header("authorization");
+    if (auth?.toLowerCase().startsWith("bearer "))
+        return auth.slice(7).trim();
+    const xKey = req.header("x-api-key");
+    if (xKey)
+        return xKey.trim();
+    return null;
+}
+app.post("/mcp", async (req, res) => {
+    const apiKey = extractBearer(req);
+    if (!apiKey) {
+        res.status(401).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32001,
+                message: "Missing API key. Send 'Authorization: Bearer pk_live_...' with each request. " +
+                    "Get a key at https://foura.ai/dashboard#api-keys",
+            },
+            id: null,
+        });
+        return;
+    }
+    try {
+        const mcp = createServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // stateless — fresh transport per request
+        });
+        res.on("close", () => {
+            transport.close();
+            mcp.close();
+        });
+        await mcp.connect(transport);
+        await withApiKey(apiKey, () => transport.handleRequest(req, res, req.body));
+    }
+    catch (err) {
+        console.error("[foura-mcp] /mcp handler error:", err);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: "Internal server error" },
+                id: null,
+            });
+        }
+    }
+});
+// Stateless mode: GET (server-initiated SSE) and DELETE (session teardown) not supported.
+const methodNotAllowed = (_req, res) => {
+    res.status(405).json({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "Method not allowed in stateless mode. Use POST /mcp." },
+        id: null,
+    });
+};
+app.get("/mcp", methodNotAllowed);
+app.delete("/mcp", methodNotAllowed);
+app.listen(PORT, "0.0.0.0", () => {
+    console.error(`[foura-mcp] HTTP listening on :${PORT}`);
+});
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/resources.d.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Resources — offload large response bodies (>= THRESHOLD bytes) onto host
+ * disk and return a MCP resource_link instead of inlining megabytes into the
+ * LLM context.
+ *
+ * Transport-level cross-cutting concern (same carve-out as auth.ts and
+ * safe-target.ts). Per-tool product code stays per-file: each tool decides
+ * which response field is the "large payload" (single/proxy use `data`,
+ * browser uses `body`).
+ */
+export declare const THRESHOLD_BYTES = 50000;
+export declare const PAYLOADS_DIR: string;
+export interface StoredPayload {
+    uri: string;
+    name: string;
+    mimeType: string;
+    size: number;
+}
+/**
+ * Write `data` to disk and return a resource_link descriptor.
+ *
+ * Caller has already decided this payload is big enough to offload (use
+ * `THRESHOLD_BYTES` for the size check).
+ */
+export declare function storePayload(data: Buffer | string, mimeType: string, suggestedName: string): Promise<StoredPayload>;
+export declare function registerResourceHandler(server: McpServer): void;

package/dist/resources.js

@@ -0,0 +1,89 @@
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Resources — offload large response bodies (>= THRESHOLD bytes) onto host
+ * disk and return a MCP resource_link instead of inlining megabytes into the
+ * LLM context.
+ *
+ * Transport-level cross-cutting concern (same carve-out as auth.ts and
+ * safe-target.ts). Per-tool product code stays per-file: each tool decides
+ * which response field is the "large payload" (single/proxy use `data`,
+ * browser uses `body`).
+ */
+export const THRESHOLD_BYTES = 50_000;
+export const PAYLOADS_DIR = process.env.FOURA_MCP_PAYLOADS_DIR ?? path.join(tmpdir(), "foura-mcp-payloads");
+const URI_PREFIX = "foura-mcp://payload/";
+let initPromise = null;
+function ensureDir() {
+    if (!initPromise)
+        initPromise = mkdir(PAYLOADS_DIR, { recursive: true }).then(() => undefined);
+    return initPromise;
+}
+const SAFE_UUID = /^[0-9a-f-]{36}$/i;
+/**
+ * Write `data` to disk and return a resource_link descriptor.
+ *
+ * Caller has already decided this payload is big enough to offload (use
+ * `THRESHOLD_BYTES` for the size check).
+ */
+export async function storePayload(data, mimeType, suggestedName) {
+    await ensureDir();
+    const uuid = randomUUID();
+    const isBinary = Buffer.isBuffer(data);
+    const buf = isBinary ? data : Buffer.from(data, "utf8");
+    const dataPath = path.join(PAYLOADS_DIR, `${uuid}.bin`);
+    const metaPath = path.join(PAYLOADS_DIR, `${uuid}.meta.json`);
+    const meta = {
+        mimeType,
+        originalName: suggestedName,
+        size: buf.byteLength,
+        storedAt: new Date().toISOString(),
+        binary: isBinary,
+    };
+    await Promise.all([
+        writeFile(dataPath, buf),
+        writeFile(metaPath, JSON.stringify(meta), { encoding: "utf8" }),
+    ]);
+    return {
+        uri: `${URI_PREFIX}${uuid}`,
+        name: suggestedName,
+        mimeType,
+        size: buf.byteLength,
+    };
+}
+export function registerResourceHandler(server) {
+    server.registerResource("payload", new ResourceTemplate(`${URI_PREFIX}{uuid}`, { list: undefined }), {
+        title: "Cached foura-mcp response payload",
+        description: "A large response body (>=50KB) returned by an earlier foura-mcp tool call, " +
+            "stored on disk for follow-up reads instead of inlined into context.",
+    }, async (uri, { uuid }) => {
+        const uuidStr = Array.isArray(uuid) ? uuid[0] : uuid;
+        if (!uuidStr || !SAFE_UUID.test(uuidStr)) {
+            throw new Error(`Invalid payload UUID: ${uuidStr}`);
+        }
+        const metaPath = path.join(PAYLOADS_DIR, `${uuidStr}.meta.json`);
+        const dataPath = path.join(PAYLOADS_DIR, `${uuidStr}.bin`);
+        const metaRaw = await readFile(metaPath, "utf8");
+        const meta = JSON.parse(metaRaw);
+        const buf = await readFile(dataPath);
+        return {
+            contents: [
+                meta.binary
+                    ? {
+                        uri: uri.href,
+                        mimeType: meta.mimeType,
+                        blob: buf.toString("base64"),
+                    }
+                    : {
+                        uri: uri.href,
+                        mimeType: meta.mimeType,
+                        text: buf.toString("utf8"),
+                    },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/dist/safe-target.d.ts

@@ -0,0 +1,5 @@
+export declare class SsrfBlockedError extends Error {
+    readonly hostInfo: string;
+    constructor(hostInfo: string);
+}
+export declare function assertPublicTarget(rawUrl: string): Promise<void>;

package/dist/safe-target.js

@@ -0,0 +1,118 @@
+import { lookup } from "node:dns/promises";
+import { isIPv4, isIPv6 } from "node:net";
+function ipv4ToInt(addr) {
+    const parts = addr.split(".");
+    if (parts.length !== 4)
+        throw new Error(`bad IPv4: ${addr}`);
+    let n = 0;
+    for (const p of parts) {
+        const v = Number(p);
+        if (!Number.isInteger(v) || v < 0 || v > 255)
+            throw new Error(`bad IPv4 octet: ${addr}`);
+        n = n * 256 + v;
+    }
+    return n >>> 0;
+}
+// RFC 5735 + RFC 6598 (CGNAT) reserved IPv4 blocks.
+const V4_RESERVED = [
+    { base: ipv4ToInt("0.0.0.0"), prefix: 8 }, // "this network"
+    { base: ipv4ToInt("10.0.0.0"), prefix: 8 }, // RFC1918 private
+    { base: ipv4ToInt("100.64.0.0"), prefix: 10 }, // CGNAT (RFC 6598)
+    { base: ipv4ToInt("127.0.0.0"), prefix: 8 }, // loopback
+    { base: ipv4ToInt("169.254.0.0"), prefix: 16 }, // link-local
+    { base: ipv4ToInt("172.16.0.0"), prefix: 12 }, // RFC1918 private
+    { base: ipv4ToInt("192.0.0.0"), prefix: 24 }, // IETF protocol
+    { base: ipv4ToInt("192.0.2.0"), prefix: 24 }, // TEST-NET-1
+    { base: ipv4ToInt("192.88.99.0"), prefix: 24 }, // 6to4 anycast (deprecated)
+    { base: ipv4ToInt("192.168.0.0"), prefix: 16 }, // RFC1918 private
+    { base: ipv4ToInt("198.18.0.0"), prefix: 15 }, // benchmarking
+    { base: ipv4ToInt("198.51.100.0"), prefix: 24 }, // TEST-NET-2
+    { base: ipv4ToInt("203.0.113.0"), prefix: 24 }, // TEST-NET-3
+    { base: ipv4ToInt("224.0.0.0"), prefix: 4 }, // multicast
+    { base: ipv4ToInt("240.0.0.0"), prefix: 4 }, // reserved
+    { base: ipv4ToInt("255.255.255.255"), prefix: 32 }, // broadcast
+];
+function isReservedV4(addr) {
+    let n;
+    try {
+        n = ipv4ToInt(addr);
+    }
+    catch {
+        return false;
+    }
+    for (const b of V4_RESERVED) {
+        const mask = b.prefix === 0 ? 0 : (0xffffffff << (32 - b.prefix)) >>> 0;
+        if ((n & mask) === (b.base & mask))
+            return true;
+    }
+    return false;
+}
+function isReservedV6(addr) {
+    const a = addr.toLowerCase();
+    if (a === "::" || a === "::1")
+        return true;
+    const firstGroup = a.split(":")[0] ?? "";
+    // ULA fc00::/7 — first hex of first group is f, second is c or d
+    if (/^f[cd][0-9a-f]{0,2}$/.test(firstGroup))
+        return true;
+    // link-local fe80::/10 — first group starts fe8, fe9, fea, feb
+    if (/^fe[89ab][0-9a-f]{0,1}$/.test(firstGroup))
+        return true;
+    // documentation 2001:db8::/32
+    if (/^2001:0?db8(:|$)/.test(a))
+        return true;
+    // IPv4-mapped: ::ffff:x.x.x.x — check the embedded v4
+    const v4mapped = /^::ffff:([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)$/.exec(a);
+    if (v4mapped?.[1])
+        return isReservedV4(v4mapped[1]);
+    return false;
+}
+export class SsrfBlockedError extends Error {
+    hostInfo;
+    constructor(hostInfo) {
+        super(`Refusing to fetch ${hostInfo}: target resolves to a private or reserved IP range. ` +
+            `The FourA scraping API only forwards requests to public internet hosts.`);
+        this.hostInfo = hostInfo;
+        this.name = "SsrfBlockedError";
+    }
+}
+export async function assertPublicTarget(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new SsrfBlockedError(`invalid URL: ${rawUrl}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new SsrfBlockedError(`unsupported scheme ${url.protocol}`);
+    }
+    // Strip the [...] brackets from a bare IPv6 hostname
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (isIPv4(host)) {
+        if (isReservedV4(host))
+            throw new SsrfBlockedError(host);
+        return;
+    }
+    if (isIPv6(host)) {
+        if (isReservedV6(host))
+            throw new SsrfBlockedError(host);
+        return;
+    }
+    let addrs;
+    try {
+        addrs = await lookup(host, { all: true, verbatim: true });
+    }
+    catch (e) {
+        throw new SsrfBlockedError(`DNS lookup failed for ${host}: ${e.message}`);
+    }
+    if (addrs.length === 0) {
+        throw new SsrfBlockedError(`${host} resolved to no addresses`);
+    }
+    for (const a of addrs) {
+        const bad = a.family === 4 ? isReservedV4(a.address) : isReservedV6(a.address);
+        if (bad)
+            throw new SsrfBlockedError(`${host} → ${a.address}`);
+    }
+}
+//# sourceMappingURL=safe-target.js.map

package/dist/safe-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-target.js","sourceRoot":"","sources":["../src/safe-target.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerSingleTool } from "./tools/single.js";
+import { registerProxyTool } from "./tools/proxy.js";
+import { registerBrowserTool } from "./tools/browser.js";
+import { registerResourceHandler } from "./resources.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "foura-mcp",
+        version: "0.1.1",
+    });
+    registerSingleTool(server);
+    registerProxyTool(server);
+    registerBrowserTool(server);
+    registerResourceHandler(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAEhC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;AAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/tools/browser.d.ts

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

package/dist/tools/browser.js

@@ -0,0 +1,127 @@
+import { request } from "undici";
+import { z } from "zod";
+import { getApiKey } from "../auth.js";
+import { assertPublicTarget, SsrfBlockedError } from "../safe-target.js";
+import { storePayload, THRESHOLD_BYTES } from "../resources.js";
+function extractContentTypeFromObject(headers) {
+    if (!headers || typeof headers !== "object")
+        return null;
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === "content-type" && typeof v === "string") {
+            return v.split(";")[0]?.trim() ?? null;
+        }
+    }
+    return null;
+}
+const BROWSER_API_URL = (process.env.FOURA_API_BASE ?? "https://api.foura.ai/api") + "/browser/";
+const BrowserCookieInputSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    domain: z.string().optional(),
+});
+const browserInputShape = {
+    url: z.string().url().describe("Target URL to load in a full browser session"),
+    headers: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Custom HTTP headers as a key-value object. Note: object shape, not [name, value] tuples."),
+    cookies: z
+        .array(BrowserCookieInputSchema)
+        .optional()
+        .describe("Cookies to set before navigation: [{ name, value, domain? }]"),
+    userAgent: z.string().optional().describe("Override the browser's User-Agent string"),
+    proxy: z.string().optional().describe("Optional proxy URL for the browser (http://, socks5://)"),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(0)
+        .max(120_000)
+        .optional()
+        .describe("Page load timeout in ms (default 30000, max 120000)"),
+    checkStatus: z
+        .number()
+        .int()
+        .optional()
+        .describe("Expected HTTP status code; request fails if the page returns a different status"),
+    checkText: z
+        .string()
+        .optional()
+        .describe("Substring that must appear in the rendered HTML for the request to count as success"),
+};
+export function registerBrowserTool(server) {
+    server.registerTool("foura_browser", {
+        title: "FourA — full browser navigation",
+        description: "Load a page in a full browser session. JavaScript executes, the DOM renders fully, and cookies " +
+            "come back with the response. Use for single-page apps, lazy-loaded content, or pages behind " +
+            "anti-bot challenges like Cloudflare. Slowest of the three tools (typically 2–10s). For plain " +
+            "static pages prefer foura_single; for static pages where you're being blocked prefer foura_proxy.",
+        inputSchema: browserInputShape,
+    }, async (input) => {
+        try {
+            await assertPublicTarget(input.url);
+        }
+        catch (e) {
+            if (e instanceof SsrfBlockedError) {
+                return { isError: true, content: [{ type: "text", text: e.message }] };
+            }
+            throw e;
+        }
+        const res = await request(BROWSER_API_URL, {
+            method: "POST",
+            headers: {
+                "X-API-Key": getApiKey(),
+                "Content-Type": "application/json",
+                "User-Agent": "foura-mcp/0.1.1 (browser)",
+            },
+            body: JSON.stringify(input),
+        });
+        const text = await res.body.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `FourA browser — non-JSON response (${res.statusCode}): ${text.slice(0, 200)}`,
+                    },
+                ],
+            };
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            const e = parsed;
+            const hint = e.retryAfter !== undefined ? ` Retry after ${e.retryAfter}s.` : "";
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `FourA browser error (${res.statusCode}): ${e.error ?? "Unknown"}.${hint}\n\n${JSON.stringify(parsed, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        const parsedObj = parsed;
+        const body = parsedObj.body;
+        if (typeof body === "string" && Buffer.byteLength(body, "utf8") >= THRESHOLD_BYTES) {
+            const ct = extractContentTypeFromObject(parsedObj.headers) ?? "text/html";
+            const stored = await storePayload(body, ct, "rendered-page.html");
+            const preview = body.slice(0, 500);
+            const trimmed = { ...parsedObj, body: `<offloaded ${stored.size} bytes — see resource ${stored.uri}>` };
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(trimmed, null, 2) },
+                    { type: "text", text: `Rendered page preview (${(stored.size / 1024).toFixed(1)} KB total):\n${preview}` },
+                    { type: "resource_link", uri: stored.uri, name: stored.name, mimeType: stored.mimeType },
+                ],
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=browser.js.map

package/dist/tools/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/tools/browser.ts"],"names":[],"mappings":"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"}

package/dist/tools/proxy.d.ts

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

package/dist/tools/proxy.js

@@ -0,0 +1,171 @@
+import { request } from "undici";
+import { z } from "zod";
+import { getApiKey } from "../auth.js";
+import { assertPublicTarget, SsrfBlockedError } from "../safe-target.js";
+import { storePayload, THRESHOLD_BYTES } from "../resources.js";
+function extractContentTypeFromHeaderInfo(headers) {
+    if (!Array.isArray(headers))
+        return null;
+    for (const h of headers) {
+        if (h && typeof h === "object") {
+            const ct = h["content-type"];
+            if (typeof ct === "string")
+                return ct.split(";")[0]?.trim() ?? null;
+        }
+    }
+    return null;
+}
+const PROXY_API_URL = (process.env.FOURA_API_BASE ?? "https://api.foura.ai/api") + "/proxy/";
+const ProxyHttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const ProxyValidateSchema = z
+    .object({
+    status: z
+        .object({
+        accept: z.array(z.number().int()).optional().describe("HTTP status codes to treat as success"),
+        fail: z.array(z.number().int()).optional().describe("HTTP status codes to treat as failure"),
+    })
+        .optional(),
+    headers: z
+        .object({
+        accept: z.record(z.string(), z.string()).optional(),
+        fail: z.record(z.string(), z.string()).optional(),
+    })
+        .optional(),
+    data: z
+        .object({
+        accept: z.array(z.string()).optional(),
+        fail: z.array(z.string()).optional(),
+    })
+        .optional(),
+})
+    .optional();
+const ProxyInnerRequestSchema = z
+    .object({
+    method: ProxyHttpMethod.describe("HTTP method"),
+    url: z.string().url().describe("Target URL. {ts} placeholder is replaced with current Unix timestamp."),
+    headers: z
+        .array(z.tuple([z.string(), z.string()]))
+        .optional()
+        .describe("Custom HTTP headers as [name, value] tuples"),
+    unblocker: z
+        .boolean()
+        .optional()
+        .describe("Inject realistic browser headers (User-Agent, etc.) — strongly recommended when going through proxies."),
+    data: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .optional()
+        .describe("Request body."),
+    timeout_ms: z.number().int().min(0).max(120_000).optional().describe("Per-attempt timeout in ms"),
+    connect_timeout_ms: z.number().int().min(0).max(120_000).optional(),
+    accept_timeout_ms: z.number().int().min(0).max(120_000).optional(),
+    server_response_timeout_ms: z.number().int().min(0).max(120_000).optional(),
+    dns_cache_timeout_sec: z.number().int().min(0).max(240).optional(),
+    followRedirects: z.number().int().min(0).max(20).optional(),
+    tryJsonData: z.boolean().optional(),
+    returnBuffer: z.boolean().optional(),
+    validate: ProxyValidateSchema,
+})
+    .describe("The inner HTTP request to send through each proxy attempt. Validation rules here determine when a proxy is treated as failed and retried.");
+const proxyInputShape = {
+    request: ProxyInnerRequestSchema,
+    maxTries: z
+        .number()
+        .int()
+        .min(1)
+        .max(90)
+        .optional()
+        .describe("Maximum proxy rotation attempts before giving up (default 5, max 90)"),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(0)
+        .max(120_000)
+        .optional()
+        .describe("Overall timeout across all rotation attempts in ms (default 45000, max 120000)"),
+    ignoreProxies: z
+        .array(z.string())
+        .optional()
+        .describe("Encoded proxy IDs to exclude from rotation (e.g. ones that failed earlier in your workflow)"),
+};
+export function registerProxyTool(server) {
+    server.registerTool("foura_proxy", {
+        title: "FourA — HTTP request via rotating proxies",
+        description: "Route an HTTP request through FourA's proxy pool with automatic retry across multiple proxies. " +
+            "Per-host proxy rating picks proxies most likely to succeed for the target. Use when foura_single " +
+            "returns 403, captcha, or geo-blocked content. Typical latency 1–5s. The response includes the " +
+            "encoded proxy ID that succeeded ('proxy' field) and the total number of attempts.",
+        inputSchema: proxyInputShape,
+    }, async (input) => {
+        try {
+            await assertPublicTarget(input.request.url);
+        }
+        catch (e) {
+            if (e instanceof SsrfBlockedError) {
+                return { isError: true, content: [{ type: "text", text: e.message }] };
+            }
+            throw e;
+        }
+        const res = await request(PROXY_API_URL, {
+            method: "POST",
+            headers: {
+                "X-API-Key": getApiKey(),
+                "Content-Type": "application/json",
+                "User-Agent": "foura-mcp/0.1.1 (proxy)",
+            },
+            body: JSON.stringify(input),
+        });
+        const text = await res.body.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `FourA proxy — non-JSON response (${res.statusCode}): ${text.slice(0, 200)}`,
+                    },
+                ],
+            };
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            const e = parsed;
+            const hint = e.retryAfter !== undefined ? ` Retry after ${e.retryAfter}s.` : "";
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `FourA proxy error (${res.statusCode}): ${e.error ?? "Unknown"}.${hint}\n\n${JSON.stringify(parsed, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        const parsedObj = parsed;
+        const data = parsedObj.data;
+        let bodyStr = null;
+        if (typeof data === "string")
+            bodyStr = data;
+        else if (data && typeof data === "object")
+            bodyStr = JSON.stringify(data);
+        if (bodyStr && Buffer.byteLength(bodyStr, "utf8") >= THRESHOLD_BYTES) {
+            const ct = extractContentTypeFromHeaderInfo(parsedObj.headers) ?? "text/plain";
+            const stored = await storePayload(bodyStr, ct, "response-body");
+            const preview = bodyStr.slice(0, 500);
+            const trimmed = { ...parsedObj, data: `<offloaded ${stored.size} bytes — see resource ${stored.uri}>` };
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(trimmed, null, 2) },
+                    { type: "text", text: `Body preview (${(stored.size / 1024).toFixed(1)} KB total):\n${preview}` },
+                    { type: "resource_link", uri: stored.uri, name: stored.name, mimeType: stored.mimeType },
+                ],
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=proxy.js.map

package/dist/tools/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/tools/proxy.ts"],"names":[],"mappings":"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"}

package/dist/tools/single.d.ts

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

package/dist/tools/single.js

@@ -0,0 +1,158 @@
+import { request } from "undici";
+import { z } from "zod";
+import { getApiKey } from "../auth.js";
+import { assertPublicTarget, SsrfBlockedError } from "../safe-target.js";
+import { storePayload, THRESHOLD_BYTES } from "../resources.js";
+function extractContentTypeFromHeaderInfo(headers) {
+    if (!Array.isArray(headers))
+        return null;
+    for (const h of headers) {
+        if (h && typeof h === "object") {
+            const ct = h["content-type"];
+            if (typeof ct === "string")
+                return ct.split(";")[0]?.trim() ?? null;
+        }
+    }
+    return null;
+}
+const SINGLE_API_URL = (process.env.FOURA_API_BASE ?? "https://api.foura.ai/api") + "/single/";
+const SingleHttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const SingleValidateSchema = z
+    .object({
+    status: z
+        .object({
+        accept: z.array(z.number().int()).optional().describe("HTTP status codes to treat as success"),
+        fail: z.array(z.number().int()).optional().describe("HTTP status codes to treat as failure"),
+    })
+        .optional(),
+    headers: z
+        .object({
+        accept: z.record(z.string(), z.string()).optional(),
+        fail: z.record(z.string(), z.string()).optional(),
+    })
+        .optional(),
+    data: z
+        .object({
+        accept: z.array(z.string()).optional().describe("Substrings the response body must contain"),
+        fail: z.array(z.string()).optional().describe("Substrings the response body must NOT contain"),
+    })
+        .optional(),
+})
+    .optional();
+const singleInputShape = {
+    method: SingleHttpMethod.describe("HTTP method"),
+    url: z.string().url().describe("Target URL. Use {ts} anywhere in the URL to insert current Unix timestamp (cache-bust)."),
+    headers: z
+        .array(z.tuple([z.string(), z.string()]))
+        .optional()
+        .describe("Custom HTTP headers as [name, value] tuples"),
+    unblocker: z
+        .boolean()
+        .optional()
+        .describe("Inject realistic browser headers (User-Agent, Sec-Ch-Ua, Accept-Encoding, …) and make the request look like it's coming from a real browser at the wire level. Recommended for sites with anti-bot protection."),
+    data: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .optional()
+        .describe("Request body. Strings sent as-is; objects auto-serialized to JSON."),
+    proxy: z
+        .string()
+        .optional()
+        .describe("Optional proxy URL (http://, socks4://, socks5://). For automatic proxy rotation use foura_proxy instead."),
+    timeout_ms: z.number().int().min(0).max(120_000).optional().describe("Overall request timeout in ms (max 120000, default 15000)"),
+    connect_timeout_ms: z.number().int().min(0).max(120_000).optional(),
+    accept_timeout_ms: z.number().int().min(0).max(120_000).optional(),
+    server_response_timeout_ms: z.number().int().min(0).max(120_000).optional(),
+    dns_cache_timeout_sec: z.number().int().min(0).max(240).optional(),
+    followRedirects: z
+        .number()
+        .int()
+        .min(0)
+        .max(20)
+        .optional()
+        .describe("Max number of redirects to follow (0-20). Omit to disable redirect following."),
+    tryJsonData: z.boolean().optional().describe("If true, attempt JSON.parse on response body; on success, data is an object."),
+    returnBuffer: z.boolean().optional().describe("Return raw bytes (base64) instead of decoded string. Use for binary responses (images, protobuf)."),
+    validate: SingleValidateSchema,
+};
+export function registerSingleTool(server) {
+    server.registerTool("foura_single", {
+        title: "FourA — single HTTP request",
+        description: "Send one HTTP request and return the response. Fastest of the three tools (typically 200ms–2s). " +
+            "Use for static pages, JSON APIs, server-rendered HTML. Set unblocker:true if the target has " +
+            "wire-level anti-bot protection. Switch to foura_proxy if you get blocked (403, captcha), or to " +
+            "foura_browser if the page needs JavaScript to render.",
+        inputSchema: singleInputShape,
+    }, async (input) => {
+        try {
+            await assertPublicTarget(input.url);
+        }
+        catch (e) {
+            if (e instanceof SsrfBlockedError) {
+                return { isError: true, content: [{ type: "text", text: e.message }] };
+            }
+            throw e;
+        }
+        const res = await request(SINGLE_API_URL, {
+            method: "POST",
+            headers: {
+                "X-API-Key": getApiKey(),
+                "Content-Type": "application/json",
+                "User-Agent": "foura-mcp/0.1.1 (single)",
+            },
+            body: JSON.stringify(input),
+        });
+        const text = await res.body.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `FourA single — non-JSON response (${res.statusCode}): ${text.slice(0, 200)}`,
+                    },
+                ],
+            };
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            const e = parsed;
+            const hint = e.retryAfter !== undefined ? ` Retry after ${e.retryAfter}s.` : "";
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `FourA single error (${res.statusCode}): ${e.error ?? "Unknown"}.${hint}\n\n${JSON.stringify(parsed, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        const parsedObj = parsed;
+        const data = parsedObj.data;
+        let bodyStr = null;
+        if (typeof data === "string")
+            bodyStr = data;
+        else if (data && typeof data === "object")
+            bodyStr = JSON.stringify(data);
+        if (bodyStr && Buffer.byteLength(bodyStr, "utf8") >= THRESHOLD_BYTES) {
+            const ct = extractContentTypeFromHeaderInfo(parsedObj.headers) ?? "text/plain";
+            const stored = await storePayload(bodyStr, ct, "response-body");
+            const preview = bodyStr.slice(0, 500);
+            const trimmed = { ...parsedObj, data: `<offloaded ${stored.size} bytes — see resource ${stored.uri}>` };
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(trimmed, null, 2) },
+                    { type: "text", text: `Body preview (${(stored.size / 1024).toFixed(1)} KB total):\n${preview}` },
+                    { type: "resource_link", uri: stored.uri, name: stored.name, mimeType: stored.mimeType },
+                ],
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=single.js.map

package/dist/tools/single.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single.js","sourceRoot":"","sources":["../../src/tools/single.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fouradata/mcp",
+  "version": "0.1.1",
+  "description": "MCP server for the FourA web scraping API — three tools for HTTP requests, rotating proxies, and full browser sessions, usable from any MCP client.",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "foura-mcp": "bin/foura-mcp.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/stdio.ts",
+    "dev:http": "tsx src/http.ts",
+    "start:http": "node dist/http.js",
+    "test": "tsx --test tests/**/*.test.ts",
+    "smoke": "node tests/smoke.mjs",
+    "inspector": "npx -y @modelcontextprotocol/inspector tsx src/stdio.ts",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
+    "undici": "^8.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.7.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "foura",
+    "web-scraping",
+    "scraping-api",
+    "rotating-proxies",
+    "anti-bot",
+    "browser-automation"
+  ],
+  "license": "MIT"
+}