@spicrawl/mcp 0.0.0-stage → 0.1.0

package/dist/http.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * spicrawl-mcp-http — the Spicrawl MCP server over Streamable HTTP, so a user can
+ * connect an MCP client to a hosted URL instead of installing anything.
+ *
+ *   POST/GET/DELETE /mcp   MCP Streamable HTTP endpoint (Bearer auth)
+ *   GET /healthz           liveness, no auth
+ *
+ * Auth is the caller's own Spicrawl API key (`Authorization: Bearer spicrawl_live_...`);
+ * every tool call runs upstream under that key. One MCP server per session, and
+ * a session is pinned to the key that created it: a request presenting another
+ * key with that session id is refused (403), so no caller can run under someone
+ * else's key. An initialize is refused (401) unless the API accepts the key,
+ * and answered 503 when the API cannot be asked.
+ *
+ *   SPICRAWL_MCP_ADDR   listen address, default 127.0.0.1:8090
+ *   SPICRAWL_BASE_URL   upstream Spicrawl API, default http://127.0.0.1:8080
+ *   SPICRAWL_PUBLIC_BASE_URL  the API as remote callers reach it, used for URLs
+ *                     handed back (browser connect URL); default SPICRAWL_BASE_URL
+ *   SPICRAWL_DOCS_URL   the public docs base URL, read by the docs tools (never
+ *                     sent a key), e.g. http://HOST:8080/docs self-hosted; default
+ *                     SPICRAWL_DOCS_HOST + /docs (legacy), then a self-hosted
+ *                     SPICRAWL_PUBLIC_BASE_URL / SPICRAWL_BASE_URL + /docs, then
+ *                     https://docs.spicrawl.com (see docsBaseFromEnv)
+ *   SPICRAWL_MCP_SESSION_IDLE_MS  idle session eviction, default 1800000 (30 min)
+ */
+export {};

package/dist/http.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * spicrawl-mcp-http — the Spicrawl MCP server over Streamable HTTP, so a user can
+ * connect an MCP client to a hosted URL instead of installing anything.
+ *
+ *   POST/GET/DELETE /mcp   MCP Streamable HTTP endpoint (Bearer auth)
+ *   GET /healthz           liveness, no auth
+ *
+ * Auth is the caller's own Spicrawl API key (`Authorization: Bearer spicrawl_live_...`);
+ * every tool call runs upstream under that key. One MCP server per session, and
+ * a session is pinned to the key that created it: a request presenting another
+ * key with that session id is refused (403), so no caller can run under someone
+ * else's key. An initialize is refused (401) unless the API accepts the key,
+ * and answered 503 when the API cannot be asked.
+ *
+ *   SPICRAWL_MCP_ADDR   listen address, default 127.0.0.1:8090
+ *   SPICRAWL_BASE_URL   upstream Spicrawl API, default http://127.0.0.1:8080
+ *   SPICRAWL_PUBLIC_BASE_URL  the API as remote callers reach it, used for URLs
+ *                     handed back (browser connect URL); default SPICRAWL_BASE_URL
+ *   SPICRAWL_DOCS_URL   the public docs base URL, read by the docs tools (never
+ *                     sent a key), e.g. http://HOST:8080/docs self-hosted; default
+ *                     SPICRAWL_DOCS_HOST + /docs (legacy), then a self-hosted
+ *                     SPICRAWL_PUBLIC_BASE_URL / SPICRAWL_BASE_URL + /docs, then
+ *                     https://docs.spicrawl.com (see docsBaseFromEnv)
+ *   SPICRAWL_MCP_SESSION_IDLE_MS  idle session eviction, default 1800000 (30 min)
+ */
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { ILayerClient, USER_AGENT } from "./client.js";
+import { buildServer } from "./server.js";
+const ADDR = process.env.SPICRAWL_MCP_ADDR || "127.0.0.1:8090";
+const BASE_URL = process.env.SPICRAWL_BASE_URL || "http://127.0.0.1:8080";
+const PUBLIC_BASE_URL = process.env.SPICRAWL_PUBLIC_BASE_URL || BASE_URL;
+const IDLE_MS = Number(process.env.SPICRAWL_MCP_SESSION_IDLE_MS) || 30 * 60 * 1000;
+const MAX_BODY = 4 * 1024 * 1024;
+const KEY_CHECK_TIMEOUT_MS = 5_000;
+const KEY_RE = /^spicrawl_(live|test)_[A-Za-z0-9_-]{8,}$/;
+const sessions = new Map();
+const log = (...a) => console.error(new Date().toISOString(), ...a);
+const hashKey = (k) => createHash("sha256").update(k).digest();
+function rpcError(res, status, code, message, extra = {}) {
+    if (res.headersSent)
+        return;
+    res.writeHead(status, { "Content-Type": "application/json", ...extra });
+    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id: null }));
+}
+function bearer(req) {
+    const h = req.headers.authorization;
+    if (!h)
+        return null;
+    const m = /^Bearer\s+(\S+)\s*$/i.exec(h);
+    return m && KEY_RE.test(m[1]) ? m[1] : null;
+}
+async function readJSON(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > MAX_BODY)
+            throw new Error("body too large");
+        chunks.push(c);
+    }
+    const raw = Buffer.concat(chunks).toString("utf8");
+    return raw ? JSON.parse(raw) : undefined;
+}
+// The key's shape is checked locally, but only the API knows whether it exists.
+// Without asking, a revoked key opens a session and fails only on its first tool
+// call, which clients surface as a broken tool rather than a bad credential.
+// GET /v1/requests needs a valid key and no scope, so any non-401 answer below
+// 500 (a 403 on scope included) proves the key authenticated.
+async function checkKey(key) {
+    let res;
+    try {
+        res = await fetch(`${BASE_URL}/v1/requests?limit=1`, {
+            headers: { Authorization: `Bearer ${key}`, Accept: "application/json", "User-Agent": USER_AGENT },
+            signal: AbortSignal.timeout(KEY_CHECK_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        log("key check: API unreachable:", err instanceof Error ? err.message : String(err));
+        return { ok: false, status: 503, message: "Service Unavailable: could not reach the Spicrawl API to verify the key; retry shortly" };
+    }
+    const text = await res.text().catch(() => "");
+    if (res.status === 401) {
+        let code = "ERR::AUTH::INVALID_KEY";
+        let detail = "the API key is invalid, revoked or expired";
+        try {
+            const p = JSON.parse(text);
+            if (typeof p.code === "string" && p.code)
+                code = p.code;
+            if (typeof p.detail === "string" && p.detail)
+                detail = p.detail;
+            else if (typeof p.title === "string" && p.title)
+                detail = p.title;
+        }
+        catch {
+            // Not a platform problem body; keep the generic wording.
+        }
+        return { ok: false, status: 401, message: `Unauthorized: ${code}: ${detail}` };
+    }
+    // A 5xx says nothing about the key, so refusing it as bad would send the
+    // caller off to rotate a working credential.
+    if (res.status >= 500) {
+        log(`key check: API answered HTTP ${res.status}`);
+        return { ok: false, status: 503, message: `Service Unavailable: the Spicrawl API answered HTTP ${res.status} while verifying the key; retry shortly` };
+    }
+    return { ok: true };
+}
+async function closeSession(id, why) {
+    const s = sessions.get(id);
+    if (!s)
+        return;
+    sessions.delete(id);
+    log(`session ${id.slice(0, 8)} closed (${why}); ${sessions.size} open`);
+    await s.transport.close().catch(() => { });
+    await s.server.close().catch(() => { });
+}
+async function handleMcp(req, res) {
+    const key = bearer(req);
+    if (!key) {
+        return rpcError(res, 401, -32001, "Unauthorized: send your Spicrawl API key as 'Authorization: Bearer spicrawl_live_...'", { "WWW-Authenticate": 'Bearer realm="spicrawl-mcp"' });
+    }
+    const keyHash = hashKey(key);
+    let body;
+    if (req.method === "POST") {
+        try {
+            body = await readJSON(req);
+        }
+        catch {
+            return rpcError(res, 400, -32700, "Parse error: body must be JSON (max 4 MiB)");
+        }
+    }
+    const sid = req.headers["mcp-session-id"];
+    if (typeof sid === "string" && sid) {
+        const s = sessions.get(sid);
+        if (!s)
+            return rpcError(res, 404, -32001, "Session not found or expired: re-initialize");
+        if (!timingSafeEqual(s.keyHash, keyHash)) {
+            log(`session ${sid.slice(0, 8)}: request with a different API key refused`);
+            return rpcError(res, 403, -32003, "Forbidden: this session belongs to a different API key");
+        }
+        s.lastSeen = Date.now();
+        await s.transport.handleRequest(req, res, body);
+        return;
+    }
+    if (req.method !== "POST" || !isInitializeRequest(body)) {
+        return rpcError(res, 400, -32000, "Bad Request: no Mcp-Session-Id; the first request must be initialize");
+    }
+    // Only a new session is checked: an existing one is already bound to this
+    // key's hash, and re-asking the API on every call would double its load.
+    const check = await checkKey(key);
+    if (!check.ok) {
+        return check.status === 401
+            ? rpcError(res, 401, -32001, check.message, { "WWW-Authenticate": 'Bearer realm="spicrawl-mcp"' })
+            : rpcError(res, 503, -32000, check.message, { "Retry-After": "5" });
+    }
+    const server = buildServer(new ILayerClient({ apiKey: key, baseURL: BASE_URL, publicBaseURL: PUBLIC_BASE_URL }));
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (id) => {
+            sessions.set(id, { transport, server, keyHash, lastSeen: Date.now() });
+            log(`session ${id.slice(0, 8)} opened; ${sessions.size} open`);
+        },
+    });
+    transport.onclose = () => {
+        if (transport.sessionId)
+            void closeSession(transport.sessionId, "closed");
+    };
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+}
+const http = createServer((req, res) => {
+    const path = (req.url || "/").split("?")[0];
+    if (path === "/healthz" && (req.method === "GET" || req.method === "HEAD")) {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(req.method === "HEAD" ? undefined : JSON.stringify({ status: "ok", sessions: sessions.size }));
+        return;
+    }
+    if (path !== "/mcp")
+        return rpcError(res, 404, -32601, "Not found: the MCP endpoint is /mcp");
+    if (!["GET", "POST", "DELETE"].includes(req.method || "")) {
+        return rpcError(res, 405, -32000, "Method not allowed", { Allow: "GET, POST, DELETE" });
+    }
+    handleMcp(req, res).catch((err) => {
+        log("request failed:", err instanceof Error ? err.message : String(err));
+        rpcError(res, 500, -32603, "Internal error");
+    });
+});
+// Idle eviction keeps memory bounded: a client that vanishes without DELETE
+// leaves its session behind otherwise.
+setInterval(() => {
+    const cutoff = Date.now() - IDLE_MS;
+    for (const [id, s] of sessions)
+        if (s.lastSeen < cutoff)
+            void closeSession(id, "idle");
+}, 60_000).unref();
+const i = ADDR.lastIndexOf(":");
+const host = i > 0 ? ADDR.slice(0, i).replace(/^\[|\]$/g, "") : "127.0.0.1";
+const port = Number(i >= 0 ? ADDR.slice(i + 1) : ADDR);
+if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    log(`invalid SPICRAWL_MCP_ADDR '${ADDR}' (want host:port)`);
+    process.exit(78);
+}
+http.listen(port, host, () => log(`spicrawl-mcp-http listening on http://${host}:${port}/mcp -> ${BASE_URL}`));
+http.on("error", (err) => {
+    log("spicrawl-mcp-http failed:", err.message);
+    process.exit(1);
+});
+const shutdown = () => {
+    log("shutting down");
+    http.close();
+    for (const id of [...sessions.keys()])
+        void closeSession(id, "shutdown");
+    setTimeout(() => process.exit(0), 2000).unref();
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+//# 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/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * spicrawl-mcp — the Spicrawl web-data platform as native agent tools.
+ *
+ * A thin MCP wrapper over the Spicrawl REST API. Each tool maps to one endpoint;
+ * the caller's API key and the API base URL come from the environment, so the
+ * same server works against a local dev stack or a production deployment.
+ *
+ *   spicrawl-mcp           stdio server (the default; what `npx -y @spicrawl/mcp` runs)
+ *   spicrawl-mcp --http    Streamable HTTP server (dist/http.js; see there for its env)
+ *
+ * Every bin in package.json points at this file. `npx -y @spicrawl/mcp` can only
+ * pick a bin on its own when the package has a bin named `mcp` (too generic to
+ * install globally) or when every bin is the same file, so the HTTP server is a
+ * flag here rather than a second bin. `node dist/http.js` still runs it directly.
+ *
+ *   SPICRAWL_API_KEY   required — a Spicrawl key (spicrawl_live_...)
+ *   SPICRAWL_BASE_URL  optional — default https://api.spicrawl.com
+ *   SPICRAWL_PUBLIC_BASE_URL  optional — base for URLs handed back to the caller
+ *                    (browser connect URL); default SPICRAWL_BASE_URL
+ *   SPICRAWL_DOCS_URL optional — the public docs base URL (docs tools), e.g.
+ *                    http://HOST:8080/docs self-hosted; default SPICRAWL_DOCS_HOST
+ *                    + /docs (legacy), then a self-hosted SPICRAWL_PUBLIC_BASE_URL /
+ *                    SPICRAWL_BASE_URL + /docs, then https://docs.spicrawl.com
+ *
+ * Transport is stdio: this runs as a subprocess of an MCP client (Claude Code,
+ * Claude Desktop, Cursor, …), which is the local-integration case the MCP spec
+ * recommends stdio for.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * spicrawl-mcp — the Spicrawl web-data platform as native agent tools.
+ *
+ * A thin MCP wrapper over the Spicrawl REST API. Each tool maps to one endpoint;
+ * the caller's API key and the API base URL come from the environment, so the
+ * same server works against a local dev stack or a production deployment.
+ *
+ *   spicrawl-mcp           stdio server (the default; what `npx -y @spicrawl/mcp` runs)
+ *   spicrawl-mcp --http    Streamable HTTP server (dist/http.js; see there for its env)
+ *
+ * Every bin in package.json points at this file. `npx -y @spicrawl/mcp` can only
+ * pick a bin on its own when the package has a bin named `mcp` (too generic to
+ * install globally) or when every bin is the same file, so the HTTP server is a
+ * flag here rather than a second bin. `node dist/http.js` still runs it directly.
+ *
+ *   SPICRAWL_API_KEY   required — a Spicrawl key (spicrawl_live_...)
+ *   SPICRAWL_BASE_URL  optional — default https://api.spicrawl.com
+ *   SPICRAWL_PUBLIC_BASE_URL  optional — base for URLs handed back to the caller
+ *                    (browser connect URL); default SPICRAWL_BASE_URL
+ *   SPICRAWL_DOCS_URL optional — the public docs base URL (docs tools), e.g.
+ *                    http://HOST:8080/docs self-hosted; default SPICRAWL_DOCS_HOST
+ *                    + /docs (legacy), then a self-hosted SPICRAWL_PUBLIC_BASE_URL /
+ *                    SPICRAWL_BASE_URL + /docs, then https://docs.spicrawl.com
+ *
+ * Transport is stdio: this runs as a subprocess of an MCP client (Claude Code,
+ * Claude Desktop, Cursor, …), which is the local-integration case the MCP spec
+ * recommends stdio for.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ILayerClient, PACKAGE_VERSION } from "./client.js";
+import { buildServer } from "./server.js";
+const USAGE = `spicrawl-mcp ${PACKAGE_VERSION} — the Spicrawl MCP server
+
+Usage:
+  spicrawl-mcp            run over stdio (for an MCP client; needs SPICRAWL_API_KEY)
+  spicrawl-mcp --http     run the Streamable HTTP server (SPICRAWL_MCP_ADDR, default 127.0.0.1:8090)
+  spicrawl-mcp --version  print the version
+  spicrawl-mcp --help     print this help
+
+Docs: https://docs.spicrawl.com/agents/mcp
+`;
+async function stdio() {
+    const server = buildServer(new ILayerClient({
+        apiKey: process.env.SPICRAWL_API_KEY ?? "",
+        baseURL: process.env.SPICRAWL_BASE_URL,
+        publicBaseURL: process.env.SPICRAWL_PUBLIC_BASE_URL,
+    }));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the transport; logs go to stderr.
+    console.error(`spicrawl-mcp ${PACKAGE_VERSION} ready (stdio)`);
+}
+async function main(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`${PACKAGE_VERSION}\n`);
+        return;
+    }
+    const unknown = args.filter((a) => a !== "--http");
+    if (unknown.length > 0) {
+        console.error(`spicrawl-mcp: unknown argument ${unknown[0]}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    if (args.includes("--http")) {
+        // dist/http.js starts listening when it is loaded.
+        await import("./http.js");
+        return;
+    }
+    await stdio();
+}
+main(process.argv.slice(2)).catch((err) => {
+    console.error("spicrawl-mcp failed to start:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,KAAK,GAAG,gBAAgB,eAAe;;;;;;;;;CAS5C,CAAC;AAEF,KAAK,UAAU,KAAK;IAClB,MAAM,MAAM,GAAG,WAAW,CACxB,IAAI,YAAY,CAAC;QACf,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE;QAC1C,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;QACtC,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB;KACpD,CAAC,CACH,CAAC;IACF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,8CAA8C;IAC9C,OAAO,CAAC,KAAK,CAAC,gBAAgB,eAAe,gBAAgB,CAAC,CAAC;AACjE,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAc;IAChC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,IAAI,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,kCAAkC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,mDAAmD;QACnD,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,MAAM,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACxC,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ILayerClient } from "./client.js";
+export declare const SERVER_NAME = "spicrawl-mcp-server";
+export declare const SERVER_VERSION: string;
+/**
+ * Wraps a raw zod shape into a strict object: unknown keys are a validation
+ * error naming them (with a did-you-mean), and the JSON Schema carries
+ * `additionalProperties: false`. Descriptions and defaults are untouched.
+ */
+export declare function strictArgs<T extends z.ZodRawShape>(shape: T): z.ZodObject<T, "strict", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<T>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<T> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>;
+/**
+ * One MCP server bound to one caller's API key. The stdio entry builds one for
+ * the process; the HTTP entry builds one per session, from that session's key.
+ */
+export declare function buildServer(client: ILayerClient): McpServer;

package/dist/server.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PACKAGE_VERSION } from "./client.js";
+import { registerScrapeTools } from "./tools/scrape.js";
+import { registerBatchTools } from "./tools/batch.js";
+import { registerSessionsTools } from "./tools/sessions.js";
+import { registerUsageTools } from "./tools/usage.js";
+import { registerRequestsTools } from "./tools/requests.js";
+import { registerBrowserTools } from "./tools/browser.js";
+import { registerDocsTools } from "./tools/docs.js";
+export const SERVER_NAME = "spicrawl-mcp-server";
+export const SERVER_VERSION = PACKAGE_VERSION;
+// ---------------------------------------------------------------------------
+// Unknown arguments are refused, never dropped.
+//
+// zod's default object strips keys it does not know, so `js_render: true` (the
+// REST name; the tool calls it `render`) used to become a silent plain fetch —
+// the customer believes rendering is on and is billed for something else. The
+// Spicrawl API refuses unknown fields for exactly this reason; the MCP layer must
+// not bypass that. Every tool's top-level arguments are therefore a strict
+// object: an unknown key fails validation with a message naming it (and the
+// closest real argument), and tools/list advertises `additionalProperties:
+// false`. Free-form maps inside a tool (headers, JSON Schemas, records) stay open.
+// ---------------------------------------------------------------------------
+/** Names an agent is likely to guess (REST / other-scraper spellings) -> the tool's name. */
+const ALIASES = {
+    js_render: "render",
+    javascript: "render",
+    response_format: "format",
+    formats: "format",
+    only_main_content: "main_content_only",
+    onlyMainContent: "main_content_only",
+    includeTags: "include_tags",
+    excludeTags: "exclude_tags",
+    waitFor: "wait_for",
+    headers: "custom_headers",
+    country: "proxy_country",
+};
+const normalise = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+function levenshtein(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/** The valid argument closest to `key`, if one is close enough to be a plausible typo. */
+function closestArgument(key, valid) {
+    const alias = ALIASES[key];
+    if (alias && valid.includes(alias))
+        return alias;
+    const nk = normalise(key);
+    // Candidates: every valid name, plus every alias whose target is valid (so a
+    // typo of a REST name, e.g. `js_rendr`, still lands on `render`).
+    const candidates = valid.map((v) => [v, v]);
+    for (const [a, target] of Object.entries(ALIASES))
+        if (valid.includes(target))
+            candidates.push([a, target]);
+    let best;
+    let bestDistance = Infinity;
+    for (const [spelling, target] of candidates) {
+        const d = levenshtein(nk, normalise(spelling));
+        if (d < bestDistance)
+            [best, bestDistance] = [target, d];
+    }
+    return bestDistance <= Math.max(1, Math.floor(nk.length / 3)) ? best : undefined;
+}
+function unknownArgumentsMessage(keys, valid) {
+    let unresolved = false;
+    const parts = keys.map((k) => {
+        const s = closestArgument(k, valid);
+        if (!s)
+            unresolved = true;
+        return s ? `unknown argument \`${k}\`; did you mean \`${s}\`?` : `unknown argument \`${k}\``;
+    });
+    let msg = parts.join("; ");
+    if (unresolved) {
+        msg += valid.length
+            ? ` (valid arguments: ${valid.map((v) => `\`${v}\``).join(", ")})`
+            : " (this tool takes no arguments)";
+    }
+    return msg;
+}
+/**
+ * Wraps a raw zod shape into a strict object: unknown keys are a validation
+ * error naming them (with a did-you-mean), and the JSON Schema carries
+ * `additionalProperties: false`. Descriptions and defaults are untouched.
+ */
+export function strictArgs(shape) {
+    const valid = Object.keys(shape);
+    const errorMap = (issue, ctx) => issue.code === z.ZodIssueCode.unrecognized_keys
+        ? { message: unknownArgumentsMessage(issue.keys, valid) }
+        : { message: ctx.defaultError };
+    return z.object(shape, { errorMap }).strict();
+}
+/** Makes a registerTool inputSchema strict: raw shapes and non-strict zod objects. */
+function strictInputSchema(schema) {
+    if (schema === undefined)
+        return undefined; // no schema -> SDK passes no args at all
+    if (schema instanceof z.ZodObject) {
+        return schema._def.unknownKeys === "strip" ? strictArgs(schema.shape) : schema;
+    }
+    const isSchemaInstance = "_def" in schema || "_zod" in schema;
+    return isSchemaInstance ? schema : strictArgs(schema);
+}
+/**
+ * McpServer whose registerTool makes every tool's input schema strict. Tools
+ * keep declaring plain raw shapes; this one place guarantees none of them (or
+ * any tool added later) can silently drop an argument.
+ */
+class StrictArgsMcpServer extends McpServer {
+    registerTool(name, config, cb) {
+        // The strict object parses to exactly what the raw shape did, so the
+        // callback's argument type is unchanged; only the declared type widens.
+        return super.registerTool(name, { ...config, inputSchema: strictInputSchema(config.inputSchema) }, cb);
+    }
+}
+/**
+ * One MCP server bound to one caller's API key. The stdio entry builds one for
+ * the process; the HTTP entry builds one per session, from that session's key.
+ */
+export function buildServer(client) {
+    const server = new StrictArgsMcpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    for (const register of [
+        registerScrapeTools,
+        registerBatchTools,
+        registerSessionsTools,
+        registerUsageTools,
+        registerRequestsTools,
+        registerBrowserTools,
+        registerDocsTools,
+    ]) {
+        register(server, client);
+    }
+    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":"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"}