@true402.dev/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 true402
+
+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,72 @@
+# @true402.dev/mcp-server
+
+MCP server for the **[true402](https://true402.dev)** machine-native marketplace — give your agent pay-per-call access to AI inference and web tools over [x402](https://x402.org) (HTTP 402 micropayments in USDC on Base).
+
+No accounts, no API keys. The agent's **wallet is its identity**: each paid tool returns an HTTP 402 challenge, the server signs an EIP-3009 USDC authorization, and the call settles on-chain. Configure a funded wallet to auto-pay, or run without one and the paid tools will surface the exact payment requirements instead of failing.
+
+## Tools
+
+| Tool | Price | What it does |
+|------|-------|--------------|
+| `chat` | per-token + 3% | OpenAI-compatible LLM inference across many models |
+| `list_models` | free | List available models + pricing |
+| `seo_audit` | $0.02 | SEO + GEO (generative-engine-optimization) audit of a page → structured report |
+| `web_extract` | $0.005 | Fetch a URL → clean text + markdown + links + metadata |
+| `link_preview` | $0.003 | Fetch a URL → Open Graph / unfurl card |
+| `robots_check` | $0.003 | A site's AI-crawler policy (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, …) + sitemaps + llms.txt |
+| `headers_check` | $0.003 | HTTP security-headers analysis (HSTS, CSP, …) + a 0–100 score |
+
+Prices are illustrative; the live 402 challenge is authoritative.
+
+## Install
+
+Requires Node.js ≥ 20. Runs over stdio — point any MCP client at it via `npx`.
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json`, or `.mcp.json` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "true402": {
+      "command": "npx",
+      "args": ["-y", "@true402.dev/mcp-server"],
+      "env": {
+        "WALLET_PRIVATE_KEY": "0xYOUR_FUNDED_BASE_WALLET_KEY"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Cline / other MCP clients
+
+Same idea — command `npx`, args `["-y", "@true402.dev/mcp-server"]`, and the `WALLET_PRIVATE_KEY` env var.
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `SERVER_URL` | `https://true402.dev/api` | true402 API base. Override to point at a self-hosted instance. |
+| `WALLET_PRIVATE_KEY` | _(none)_ | A funded **Base** wallet private key used to sign x402 payments. Needs **USDC** (gas is sponsored by the facilitator — no ETH required). Without it, paid tools return the 402 requirements instead of paying. |
+
+> **Security:** the key is read only from the environment and is never logged, echoed, or returned. Use a dedicated low-balance wallet — fund it with only what you intend to spend.
+
+## How payment works
+
+1. The tool calls the true402 endpoint with no payment.
+2. The server replies `402` with accepted payment options (USDC on Base).
+3. This MCP server signs an EIP-3009 `transferWithAuthorization` with your wallet.
+4. It retries with the signed `X-PAYMENT` header; the service verifies and responds.
+5. Settlement happens on-chain. Your wallet pays only USDC — the facilitator sponsors gas.
+
+## Links
+
+- Marketplace: <https://true402.dev>
+- Live tool catalog: <https://true402.dev/api/v1/services>
+- x402 protocol: <https://x402.org>
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * true402 MCP Server
+ *
+ * Exposes the true402 machine-native marketplace as MCP tools for Claude and other
+ * MCP-compatible clients: LLM inference plus the paid web stalls (SEO/GEO audit, web
+ * extract, link preview, robots/AI-crawler check, security-headers check). Each paid
+ * tool is x402-gated (USDC on Base); set WALLET_PRIVATE_KEY to auto-pay. Uses stdio.
+ *
+ * Environment variables:
+ *   SERVER_URL          - true402 API base (default: https://true402.dev/api)
+ *   WALLET_PRIVATE_KEY  - funded Base wallet key for x402 payment signing (optional;
+ *                         without it, paid tools surface the 402 requirements instead)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * true402 MCP Server
+ *
+ * Exposes the true402 machine-native marketplace as MCP tools for Claude and other
+ * MCP-compatible clients: LLM inference plus the paid web stalls (SEO/GEO audit, web
+ * extract, link preview, robots/AI-crawler check, security-headers check). Each paid
+ * tool is x402-gated (USDC on Base); set WALLET_PRIVATE_KEY to auto-pay. Uses stdio.
+ *
+ * Environment variables:
+ *   SERVER_URL          - true402 API base (default: https://true402.dev/api)
+ *   WALLET_PRIVATE_KEY  - funded Base wallet key for x402 payment signing (optional;
+ *                         without it, paid tools surface the 402 requirements instead)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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";
+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.2.0",
+});
+// Register tools
+registerModelsTool(server, SERVER_URL);
+registerChatTool(server, SERVER_URL, WALLET_PRIVATE_KEY);
+// Non-LLM paid stalls: seo_audit, web_extract, link_preview,
+// robots_check, headers_check (all x402-gated, USDC on Base).
+registerStallTools(server, SERVER_URL, WALLET_PRIVATE_KEY);
+// Start server with stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/tools/chat.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register the chat tool.
+ * Calls POST /v1/chat/completions on the true402 endpoint.
+ * Handles the x402 payment flow (402 -> sign -> retry with X-Payment header)
+ * via the shared {@link payAndFetch} helper.
+ */
+export declare function registerChatTool(server: McpServer, baseUrl: string, walletPrivateKey: string | undefined): void;

package/dist/tools/chat.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { payAndFetch } from "../x402-pay.js";
+/**
+ * Register the chat tool.
+ * Calls POST /v1/chat/completions on the true402 endpoint.
+ * Handles the x402 payment flow (402 -> sign -> retry with X-Payment header)
+ * via the shared {@link payAndFetch} helper.
+ */
+export function registerChatTool(server, baseUrl, walletPrivateKey) {
+    server.tool("chat", "Send a chat completion request to an LLM via true402 (PAID x402 service, USDC on Base). Requires a funded wallet (WALLET_PRIVATE_KEY) on the MCP server.", {
+        model: z.string().describe("Model ID (e.g. gpt-4o, claude-3-5-sonnet)"),
+        messages: z
+            .array(z.object({
+            role: z.string().describe("Message role: system, user, or assistant"),
+            content: z.string().describe("Message content"),
+        }))
+            .describe("Chat messages"),
+        max_tokens: z
+            .number()
+            .optional()
+            .describe("Maximum tokens to generate"),
+    }, async ({ model, messages, max_tokens }) => {
+        const body = { model, messages };
+        if (max_tokens !== undefined) {
+            body.max_tokens = max_tokens;
+        }
+        const result = await payAndFetch(baseUrl, "/v1/chat/completions", body, walletPrivateKey);
+        if (!result.ok) {
+            return {
+                content: [{ type: "text", text: result.message }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result.data, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/models.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register the list_models tool.
+ * Calls GET /v1/models on the true402 endpoint.
+ */
+export declare function registerModelsTool(server: McpServer, baseUrl: string): void;

package/dist/tools/models.js

@@ -0,0 +1,30 @@
+/**
+ * Register the list_models tool.
+ * Calls GET /v1/models on the true402 endpoint.
+ */
+export function registerModelsTool(server, baseUrl) {
+    server.tool("list_models", "List available LLM models with pricing from true402", {}, async () => {
+        const response = await fetch(`${baseUrl}/v1/models`);
+        if (!response.ok) {
+            const text = await response.text();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching models: ${response.status} ${text}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const data = await response.json();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/stalls.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register all five non-LLM paid stalls (seo_audit, web_extract, link_preview,
+ * robots_check, headers_check) on the given MCP server.
+ */
+export declare function registerStallTools(server: McpServer, baseUrl: string, walletPrivateKey: string | undefined): void;

package/dist/tools/stalls.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+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) {
+    const handler = async (args) => {
+        const body = spec.buildBody(args);
+        const result = await payAndFetch(baseUrl, spec.path, body, walletPrivateKey);
+        if (!result.ok) {
+            return {
+                content: [{ type: "text", text: result.message }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result.data, null, 2),
+                },
+            ],
+        };
+    };
+    server.tool(spec.toolName, spec.description, spec.inputSchema, handler);
+}
+// A required http/https page URL — shared by every stall.
+const urlField = z
+    .string()
+    .url()
+    .describe("Absolute http(s) URL of the page to process");
+/**
+ * Register all five non-LLM paid stalls (seo_audit, web_extract, link_preview,
+ * robots_check, headers_check) on the given MCP server.
+ */
+export function registerStallTools(server, baseUrl, walletPrivateKey) {
+    // 1. SEO + GEO audit.
+    registerStall(server, baseUrl, walletPrivateKey, {
+        toolName: "seo_audit",
+        path: "/v1/seo-audit",
+        description: "Audit a web page for SEO + GEO (generative-engine-optimization). " +
+            "Returns a structured JSON report: meta tags, an SEO score with " +
+            "per-category breakdown + issues, a GEO score with breakdown + " +
+            "issues, and a combined percentage. PAID x402 service (USDC on " +
+            "Base) — needs a funded wallet on the MCP server.",
+        inputSchema: {
+            url: urlField,
+            mode: z
+                .enum(["both", "seo", "geo"])
+                .optional()
+                .describe("Which audit(s) to run: 'both' (default), 'seo' only, or 'geo' only"),
+        },
+        buildBody: ({ url, mode }) => {
+            const body = { url };
+            if (mode !== undefined)
+                body.mode = mode;
+            return body;
+        },
+    });
+    // 2. Clean web extraction (readable text + markdown + links + metadata).
+    registerStall(server, baseUrl, walletPrivateKey, {
+        toolName: "web_extract",
+        path: "/v1/web-extract",
+        description: "Fetch a URL and return its clean readable text, a light markdown " +
+            "rendering, all links (in document order), and metadata (title, " +
+            "description, word count, byte size). PAID x402 service (USDC on " +
+            "Base) — needs a funded wallet on the MCP server.",
+        inputSchema: { url: urlField },
+        buildBody: ({ url }) => ({ url }),
+    });
+    // 3. Link preview / Open Graph card.
+    registerStall(server, baseUrl, walletPrivateKey, {
+        toolName: "link_preview",
+        path: "/v1/link-preview",
+        description: "Fetch a URL and return its link-preview / Open Graph unfurl card: " +
+            "title, description, image, siteName, type, canonical URL, favicon, " +
+            "and theme color (image/canonical/favicon resolved to absolute URLs). " +
+            "PAID x402 service (USDC on Base) — needs a funded wallet on the MCP " +
+            "server.",
+        inputSchema: { url: urlField },
+        buildBody: ({ url }) => ({ url }),
+    });
+    // 4. AI-crawler / robots.txt policy check.
+    registerStall(server, baseUrl, walletPrivateKey, {
+        toolName: "robots_check",
+        path: "/v1/robots-check",
+        description: "Report a site's AI-crawler policy (GPTBot, ClaudeBot, Google-Extended, " +
+            "PerplexityBot, and ~15 other AI bots: allow | block | unspecified), " +
+            "plus declared sitemaps and whether an llms.txt is present. Pass any " +
+            "URL on the target site. PAID x402 service (USDC on Base) — needs a " +
+            "funded wallet on the MCP server.",
+        inputSchema: { url: urlField },
+        buildBody: ({ url }) => ({ url }),
+    });
+    // 5. HTTP security-headers analysis.
+    registerStall(server, baseUrl, walletPrivateKey, {
+        toolName: "headers_check",
+        path: "/v1/headers-check",
+        description: "Analyse a URL's HTTP security headers (HSTS, CSP, X-Frame-Options, " +
+            "and more) into a present/missing breakdown plus a 0-100 score, along " +
+            "with status, HTTPS flag, and server banner. PAID x402 service (USDC " +
+            "on Base) — needs a funded wallet on the MCP server.",
+        inputSchema: { url: urlField },
+        buildBody: ({ url }) => ({ url }),
+    });
+}

package/dist/x402-pay.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared x402 payment helper for the true402 MCP server.
+ *
+ * Encapsulates the full pay-and-retry flow used by every paid stall:
+ *   1. POST the request body (no payment header)
+ *   2. If the server replies 402, parse the payment requirements
+ *   3. Pick the EVM (scheme: "exact") option, sign an EIP-3009
+ *      TransferWithAuthorization with the configured wallet
+ *   4. Retry with the base64-encoded `X-PAYMENT` header
+ *   5. Return the parsed JSON (or a structured error)
+ *
+ * The signer is network-aware: it derives the EIP-712 domain (chainId,
+ * verifyingContract, name, version) from the 402 requirement itself, so it
+ * works on Base mainnet, Base Sepolia, or any future network the server
+ * advertises — instead of being hardcoded to one chain.
+ *
+ * SECURITY: the wallet private key is never logged, echoed, or returned.
+ */
+import { type Hex } from "viem";
+/**
+ * EVM payment requirement from a 402 response (scheme: "exact").
+ */
+export interface EVMPaymentRequirement {
+    scheme: "exact";
+    network: string;
+    /**
+     * Amount in USDC base units. x402 v2 advertises this as `amount`; v1 used
+     * `maxAmountRequired`. We read either so the client works against both.
+     */
+    amount?: string;
+    maxAmountRequired?: string;
+    asset: string;
+    payTo: string;
+    facilitatorUrl: string;
+    maxTimeoutSeconds: number;
+    mimeType: string;
+    description?: string;
+    resource?: {
+        url: string;
+        method: string;
+    };
+    /**
+     * Optional EIP-712 USDC domain advertised by the server.
+     * Base mainnet USDC uses name "USD Coin"; Base Sepolia test USDC uses "USDC".
+     */
+    extra?: {
+        name?: string;
+        version?: string;
+    };
+}
+/**
+ * Sign an EIP-3009 TransferWithAuthorization and return the x402 payment
+ * payload. The EIP-712 domain is derived from the requirement (network +
+ * asset + advertised domain name/version) so signatures are valid on the
+ * exact chain the 402 demands.
+ */
+export declare function signEIP3009Payment(privateKey: Hex, requirement: EVMPaymentRequirement): Promise<object>;
+/**
+ * Discriminated result of {@link payAndFetch}.
+ *
+ * - `ok: true`  -> `data` holds the parsed JSON returned by the endpoint.
+ * - `ok: false` -> `message` is a human/agent-readable explanation and
+ *   `paymentRequired` is true when the failure was a 402 we could not satisfy
+ *   (so the caller can surface the requirements clearly).
+ */
+export type PayAndFetchResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    message: string;
+    paymentRequired?: boolean;
+};
+/**
+ * Perform the full x402 flow against `${baseUrl}${path}` with the given JSON
+ * `body`. Returns the parsed JSON on success, or a structured error.
+ *
+ * If no wallet key is configured and the endpoint demands payment, this does
+ * NOT crash — it returns `{ ok: false, paymentRequired: true, message }` with
+ * the raw requirements embedded so an agent knows it must fund a wallet.
+ */
+export declare function payAndFetch(baseUrl: string, path: string, body: unknown, walletPrivateKey: string | undefined): Promise<PayAndFetchResult>;

package/dist/x402-pay.js

@@ -0,0 +1,264 @@
+/**
+ * Shared x402 payment helper for the true402 MCP server.
+ *
+ * Encapsulates the full pay-and-retry flow used by every paid stall:
+ *   1. POST the request body (no payment header)
+ *   2. If the server replies 402, parse the payment requirements
+ *   3. Pick the EVM (scheme: "exact") option, sign an EIP-3009
+ *      TransferWithAuthorization with the configured wallet
+ *   4. Retry with the base64-encoded `X-PAYMENT` header
+ *   5. Return the parsed JSON (or a structured error)
+ *
+ * The signer is network-aware: it derives the EIP-712 domain (chainId,
+ * verifyingContract, name, version) from the 402 requirement itself, so it
+ * works on Base mainnet, Base Sepolia, or any future network the server
+ * advertises — instead of being hardcoded to one chain.
+ *
+ * SECURITY: the wallet private key is never logged, echoed, or returned.
+ */
+import { encodePacked, keccak256 } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+// CAIP-2 chain id -> EVM numeric chainId.
+const CHAIN_IDS = {
+    "eip155:8453": 8453, // Base mainnet
+    "eip155:84532": 84532, // Base Sepolia
+    "eip155:1": 1, // Ethereum mainnet
+};
+// Fallback numeric chainId when the network string is unknown (Base mainnet).
+const DEFAULT_CHAIN_ID = 8453;
+/**
+ * Resolve the numeric chainId for an x402 `network` value. Accepts CAIP-2
+ * ("eip155:8453"), a bare numeric id ("8453"), or the friendly names the
+ * server config understands ("base-mainnet" / "base-sepolia" / "ethereum").
+ */
+function resolveChainId(network) {
+    if (CHAIN_IDS[network] !== undefined)
+        return CHAIN_IDS[network];
+    const colon = network.indexOf(":");
+    if (colon !== -1) {
+        const n = Number(network.slice(colon + 1));
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    switch (network) {
+        case "base-mainnet":
+        case "base":
+            return 8453;
+        case "base-sepolia":
+            return 84532;
+        case "ethereum":
+        case "mainnet":
+            return 1;
+        default: {
+            const n = Number(network);
+            return Number.isFinite(n) && n > 0 ? n : DEFAULT_CHAIN_ID;
+        }
+    }
+}
+/**
+ * Sign an EIP-3009 TransferWithAuthorization and return the x402 payment
+ * payload. The EIP-712 domain is derived from the requirement (network +
+ * asset + advertised domain name/version) so signatures are valid on the
+ * exact chain the 402 demands.
+ */
+export async function signEIP3009Payment(privateKey, requirement) {
+    const account = privateKeyToAccount(privateKey);
+    const now = Math.floor(Date.now() / 1000);
+    const validAfter = BigInt(now - 60); // valid 60s in the past (clock skew tolerance)
+    const validBefore = BigInt(now + requirement.maxTimeoutSeconds);
+    // Generate a random nonce (bytes32)
+    const randomBytes = new Uint8Array(32);
+    crypto.getRandomValues(randomBytes);
+    const nonce = keccak256(encodePacked(["bytes32", "uint256"], [
+        ("0x" +
+            Array.from(randomBytes)
+                .map((b) => b.toString(16).padStart(2, "0"))
+                .join("")),
+        BigInt(now),
+    ]));
+    // v2 advertises `amount`; v1 used `maxAmountRequired` — accept either, like a1-pay/pay.mjs.
+    const rawAmount = requirement.amount ?? requirement.maxAmountRequired;
+    if (rawAmount === undefined) {
+        throw new Error("Payment requirement is missing an amount");
+    }
+    const value = BigInt(rawAmount);
+    const message = {
+        from: account.address,
+        to: requirement.payTo,
+        value,
+        validAfter,
+        validBefore,
+        nonce: nonce,
+    };
+    // Build the EIP-712 domain from the requirement so we sign for the right
+    // chain + USDC contract. Prefer the domain name/version the server
+    // advertises in `extra`; fall back to network-derived defaults.
+    const chainId = resolveChainId(requirement.network);
+    const domainName = requirement.extra?.name ?? (chainId === 84532 ? "USDC" : "USD Coin");
+    const domainVersion = requirement.extra?.version ?? "2";
+    const domain = {
+        name: domainName,
+        version: domainVersion,
+        chainId,
+        verifyingContract: requirement.asset,
+    };
+    // Sign EIP-712 typed data
+    const signature = await account.signTypedData({
+        domain,
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: "TransferWithAuthorization",
+        message,
+    });
+    // Build x402 payment payload
+    return {
+        x402Version: 2,
+        scheme: "exact",
+        network: requirement.network,
+        payload: {
+            signature,
+            authorization: {
+                from: account.address,
+                to: requirement.payTo,
+                value: value.toString(),
+                validAfter: validAfter.toString(),
+                validBefore: validBefore.toString(),
+                nonce,
+            },
+        },
+    };
+}
+/**
+ * Perform the full x402 flow against `${baseUrl}${path}` with the given JSON
+ * `body`. Returns the parsed JSON on success, or a structured error.
+ *
+ * If no wallet key is configured and the endpoint demands payment, this does
+ * NOT crash — it returns `{ ok: false, paymentRequired: true, message }` with
+ * the raw requirements embedded so an agent knows it must fund a wallet.
+ */
+export async function payAndFetch(baseUrl, path, body, walletPrivateKey) {
+    const url = `${baseUrl}${path}`;
+    // Step 1: first request, no payment header.
+    let firstResponse;
+    try {
+        firstResponse = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            message: `Network error reaching ${url}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Step 2: non-402 short-circuit (success OR a non-payment error).
+    if (firstResponse.status !== 402) {
+        const data = await safeJson(firstResponse);
+        if (!firstResponse.ok) {
+            return {
+                ok: false,
+                message: `Request failed: ${firstResponse.status} ${stringify(data)}`,
+            };
+        }
+        return { ok: true, data };
+    }
+    // Step 3: 402 Payment Required. Parse the requirements first so we can
+    // surface them no matter what.
+    const paymentData = (await safeJson(firstResponse));
+    if (!walletPrivateKey) {
+        return {
+            ok: false,
+            paymentRequired: true,
+            message: [
+                "Payment required (HTTP 402). No wallet private key configured.",
+                "This is a PAID x402 service (USDC on Base). Set WALLET_PRIVATE_KEY",
+                "on the MCP server to a funded wallet to enable automatic payment.",
+                "",
+                "Payment requirements:",
+                stringify(paymentData),
+            ].join("\n"),
+        };
+    }
+    // Find the EVM payment option (scheme: "exact").
+    const evmRequirement = paymentData.accepts?.find((r) => r.scheme === "exact");
+    if (!evmRequirement) {
+        // Lightning (BOLT11) payment is a TODO — not implemented here.
+        return {
+            ok: false,
+            paymentRequired: true,
+            message: [
+                "Payment required (HTTP 402) but no EVM (scheme: exact) option found.",
+                "Only EVM (USDC on Base) payments are currently supported; Lightning",
+                "(BOLT11) is not yet implemented in this client.",
+                "",
+                "Available payment options:",
+                stringify(paymentData.accepts),
+            ].join("\n"),
+        };
+    }
+    // Step 4: sign the EIP-3009 authorization and base64-encode the payload.
+    let xPaymentHeader;
+    try {
+        const signedPayload = await signEIP3009Payment(walletPrivateKey, evmRequirement);
+        xPaymentHeader = Buffer.from(JSON.stringify(signedPayload)).toString("base64");
+    }
+    catch (err) {
+        // Never include the key material in the error.
+        return {
+            ok: false,
+            message: `Failed to sign payment: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Step 5: retry with the X-PAYMENT header.
+    let retryResponse;
+    try {
+        retryResponse = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-PAYMENT": xPaymentHeader,
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            message: `Network error on paid retry to ${url}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const retryData = await safeJson(retryResponse);
+    if (!retryResponse.ok) {
+        return {
+            ok: false,
+            message: `Payment sent but request failed: ${retryResponse.status} ${stringify(retryData)}`,
+        };
+    }
+    return { ok: true, data: retryData };
+}
+/** Parse a response body as JSON, falling back to text wrapped in an object. */
+async function safeJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { _raw: text };
+    }
+}
+function stringify(value) {
+    return JSON.stringify(value, null, 2);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@true402.dev/mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server for the true402 machine-native marketplace — pay-per-call AI + web tools over x402 (USDC on Base): LLM inference, SEO/GEO audit, web extract, link preview, robots/AI-crawler check, security headers.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "true402-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "ai-agent",
+    "agent",
+    "micropayments",
+    "usdc",
+    "base",
+    "llm",
+    "seo",
+    "geo",
+    "web-scraping",
+    "tools"
+  ],
+  "homepage": "https://true402.dev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "viem": "^2.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}