@jsonrecon/mcp-server 1.2.0 → 1.3.0

package/README.md

@@ -0,0 +1,58 @@
+# JSON Recon MCP Server
+
+MCP tools for concise Schema.org extraction and field-level Product verification.
+
+## Tools and prices
+
+| Tool | Mode | Price on success |
+| --- | --- | ---: |
+| `check_extractability` | Free preflight | $0 |
+| `extract_schema` | Lite | $0.005 |
+| `extract_schema` | Full | $0.01 |
+| `verify_product` | Verified Product | $0.02 |
+
+Paid tools support either a prepaid JSON Recon API key or an agent-controlled wallet using x402 on Base. The free preflight works without credentials.
+
+## Prepaid API-key setup
+
+```json
+{
+  "mcpServers": {
+    "jsonrecon": {
+      "command": "npx",
+      "args": ["-y", "@jsonrecon/mcp-server"],
+      "env": {
+        "JSONRECON_API_KEY": "jr_liv_xxxxx"
+      }
+    }
+  }
+}
+```
+
+## x402 wallet setup
+
+```json
+{
+  "mcpServers": {
+    "jsonrecon": {
+      "command": "npx",
+      "args": ["-y", "@jsonrecon/mcp-server"],
+      "env": {
+        "JSONRECON_PAYMENT_MODE": "x402",
+        "JSONRECON_EVM_PRIVATE_KEY": "0x_your_32_byte_private_key",
+        "JSONRECON_X402_SESSION_LIMIT_USDC": "1.00"
+      }
+    }
+  }
+}
+```
+
+Use a dedicated, low-balance agent wallet. The private key remains in the local MCP process and is never sent to JSON Recon; only the signed x402 payment authorization is transmitted. The client signs only exact Base-mainnet USDC challenges from the configured JSON Recon origin and route, subject to fixed per-route price ceilings. Redirects are disabled. The default cumulative authorization ceiling is $1 USDC per MCP process and can be lowered with `JSONRECON_X402_SESSION_LIMIT_USDC`.
+
+When both credentials are configured, the default `auto` mode prefers the API key. Set `JSONRECON_PAYMENT_MODE` explicitly to `api_key` or `x402` to override that selection.
+
+## Free-only setup
+
+Omit the `env` block to use `check_extractability` without credentials. Paid tool calls return a configuration error until either payment method is configured.
+
+Learn more at [jsonrecon.com/mcp](https://jsonrecon.com/mcp).

package/dist/index.js

@@ -3,95 +3,225 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
+import { wrapAxiosWithPayment, x402Client, } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
 import { TOOLS } from "./tools.js";
-// Environment setup
-const API_KEY = process.env.JSONRECON_API_KEY;
-// For dev/testing, user might override the endpoint
-const ENDPOINT = process.env.JSONRECON_ENDPOINT || "https://jsonrecon.com";
-if (!API_KEY) {
-    console.error("Missing JSONRECON_API_KEY environment variable.");
-    console.error("Please add it to your MCP configuration.");
-    process.exit(1);
+const VERSION = "1.3.0";
+const BASE_NETWORK = "eip155:8453";
+const BASE_USDC = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+const DEFAULT_ENDPOINT = "https://jsonrecon.com";
+const DEFAULT_SESSION_LIMIT_USDC = "1.00";
+const ROUTE_LIMITS = {
+    "/extract": 10000n,
+    "/extract/lite": 5000n,
+    "/extract/verified": 20000n,
+};
+function normalizeEndpoint(rawEndpoint) {
+    let endpoint;
+    try {
+        endpoint = new URL(rawEndpoint);
+    }
+    catch {
+        throw new Error("JSONRECON_ENDPOINT must be a valid URL.");
+    }
+    const isLoopback = ["127.0.0.1", "::1", "localhost"].includes(endpoint.hostname);
+    if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && isLoopback)) {
+        throw new Error("JSONRECON_ENDPOINT must use HTTPS (HTTP is allowed only for loopback testing).");
+    }
+    if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+        throw new Error("JSONRECON_ENDPOINT must not contain credentials, a query, or a fragment.");
+    }
+    if (endpoint.pathname !== "/" && endpoint.pathname !== "") {
+        throw new Error("JSONRECON_ENDPOINT must be an origin without a path.");
+    }
+    endpoint.pathname = "/";
+    return endpoint;
 }
-const server = new Server({
-    name: "jsonrecon-mcp",
-    version: "1.2.0",
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-// Register tools
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: TOOLS };
+function parseUsdc(value, variableName) {
+    if (!/^(?:0|[1-9]\d*)(?:\.\d{1,6})?$/.test(value)) {
+        throw new Error(`${variableName} must be a non-negative USDC amount with at most 6 decimals.`);
+    }
+    const [whole, fraction = ""] = value.split(".");
+    return BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, "0"));
+}
+function configuredMode() {
+    const value = (process.env.JSONRECON_PAYMENT_MODE || "auto").toLowerCase();
+    if (value !== "auto" && value !== "api_key" && value !== "x402") {
+        throw new Error("JSONRECON_PAYMENT_MODE must be auto, api_key, or x402.");
+    }
+    return value;
+}
+function paidAccessMode() {
+    const mode = configuredMode();
+    if (mode === "api_key") {
+        if (!process.env.JSONRECON_API_KEY) {
+            throw new Error("API-key mode requires JSONRECON_API_KEY.");
+        }
+        return mode;
+    }
+    if (mode === "x402") {
+        if (!process.env.JSONRECON_EVM_PRIVATE_KEY) {
+            throw new Error("x402 mode requires JSONRECON_EVM_PRIVATE_KEY.");
+        }
+        return mode;
+    }
+    if (process.env.JSONRECON_API_KEY)
+        return "api_key";
+    if (process.env.JSONRECON_EVM_PRIVATE_KEY)
+        return "x402";
+    throw new Error("Paid tools require JSONRECON_API_KEY, or JSONRECON_PAYMENT_MODE=x402 with JSONRECON_EVM_PRIVATE_KEY.");
+}
+const endpoint = normalizeEndpoint(process.env.JSONRECON_ENDPOINT || DEFAULT_ENDPOINT);
+const endpointOrigin = endpoint.origin;
+const plainApi = axios.create({
+    baseURL: endpointOrigin,
+    maxRedirects: 0,
+    timeout: 120_000,
 });
-// Handle tool execution
+let authorizedThisSession = 0n;
+function getSessionLimit() {
+    return parseUsdc(process.env.JSONRECON_X402_SESSION_LIMIT_USDC || DEFAULT_SESSION_LIMIT_USDC, "JSONRECON_X402_SESSION_LIMIT_USDC");
+}
+function createX402Api(route) {
+    const privateKey = process.env.JSONRECON_EVM_PRIVATE_KEY;
+    if (!privateKey || !/^0x[0-9a-fA-F]{64}$/.test(privateKey)) {
+        throw new Error("JSONRECON_EVM_PRIVATE_KEY must be a 0x-prefixed 32-byte EVM private key.");
+    }
+    const account = privateKeyToAccount(privateKey);
+    const routeLimit = ROUTE_LIMITS[route];
+    const client = new x402Client()
+        .register(BASE_NETWORK, new ExactEvmScheme(account))
+        .registerPolicy((version, requirements) => requirements.filter((requirement) => {
+        if (version !== 2
+            || requirement.scheme !== "exact"
+            || requirement.network !== BASE_NETWORK
+            || requirement.asset.toLowerCase() !== BASE_USDC
+            || !Number.isSafeInteger(requirement.maxTimeoutSeconds)
+            || requirement.maxTimeoutSeconds <= 0
+            || requirement.maxTimeoutSeconds > 300) {
+            return false;
+        }
+        try {
+            const amount = BigInt(requirement.amount);
+            return amount > 0n && amount <= routeLimit;
+        }
+        catch {
+            return false;
+        }
+    }));
+    client.onBeforePaymentCreation(async ({ paymentRequired, selectedRequirements }) => {
+        let resource;
+        try {
+            resource = new URL(paymentRequired.resource.url);
+        }
+        catch {
+            return { abort: true, reason: "The payment challenge has an invalid resource URL." };
+        }
+        if (resource.origin !== endpointOrigin || resource.pathname !== route) {
+            return { abort: true, reason: "The payment challenge does not match the requested JSON Recon route." };
+        }
+        const amount = BigInt(selectedRequirements.amount);
+        const sessionLimit = getSessionLimit();
+        if (authorizedThisSession + amount > sessionLimit) {
+            return { abort: true, reason: "The JSON Recon x402 session spending limit would be exceeded." };
+        }
+        authorizedThisSession += amount;
+    });
+    return wrapAxiosWithPayment(axios.create({
+        baseURL: endpointOrigin,
+        maxRedirects: 0,
+        timeout: 120_000,
+    }), client);
+}
+async function postPaid(route, body) {
+    const mode = paidAccessMode();
+    if (mode === "api_key") {
+        return plainApi.post(route, body, {
+            headers: {
+                Authorization: `Bearer ${process.env.JSONRECON_API_KEY}`,
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    return createX402Api(route).post(route, body, {
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function safeError(error) {
+    if (axios.isAxiosError(error)) {
+        const body = error.response?.data;
+        return {
+            error: typeof body?.error === "string"
+                ? body.error
+                : `JSON Recon request failed${error.response?.status ? ` with HTTP ${error.response.status}` : ""}.`,
+            ...(typeof body?.reason === "string" ? { reason: body.reason } : {}),
+            ...(typeof body?.refunded === "boolean" ? { refunded: body.refunded } : {}),
+        };
+    }
+    const message = error instanceof Error ? error.message : "Unknown request failure.";
+    if (message.startsWith("Failed to create payment payload:")) {
+        return { error: "The x402 payment challenge was rejected or could not be signed safely." };
+    }
+    const allowed = [
+        "API-key mode requires",
+        "x402 mode requires",
+        "Paid tools require",
+        "JSONRECON_PAYMENT_MODE",
+        "JSONRECON_EVM_PRIVATE_KEY",
+        "JSONRECON_X402_SESSION_LIMIT_USDC",
+    ].some(prefix => message.startsWith(prefix));
+    return { error: allowed ? message : "JSON Recon request failed before a safe response was received." };
+}
+const server = new Server({ name: "jsonrecon-mcp", version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (request.params.name === "extract_schema") {
         const url = String(request.params.arguments?.url);
         const schemaType = String(request.params.arguments?.schema_type || "auto");
         const mode = String(request.params.arguments?.mode || "full");
+        const route = mode === "lite" ? "/extract/lite" : "/extract";
         try {
-            const endpointPath = mode === "lite" ? "/extract/lite" : "/extract";
-            const response = await axios.post(`${ENDPOINT}${endpointPath}`, {
-                url: url,
-                schema_type: schemaType,
-            }, {
-                headers: {
-                    "Authorization": `Bearer ${API_KEY}`,
-                    "Content-Type": "application/json"
-                },
-            });
+            const response = await postPaid(route, { url, schema_type: schemaType });
             return {
                 structuredContent: response.data,
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(response.data, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }],
             };
         }
         catch (error) {
-            const errorMsg = error.response?.data?.error || error.message;
             return {
                 isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: `JsonRecon API Error: ${errorMsg}`,
-                    },
-                ],
+                content: [{ type: "text", text: JSON.stringify(safeError(error), null, 2) }],
             };
         }
     }
     if (request.params.name === "verify_product") {
         const url = String(request.params.arguments?.url);
         try {
-            const response = await axios.post(`${ENDPOINT}/extract/verified`, { url }, { headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" } });
+            const response = await postPaid("/extract/verified", { url });
             return {
                 structuredContent: response.data,
                 content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }],
             };
         }
         catch (error) {
-            const body = error.response?.data;
-            const errorMsg = body?.error || error.message;
             return {
                 isError: true,
-                content: [{ type: "text", text: JSON.stringify({ error: errorMsg, reason: body?.reason, refunded: body?.refunded }, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(safeError(error), null, 2) }],
             };
         }
     }
     if (request.params.name === "check_extractability") {
         const url = String(request.params.arguments?.url);
         try {
-            const response = await axios.get(`${ENDPOINT}/check`, { params: { url } });
+            const response = await plainApi.get("/check", { params: { url } });
             return { content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }] };
         }
         catch (error) {
-            const errorMsg = error.response?.data?.error || error.message;
-            return { isError: true, content: [{ type: "text", text: `JsonRecon API Error: ${errorMsg}` }] };
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify(safeError(error), null, 2) }],
+            };
         }
     }
     throw new Error(`Tool not found: ${request.params.name}`);
@@ -99,9 +229,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("JsonRecon MCP server running on stdio");
+    console.error("JSON Recon MCP server running on stdio");
 }
-main().catch((error) => {
-    console.error("Server error:", error);
+main().catch(() => {
+    console.error("JSON Recon MCP server could not start. Check its non-secret configuration.");
     process.exit(1);
 });

package/package.json

@@ -1,28 +1,32 @@
 {
   "name": "@jsonrecon/mcp-server",
-  "version": "1.2.0",
-  "description": "MCP tools for concise Schema.org extraction and Product verification",
+  "version": "1.3.0",
+  "description": "MCP tools for concise Schema.org extraction and Product verification",
   "main": "dist/index.js",
-  "type": "module",
-  "bin": {
-    "jsonrecon-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "schemas:check": "node ../../scripts/sync-mcp-output-schemas.js --check",
-    "prebuild": "npm run schemas:check",
+  "type": "module",
+  "bin": {
+    "jsonrecon-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "schemas:check": "node ../../scripts/sync-mcp-output-schemas.js --check",
+    "prebuild": "npm run schemas:check",
     "build": "tsc",
     "test": "node --test test/*.test.mjs",
+    "test:live": "npm run build && node test/live-canary.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",
-    "axios": "^1.7.0"
+    "@x402/axios": "2.19.0",
+    "@x402/evm": "2.19.0",
+    "axios": "^1.7.0",
+    "viem": "2.55.4"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",