@true402.dev/mcp-server 0.4.0 → 0.6.0

package/dist/index.js

@@ -17,21 +17,29 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { registerModelsTool } from "./tools/models.js";
 import { registerChatTool } from "./tools/chat.js";
 import { registerStallTools } from "./tools/stalls.js";
+import { registerDiscoveredStalls } from "./tools/discover.js";
 const SERVER_URL = process.env.SERVER_URL ?? "https://true402.dev/api";
 const WALLET_PRIVATE_KEY = process.env.WALLET_PRIVATE_KEY;
 const server = new McpServer({
     name: "true402",
-    version: "0.4.0",
+    version: "0.6.0",
 });
-// Register tools
-registerModelsTool(server, SERVER_URL);
-registerChatTool(server, SERVER_URL, WALLET_PRIVATE_KEY);
-// Non-LLM paid stalls: web utilities (seo_audit, web_extract, link_preview,
-// robots_check, headers_check) + Base on-chain signals (token_safety, new_pairs,
-// liquidity_pulls, whale_swaps) — all x402-gated, USDC on Base.
-registerStallTools(server, SERVER_URL, WALLET_PRIVATE_KEY);
 // Start server with stdio transport
 async function main() {
+    // Always-present built-in tools (LLM router — chat uses a $ref body + streaming, so it stays
+    // hand-written rather than discovered).
+    registerModelsTool(server, SERVER_URL);
+    registerChatTool(server, SERVER_URL, WALLET_PRIVATE_KEY);
+    // Paid stalls: ASK THE SERVER. Fetch its OpenAPI spec and register an MCP tool for every paid
+    // POST endpoint (x-payment-info), so a new marketplace stall surfaces automatically with no MCP
+    // release. Falls back to the built-in stall list only if the server is unreachable at startup.
+    const discovered = await registerDiscoveredStalls(server, SERVER_URL, WALLET_PRIVATE_KEY);
+    if (discovered) {
+        console.error(`true402 MCP: discovered ${discovered.length} paid stalls from ${SERVER_URL} (${discovered.join(", ")})`);
+    }
+    else {
+        registerStallTools(server, SERVER_URL, WALLET_PRIVATE_KEY);
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/tools/discover.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Fetch `${baseUrl}/openapi.json` and register an MCP tool for each paid POST stall.
+ * Returns the registered tool names, or null if discovery failed (caller should fall back).
+ */
+export declare function registerDiscoveredStalls(server: McpServer, baseUrl: string, walletPrivateKey: string | undefined): Promise<string[] | null>;

package/dist/tools/discover.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { registerStall } from "./stalls.js";
+/** Map one JSON-Schema property to a zod validator (covers the property kinds the stalls use). */
+function toZod(prop) {
+    let base;
+    if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+        base = z.enum(prop.enum.map(String));
+    }
+    else if (prop.type === "number" || prop.type === "integer") {
+        base = z.number();
+    }
+    else if (prop.type === "boolean") {
+        base = z.boolean();
+    }
+    else {
+        base = z.string();
+    }
+    return prop.description ? base.describe(prop.description) : base;
+}
+/** Build a zod raw shape from a request-body JSON Schema's `properties` + `required`. */
+function bodyToShape(schema) {
+    const shape = {};
+    const required = new Set(schema?.required ?? []);
+    for (const [key, prop] of Object.entries(schema?.properties ?? {})) {
+        const v = toZod(prop);
+        shape[key] = required.has(key) ? v : v.optional();
+    }
+    return shape;
+}
+/**
+ * Fetch `${baseUrl}/openapi.json` and register an MCP tool for each paid POST stall.
+ * Returns the registered tool names, or null if discovery failed (caller should fall back).
+ */
+export async function registerDiscoveredStalls(server, baseUrl, walletPrivateKey) {
+    let spec;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10_000);
+        const res = await fetch(`${baseUrl}/openapi.json`, {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        spec = (await res.json());
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`true402 MCP: stall discovery from ${baseUrl}/openapi.json failed (${msg}); using built-in stall list`);
+        return null;
+    }
+    // OpenAPI path keys carry the base path (e.g. /api/v1/x); strip it so the tool path is relative
+    // to baseUrl (which already includes /api), matching how payAndFetch joins baseUrl + path.
+    let basePath = "";
+    try {
+        basePath = new URL(baseUrl).pathname.replace(/\/+$/, "");
+    }
+    catch {
+        /* baseUrl is relative — keys are already root-relative */
+    }
+    const registered = [];
+    for (const [key, ops] of Object.entries(spec.paths ?? {})) {
+        const op = ops.post;
+        if (!op || op["x-payment-info"] === undefined)
+            continue; // paid stalls only
+        if (key.endsWith("/chat/completions"))
+            continue; // chat is special-cased (hardcoded)
+        const rel = basePath && key.startsWith(basePath) ? key.slice(basePath.length) : key;
+        const toolName = (rel.replace(/\/+$/, "").split("/").pop() ?? "").replace(/-/g, "_");
+        if (!toolName)
+            continue;
+        const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+        const description = (op.description ?? op.summary ?? `Paid x402 stall ${rel}`) +
+            " (PAID x402 service — USDC on Base; the MCP server needs a funded wallet to settle.)";
+        registerStall(server, baseUrl, walletPrivateKey, {
+            toolName,
+            path: rel,
+            description,
+            inputSchema: bodyToShape(bodySchema),
+            // The discovered zod shape already mirrors the body, so pass validated args straight through.
+            buildBody: (args) => {
+                const body = {};
+                for (const [k, v] of Object.entries(args ?? {}))
+                    if (v !== undefined)
+                        body[k] = v;
+                return body;
+            },
+        });
+        registered.push(toolName);
+    }
+    return registered;
+}

package/dist/tools/stalls.d.ts

@@ -1,4 +1,37 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodRawShapeCompat, ShapeOutput } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+/**
+ * Paid, non-LLM stalls exposed by the true402 marketplace.
+ *
+ * Each of these is an x402-gated POST endpoint that takes a small JSON body and
+ * returns a structured JSON report. They are all PAID services (USDC on Base):
+ * the MCP server must have a funded wallet (WALLET_PRIVATE_KEY) configured for
+ * the calls to settle. With no wallet, the tools surface the 402 payment
+ * requirements instead of crashing.
+ */
+/**
+ * A generic paid stall: an MCP tool that POSTs a body to an x402-gated path and
+ * returns the parsed JSON report. The input type is inferred from the zod raw
+ * shape `Schema`, and the body is built from the validated tool args via
+ * `buildBody`.
+ */
+export interface StallSpec<Schema extends ZodRawShapeCompat> {
+    /** MCP tool name (e.g. "seo_audit"). */
+    toolName: string;
+    /** Server-side endpoint path (e.g. "/v1/seo-audit"). */
+    path: string;
+    /** Agent-facing description. Should make clear this is a PAID x402 service. */
+    description: string;
+    /** Zod raw shape (plain object of validators) describing the tool inputs. */
+    inputSchema: Schema;
+    /** Map validated args to the JSON request body sent to the endpoint. */
+    buildBody: (args: ShapeOutput<Schema>) => Record<string, unknown>;
+}
+/**
+ * Register a single paid stall as an MCP tool. The handler runs the shared
+ * x402 pay-and-retry flow and maps the result into the MCP content shape.
+ */
+export declare function registerStall<Schema extends ZodRawShapeCompat>(server: McpServer, baseUrl: string, walletPrivateKey: string | undefined, spec: StallSpec<Schema>): void;
 /**
  * Register all nine non-LLM paid stalls on the given MCP server: the web utilities
  * (seo_audit, web_extract, link_preview, robots_check, headers_check) and the Base

package/dist/tools/stalls.js

@@ -4,7 +4,7 @@ import { payAndFetch } from "../x402-pay.js";
  * Register a single paid stall as an MCP tool. The handler runs the shared
  * x402 pay-and-retry flow and maps the result into the MCP content shape.
  */
-function registerStall(server, baseUrl, walletPrivateKey, spec) {
+export function registerStall(server, baseUrl, walletPrivateKey, spec) {
     const handler = async (args) => {
         const body = spec.buildBody(args);
         const result = await payAndFetch(baseUrl, spec.path, body, walletPrivateKey);

package/dist/x402-pay.d.ts

@@ -47,6 +47,16 @@ export interface EVMPaymentRequirement {
         version?: string;
     };
 }
+/**
+ * Guard a 402 requirement BEFORE signing: a hostile/buggy server must not make the wallet sign a
+ * draining amount or an off-spec asset. Returns a refusal string, or null if the payment is allowed.
+ * - amount must be ≤ `maxUsdc` (the client-side spend ceiling, MAX_PAYMENT_USDC).
+ * - asset must be the canonical USDC on a supported chain (no arbitrary token/verifyingContract).
+ */
+export declare function assessRequirement(req: EVMPaymentRequirement, maxUsdc: number): string | null;
+/** Refuse to send a signed payment over cleartext (the X-PAYMENT header would be interceptable).
+ *  Returns a refusal string, or null if the URL is https (or localhost for dev). */
+export declare function requireSecureUrl(url: string): string | null;
 /**
  * Sign an EIP-3009 TransferWithAuthorization and return the x402 payment
  * payload. The EIP-712 domain is derived from the requirement (network +

package/dist/x402-pay.js

@@ -65,6 +65,57 @@ function resolveChainId(network) {
         }
     }
 }
+// Canonical USDC per chain — the ONLY token/chain this client will ever sign a payment for, so a
+// hostile or buggy server cannot redirect the wallet's signature to an arbitrary token/chain.
+const USDC_BY_CHAIN = {
+    8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base mainnet
+    84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // Base Sepolia
+    1: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // Ethereum mainnet
+};
+/**
+ * Guard a 402 requirement BEFORE signing: a hostile/buggy server must not make the wallet sign a
+ * draining amount or an off-spec asset. Returns a refusal string, or null if the payment is allowed.
+ * - amount must be ≤ `maxUsdc` (the client-side spend ceiling, MAX_PAYMENT_USDC).
+ * - asset must be the canonical USDC on a supported chain (no arbitrary token/verifyingContract).
+ */
+export function assessRequirement(req, maxUsdc) {
+    const raw = req.amount ?? req.maxAmountRequired;
+    if (raw === undefined)
+        return "the 402 has no amount; refusing to sign.";
+    let amountUsdc;
+    try {
+        amountUsdc = Number(BigInt(raw)) / 1e6; // USDC has 6 decimals
+    }
+    catch {
+        return "the 402 amount is unparseable; refusing to sign.";
+    }
+    if (!Number.isFinite(amountUsdc) || amountUsdc < 0)
+        return "the 402 amount is invalid; refusing to sign.";
+    if (Number.isFinite(maxUsdc) && amountUsdc > maxUsdc) {
+        return `refusing to auto-pay $${amountUsdc} USDC — it exceeds the MAX_PAYMENT_USDC ceiling of $${maxUsdc}. Raise MAX_PAYMENT_USDC if this is intended.`;
+    }
+    const usdc = USDC_BY_CHAIN[resolveChainId(req.network)];
+    if (!usdc || (req.asset ?? "").toLowerCase() !== usdc.toLowerCase()) {
+        return "refusing to pay: the 402's asset/network is not canonical USDC on a supported Base network.";
+    }
+    return null;
+}
+/** Refuse to send a signed payment over cleartext (the X-PAYMENT header would be interceptable).
+ *  Returns a refusal string, or null if the URL is https (or localhost for dev). */
+export function requireSecureUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return `invalid SERVER_URL: ${url}`;
+    }
+    const local = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+    if (u.protocol !== "https:" && !local) {
+        return `refusing to send a signed payment over cleartext (${u.protocol}//${u.hostname}); use an https SERVER_URL (or localhost for dev).`;
+    }
+    return null;
+}
 /**
  * Sign an EIP-3009 TransferWithAuthorization and return the x402 payment
  * payload. The EIP-712 domain is derived from the requirement (network +
@@ -150,6 +201,10 @@ export async function signEIP3009Payment(privateKey, requirement) {
  */
 export async function payAndFetch(baseUrl, path, body, walletPrivateKey) {
     const url = `${baseUrl}${path}`;
+    // Step 0: never sign/send a payment over cleartext (X-PAYMENT would be interceptable).
+    const insecure = requireSecureUrl(url);
+    if (insecure)
+        return { ok: false, message: insecure };
     // Step 1: first request, no payment header.
     let firstResponse;
     try {
@@ -210,6 +265,13 @@ export async function payAndFetch(baseUrl, path, body, walletPrivateKey) {
             ].join("\n"),
         };
     }
+    // Spend ceiling + asset/network pin: a hostile server must not make our wallet sign a draining
+    // amount or a payment to an arbitrary token/chain. Refuse BEFORE signing.
+    const maxUsdc = Number(process.env.MAX_PAYMENT_USDC ?? "0.10");
+    const refusal = assessRequirement(evmRequirement, maxUsdc);
+    if (refusal) {
+        return { ok: false, paymentRequired: true, message: refusal };
+    }
     // Step 4: sign the EIP-3009 authorization and base64-encode the payload.
     let xPaymentHeader;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@true402.dev/mcp-server",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "mcpName": "dev.true402/mcp-server",
   "description": "MCP server for the true402 machine-native marketplace — pay-per-call AI + web + Base on-chain tools over x402 (USDC on Base): LLM inference, SEO/GEO audit, web extract, link preview, robots/AI-crawler check, security headers, and on-chain DeFi trading signals (token rug/honeypot safety, new token pairs, liquidity-pull/rug alerts, whale swaps).",
   "type": "module",
@@ -16,6 +16,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -51,7 +52,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
   },
   "engines": {
     "node": ">=20.0.0"