x402scan-mcp 0.0.1

package/README.md

@@ -0,0 +1,105 @@
+# x402scan-mcp
+
+MCP server for calling [x402](https://x402.org)-protected APIs with automatic payment handling.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add x402scan -- npx -y x402scan-mcp@latest
+```
+
+### Codex
+
+```bash
+codex mcp add x402scan -- npx -y x402scan-mcp@latest
+```
+
+### Cursor
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=x402scan&config=eyJjb21tYW5kIjoiL2Jpbi9iYXNoIiwiYXJncyI6WyItYyIsInNvdXJjZSAkSE9NRS8ubnZtL252bS5zaCAyPi9kZXYvbnVsbDsgZXhlYyBucHggLXkgeDQwMnNjYW4tbWNwQGxhdGVzdCJdfQ%3D%3D)
+
+### Claude Desktop
+
+[![Add to Claude](https://img.shields.io/badge/Add_to_Claude-x402scan-blue?logo=anthropic)](https://github.com/merit-systems/x402scan-mcp/raw/main/x402scan.mcpb)
+
+<details>
+<summary>Manual installation</summary>
+
+**Codex** - Add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.x402scan]
+command = "npx"
+args = ["-y", "x402scan-mcp@latest"]
+```
+
+**Cursor** - Add to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "x402scan": {
+      "command": "/bin/bash",
+      "args": ["-c", "source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y x402scan-mcp@latest"]
+    }
+  }
+}
+```
+
+**Claude Desktop** - Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "x402scan": {
+      "command": "/bin/bash",
+      "args": ["-c", "source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y x402scan-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+## Usage
+
+On first run, a wallet is generated at `~/.x402scan-mcp/wallet.json`. Deposit USDC on Base to the wallet address before making paid API calls.
+
+**Workflow:**
+1. `check_balance` - Check wallet and get deposit address
+2. `query_endpoint` - Probe endpoint for pricing/schema (optional)
+3. `execute_call` - Make the paid request
+
+## Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `check_balance` | Get wallet address and USDC balance |
+| `query_endpoint` | Probe x402 endpoint for pricing/schema without payment |
+| `validate_payment` | Pre-flight check if payment would succeed |
+| `execute_call` | Make paid request to x402 endpoint |
+
+## Environment
+
+| Variable | Description |
+|----------|-------------|
+| `X402_PRIVATE_KEY` | Override wallet (optional) |
+| `X402_DEBUG` | Set to `true` for verbose logging |
+
+## Supported Networks
+
+Base, Base Sepolia, Ethereum, Optimism, Arbitrum, Polygon (via CAIP-2)
+
+## Develop
+
+```bash
+bun install
+
+# Add local server to Claude Code
+claude mcp add x402scan-dev -- bun run /path/to/x402scan-mcp/src/index.ts
+
+# Build
+bun run build
+
+# Build .mcpb for Claude Desktop
+bun run build:mcpb
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,968 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/wallet/manager.ts
+import { randomBytes } from "crypto";
+import { privateKeyToAccount } from "viem/accounts";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+
+// src/utils/logger.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var LOG_DIR = join(homedir(), ".x402scan-mcp");
+var LOG_FILE = join(LOG_DIR, "mcp.log");
+try {
+  mkdirSync(LOG_DIR, { recursive: true });
+} catch {
+}
+function formatTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function formatArgs(args) {
+  return args.map((arg) => {
+    if (typeof arg === "object" && arg !== null) {
+      try {
+        return JSON.stringify(arg, null, 2);
+      } catch {
+        return String(arg);
+      }
+    }
+    return String(arg);
+  }).join(" ");
+}
+function writeLog(level, message, ...args) {
+  const formatted = args.length > 0 ? `${message} ${formatArgs(args)}` : message;
+  const line = `[${formatTimestamp()}] [${level}] ${formatted}
+`;
+  try {
+    appendFileSync(LOG_FILE, line);
+  } catch {
+  }
+  console.error(`[x402scan] ${formatted}`);
+}
+var log = {
+  info: (message, ...args) => writeLog("INFO", message, ...args),
+  error: (message, ...args) => writeLog("ERROR", message, ...args),
+  debug: (message, ...args) => writeLog("DEBUG", message, ...args),
+  /** Clear the log file (adds separator) */
+  clear: () => {
+    try {
+      appendFileSync(LOG_FILE, `
+--- Log cleared at ${formatTimestamp()} ---
+`);
+    } catch {
+    }
+  },
+  /** Get log file path */
+  path: LOG_FILE
+};
+var DEBUG = process.env.X402_DEBUG === "true";
+function logInfo(message) {
+  log.info(message);
+}
+function logPaymentRequired(pr) {
+  if (DEBUG) {
+    log.debug("Payment required:", pr);
+  }
+}
+function logSignature(headers) {
+  if (DEBUG) {
+    log.debug("Payment headers:", Object.keys(headers).join(", "));
+  }
+}
+function logSettlement(response) {
+  if (DEBUG) {
+    log.debug("Settlement response:", response);
+  }
+}
+
+// src/wallet/manager.ts
+var WALLET_DIR = path.join(os.homedir(), ".x402scan-mcp");
+var WALLET_FILE = path.join(WALLET_DIR, "wallet.json");
+function generatePrivateKey() {
+  return `0x${randomBytes(32).toString("hex")}`;
+}
+async function loadWalletConfig() {
+  try {
+    const data = await fs.readFile(WALLET_FILE, "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+async function saveWalletConfig(config) {
+  await fs.mkdir(WALLET_DIR, { recursive: true });
+  await fs.writeFile(WALLET_FILE, JSON.stringify(config, null, 2));
+  try {
+    await fs.chmod(WALLET_FILE, 384);
+  } catch {
+  }
+}
+async function getOrCreateWallet() {
+  const envPrivateKey = process.env.X402_PRIVATE_KEY;
+  let privateKey;
+  let address;
+  let config;
+  let isNew = false;
+  if (envPrivateKey) {
+    privateKey = envPrivateKey;
+    const account2 = privateKeyToAccount(privateKey);
+    address = account2.address;
+    config = {
+      privateKey,
+      address,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    logInfo(`Using wallet from environment: ${address}`);
+  } else {
+    const existingConfig = await loadWalletConfig();
+    if (!existingConfig) {
+      privateKey = generatePrivateKey();
+      const account2 = privateKeyToAccount(privateKey);
+      address = account2.address;
+      config = {
+        privateKey,
+        address,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await saveWalletConfig(config);
+      isNew = true;
+      logInfo(`Generated new wallet: ${address}`);
+      logInfo(`Wallet saved to: ${WALLET_FILE}`);
+    } else {
+      config = existingConfig;
+      privateKey = config.privateKey;
+      address = config.address;
+      logInfo(`Loaded wallet: ${address}`);
+    }
+  }
+  const account = privateKeyToAccount(privateKey);
+  return { account, address, config, isNew };
+}
+function getWalletFilePath() {
+  return WALLET_FILE;
+}
+async function walletExists() {
+  if (process.env.X402_PRIVATE_KEY) {
+    return true;
+  }
+  const config = await loadWalletConfig();
+  return config !== null;
+}
+
+// src/balance/usdc.ts
+import { createPublicClient, http } from "viem";
+
+// src/utils/networks.ts
+import { base, baseSepolia, mainnet, sepolia, optimism, arbitrum, polygon } from "viem/chains";
+var CHAIN_CONFIGS = {
+  // Base Mainnet
+  "eip155:8453": {
+    chain: base,
+    caip2: "eip155:8453",
+    v1Name: "base",
+    usdcAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  },
+  // Base Sepolia
+  "eip155:84532": {
+    chain: baseSepolia,
+    caip2: "eip155:84532",
+    v1Name: "base-sepolia",
+    usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+  },
+  // Ethereum Mainnet
+  "eip155:1": {
+    chain: mainnet,
+    caip2: "eip155:1",
+    v1Name: "ethereum",
+    usdcAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+  },
+  // Ethereum Sepolia
+  "eip155:11155111": {
+    chain: sepolia,
+    caip2: "eip155:11155111",
+    v1Name: "ethereum-sepolia",
+    usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
+  },
+  // Optimism
+  "eip155:10": {
+    chain: optimism,
+    caip2: "eip155:10",
+    v1Name: "optimism",
+    usdcAddress: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
+  },
+  // Arbitrum
+  "eip155:42161": {
+    chain: arbitrum,
+    caip2: "eip155:42161",
+    v1Name: "arbitrum",
+    usdcAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
+  },
+  // Polygon
+  "eip155:137": {
+    chain: polygon,
+    caip2: "eip155:137",
+    v1Name: "polygon",
+    usdcAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
+  }
+};
+var V1_TO_CAIP2 = {
+  "base": "eip155:8453",
+  "base-sepolia": "eip155:84532",
+  "ethereum": "eip155:1",
+  "ethereum-sepolia": "eip155:11155111",
+  "optimism": "eip155:10",
+  "arbitrum": "eip155:42161",
+  "polygon": "eip155:137"
+};
+var DEFAULT_NETWORK = "eip155:8453";
+function toCaip2(network) {
+  if (network.startsWith("eip155:")) {
+    return network;
+  }
+  const caip2 = V1_TO_CAIP2[network.toLowerCase()];
+  if (caip2) {
+    return caip2;
+  }
+  return network;
+}
+function getChainConfig(network) {
+  const caip2 = toCaip2(network);
+  return CHAIN_CONFIGS[caip2];
+}
+function getUSDCAddress(network) {
+  const config = getChainConfig(network);
+  return config?.usdcAddress;
+}
+function getChain(network) {
+  const config = getChainConfig(network);
+  return config?.chain;
+}
+function getChainName(network) {
+  const config = getChainConfig(network);
+  if (config) {
+    return config.chain.name;
+  }
+  return network;
+}
+function getExplorerUrl(network) {
+  const config = getChainConfig(network);
+  return config?.chain.blockExplorers?.default.url;
+}
+function isTestnet(network) {
+  const config = getChainConfig(network);
+  if (!config) return false;
+  return config.chain.testnet === true;
+}
+
+// src/balance/usdc.ts
+var ERC20_ABI = [
+  {
+    inputs: [{ name: "account", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function"
+  }
+];
+async function getUSDCBalance(address, network = DEFAULT_NETWORK) {
+  const caip2Network = toCaip2(network);
+  const chain = getChain(caip2Network);
+  const usdcAddress = getUSDCAddress(caip2Network);
+  if (!chain) {
+    throw new Error(`Unsupported network: ${network} (${caip2Network})`);
+  }
+  if (!usdcAddress) {
+    throw new Error(`No USDC address configured for network: ${network}`);
+  }
+  log.debug(`Reading USDC balance for ${address} on ${chain.name}`);
+  const client = createPublicClient({
+    chain,
+    transport: http()
+  });
+  const balance = await client.readContract({
+    address: usdcAddress,
+    abi: ERC20_ABI,
+    functionName: "balanceOf",
+    args: [address]
+  });
+  const decimals = 6;
+  const formatted = Number(balance) / Math.pow(10, decimals);
+  const formattedString = `$${formatted.toFixed(2)}`;
+  log.debug(`Balance: ${formattedString}`);
+  return {
+    balance,
+    formatted,
+    formattedString,
+    decimals,
+    network: caip2Network,
+    usdcAddress
+  };
+}
+async function hasSufficientBalance(address, requiredAmount, network = DEFAULT_NETWORK) {
+  const required = typeof requiredAmount === "string" ? BigInt(requiredAmount) : requiredAmount;
+  const { balance } = await getUSDCBalance(address, network);
+  const sufficient = balance >= required;
+  const shortfall = sufficient ? 0n : required - balance;
+  return {
+    sufficient,
+    currentBalance: balance,
+    requiredAmount: required,
+    shortfall
+  };
+}
+
+// src/utils/helpers.ts
+function mcpSuccess(data) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+function mcpError(error, context) {
+  let message;
+  let details;
+  if (error instanceof Error) {
+    message = error.message;
+    if ("cause" in error && error.cause) {
+      details = { cause: String(error.cause) };
+    }
+  } else if (typeof error === "string") {
+    message = error;
+  } else {
+    message = String(error);
+  }
+  const errorResponse = {
+    error: message
+  };
+  if (details) {
+    errorResponse.details = details;
+  }
+  if (context) {
+    errorResponse.context = context;
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(errorResponse, null, 2)
+      }
+    ],
+    isError: true
+  };
+}
+function formatUSDC(amount) {
+  const usd = Number(amount) / 1e6;
+  return `$${usd.toFixed(2)}`;
+}
+
+// src/tools/check_balance.ts
+function registerCheckBalanceTool(server) {
+  server.tool(
+    "check_balance",
+    "Check wallet address and USDC balance. Creates wallet if needed. Returns address, balance, and funding instructions.",
+    {},
+    async () => {
+      try {
+        const { address, isNew } = await getOrCreateWallet();
+        const walletFile = getWalletFilePath();
+        let balance;
+        try {
+          balance = await getUSDCBalance(address, DEFAULT_NETWORK);
+        } catch (err) {
+          return mcpSuccess({
+            address,
+            network: DEFAULT_NETWORK,
+            networkName: getChainName(DEFAULT_NETWORK),
+            balanceUSDC: null,
+            balanceError: err instanceof Error ? err.message : "Failed to fetch balance",
+            walletFile,
+            isNewWallet: isNew,
+            fundingInstructions: getFundingInstructions(address, DEFAULT_NETWORK)
+          });
+        }
+        const response = {
+          address,
+          network: balance.network,
+          networkName: getChainName(balance.network),
+          balanceUSDC: balance.formatted,
+          balanceFormatted: balance.formattedString,
+          walletFile,
+          isNewWallet: isNew
+        };
+        if (balance.formatted < 1) {
+          response.fundingInstructions = getFundingInstructions(address, balance.network);
+          response.suggestion = balance.formatted === 0 ? "Your wallet has no USDC. Send USDC to the address above to start making paid API calls." : "Your balance is low. Consider topping up to continue making paid API calls.";
+        }
+        return mcpSuccess(response);
+      } catch (err) {
+        return mcpError(err, { tool: "check_balance" });
+      }
+    }
+  );
+}
+function getFundingInstructions(address, network) {
+  const explorerUrl = getExplorerUrl(network);
+  const usdcAddress = getUSDCAddress(network);
+  const chainName = getChainName(network);
+  const testnet = isTestnet(network);
+  return {
+    chainName,
+    isTestnet: testnet,
+    depositAddress: address,
+    usdcContract: usdcAddress,
+    explorerUrl: explorerUrl ? `${explorerUrl}/address/${address}` : void 0,
+    instructions: testnet ? `This is a testnet. Get test USDC from a faucet and send to ${address}` : `Send USDC on ${chainName} to ${address}`
+  };
+}
+
+// src/tools/query_endpoint.ts
+import { z } from "zod";
+import { x402HTTPClient as x402HTTPClient2 } from "@x402/core/http";
+import { x402Client as x402Client2 } from "@x402/core/client";
+import { registerExactEvmScheme as registerExactEvmScheme2 } from "@x402/evm/exact/client";
+import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/x402/client.ts
+import { x402Client } from "@x402/core/client";
+import { x402HTTPClient } from "@x402/core/http";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+function createX402Client(config) {
+  const { account, preferredNetwork } = config;
+  const coreClient = new x402Client(
+    preferredNetwork ? (_version, accepts) => {
+      const preferred = accepts.find((a) => toCaip2(a.network) === toCaip2(preferredNetwork));
+      return preferred || accepts[0];
+    } : void 0
+  );
+  registerExactEvmScheme(coreClient, { signer: account });
+  const httpClient = new x402HTTPClient(coreClient);
+  return { coreClient, httpClient };
+}
+async function makeX402Request(httpClient, url, options = {}) {
+  const { method = "GET", body, headers = {} } = options;
+  log.debug(`Making initial request: ${method} ${url}`);
+  let firstResponse;
+  try {
+    firstResponse = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+  } catch (err) {
+    return {
+      success: false,
+      statusCode: 0,
+      error: {
+        phase: "initial_request",
+        message: `Network error: ${err instanceof Error ? err.message : String(err)}`
+      }
+    };
+  }
+  if (firstResponse.status !== 402) {
+    if (firstResponse.ok) {
+      try {
+        const data2 = await firstResponse.json();
+        return {
+          success: true,
+          statusCode: firstResponse.status,
+          data: data2
+        };
+      } catch {
+        return {
+          success: true,
+          statusCode: firstResponse.status,
+          data: await firstResponse.text()
+        };
+      }
+    } else {
+      const errorText = await firstResponse.text();
+      return {
+        success: false,
+        statusCode: firstResponse.status,
+        error: {
+          phase: "initial_request",
+          message: `HTTP ${firstResponse.status}: ${errorText}`
+        }
+      };
+    }
+  }
+  log.debug("Got 402 Payment Required, parsing requirements...");
+  let paymentRequired;
+  let responseBody;
+  try {
+    try {
+      responseBody = await firstResponse.clone().json();
+    } catch {
+      responseBody = void 0;
+    }
+    paymentRequired = httpClient.getPaymentRequiredResponse(
+      (name) => firstResponse.headers.get(name),
+      responseBody
+    );
+    logPaymentRequired(paymentRequired);
+  } catch (err) {
+    return {
+      success: false,
+      statusCode: 402,
+      error: {
+        phase: "parse_requirements",
+        message: `Failed to parse payment requirements: ${err instanceof Error ? err.message : String(err)}`,
+        details: {
+          headers: Object.fromEntries(firstResponse.headers.entries()),
+          body: responseBody
+        }
+      }
+    };
+  }
+  log.debug("Creating payment payload...");
+  let paymentPayload;
+  try {
+    paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
+    log.debug(`Payment created for network: ${paymentPayload.accepted?.network}`);
+  } catch (err) {
+    return {
+      success: false,
+      statusCode: 402,
+      paymentRequired,
+      error: {
+        phase: "create_signature",
+        message: `Failed to create payment signature: ${err instanceof Error ? err.message : String(err)}`
+      }
+    };
+  }
+  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+  logSignature(paymentHeaders);
+  log.debug("Retrying request with payment...");
+  let paidResponse;
+  try {
+    paidResponse = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...paymentHeaders,
+        ...headers
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+  } catch (err) {
+    return {
+      success: false,
+      statusCode: 0,
+      paymentRequired,
+      error: {
+        phase: "paid_request",
+        message: `Network error on paid request: ${err instanceof Error ? err.message : String(err)}`
+      }
+    };
+  }
+  if (!paidResponse.ok) {
+    const errorText = await paidResponse.text();
+    return {
+      success: false,
+      statusCode: paidResponse.status,
+      paymentRequired,
+      error: {
+        phase: "paid_request",
+        message: `HTTP ${paidResponse.status} after payment: ${errorText}`,
+        details: {
+          headers: Object.fromEntries(paidResponse.headers.entries())
+        }
+      }
+    };
+  }
+  let settlement;
+  try {
+    const settleResponse = httpClient.getPaymentSettleResponse(
+      (name) => paidResponse.headers.get(name)
+    );
+    logSettlement(settleResponse);
+    settlement = {
+      transactionHash: settleResponse.transaction,
+      network: settleResponse.network,
+      payer: settleResponse.payer || paymentPayload.accepted?.payTo || ""
+    };
+  } catch (err) {
+    log.debug(`Could not parse settlement response: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  let data;
+  try {
+    data = await paidResponse.json();
+  } catch {
+    data = await paidResponse.text();
+  }
+  return {
+    success: true,
+    statusCode: paidResponse.status,
+    data,
+    settlement,
+    paymentRequired
+  };
+}
+async function queryEndpoint(url, httpClient, options = {}) {
+  const { method = "GET", body, headers = {} } = options;
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+  } catch (err) {
+    return {
+      success: false,
+      statusCode: 0,
+      error: `Network error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const rawHeaders = Object.fromEntries(response.headers.entries());
+  if (response.status !== 402) {
+    return {
+      success: true,
+      statusCode: response.status,
+      rawHeaders
+    };
+  }
+  let rawBody;
+  try {
+    rawBody = await response.json();
+  } catch {
+    rawBody = void 0;
+  }
+  try {
+    const paymentRequired = httpClient.getPaymentRequiredResponse(
+      (name) => response.headers.get(name),
+      rawBody
+    );
+    return {
+      success: true,
+      statusCode: 402,
+      x402Version: paymentRequired.x402Version,
+      paymentRequired,
+      rawHeaders,
+      rawBody
+    };
+  } catch (err) {
+    return {
+      success: false,
+      statusCode: 402,
+      error: `Failed to parse payment requirements: ${err instanceof Error ? err.message : String(err)}`,
+      parseErrors: [err instanceof Error ? err.message : String(err)],
+      rawHeaders,
+      rawBody
+    };
+  }
+}
+
+// src/tools/query_endpoint.ts
+function registerQueryEndpointTool(server) {
+  server.tool(
+    "query_endpoint",
+    "Probe an x402-protected endpoint to get pricing and schema without making a payment. Returns payment requirements, accepted networks, and Bazaar schema if available.",
+    {
+      url: z.string().url().describe("The x402-protected endpoint URL to probe"),
+      method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("GET").describe("HTTP method to use"),
+      body: z.unknown().optional().describe("Request body for POST/PUT/PATCH methods")
+    },
+    async ({ url, method, body }) => {
+      try {
+        const tempKey = `0x${randomBytes2(32).toString("hex")}`;
+        const tempAccount = privateKeyToAccount2(tempKey);
+        const coreClient = new x402Client2();
+        registerExactEvmScheme2(coreClient, { signer: tempAccount });
+        const httpClient = new x402HTTPClient2(coreClient);
+        const result = await queryEndpoint(url, httpClient, {
+          method,
+          body
+        });
+        if (!result.success) {
+          return mcpError(result.error || "Failed to query endpoint", {
+            statusCode: result.statusCode,
+            parseErrors: result.parseErrors,
+            rawHeaders: result.rawHeaders,
+            rawBody: result.rawBody
+          });
+        }
+        if (result.statusCode !== 402) {
+          return mcpSuccess({
+            isX402Endpoint: false,
+            statusCode: result.statusCode,
+            message: "This endpoint does not require payment (no 402 response)",
+            rawHeaders: result.rawHeaders
+          });
+        }
+        const pr = result.paymentRequired;
+        const requirements = pr.accepts.map((req) => ({
+          scheme: req.scheme,
+          network: req.network,
+          networkName: getChainName(req.network),
+          price: formatUSDC(BigInt(req.amount)),
+          priceRaw: req.amount,
+          asset: req.asset,
+          payTo: req.payTo,
+          maxTimeoutSeconds: req.maxTimeoutSeconds,
+          extra: req.extra
+        }));
+        const response = {
+          isX402Endpoint: true,
+          x402Version: pr.x402Version,
+          requirements
+        };
+        if (pr.resource) {
+          response.resource = {
+            url: pr.resource.url,
+            description: pr.resource.description,
+            mimeType: pr.resource.mimeType
+          };
+        }
+        if (pr.extensions?.bazaar) {
+          const bazaar = pr.extensions.bazaar;
+          response.bazaar = {
+            info: bazaar.info,
+            schema: bazaar.schema,
+            examples: bazaar.examples,
+            hasBazaarExtension: true
+          };
+        }
+        if (pr.error) {
+          response.serverError = pr.error;
+        }
+        return mcpSuccess(response);
+      } catch (err) {
+        return mcpError(err, { tool: "query_endpoint", url });
+      }
+    }
+  );
+}
+
+// src/tools/validate_payment.ts
+import { z as z2 } from "zod";
+var PaymentRequirementsSchema = z2.object({
+  scheme: z2.string(),
+  network: z2.string(),
+  amount: z2.string(),
+  asset: z2.string(),
+  payTo: z2.string(),
+  maxTimeoutSeconds: z2.number(),
+  extra: z2.record(z2.unknown()).optional()
+});
+function registerValidatePaymentTool(server) {
+  server.tool(
+    "validate_payment",
+    "Pre-flight check if a payment would succeed. Validates wallet, network support, and balance. Use after query_endpoint to verify before execute_call.",
+    {
+      requirements: PaymentRequirementsSchema.describe(
+        "Payment requirements from query_endpoint result"
+      )
+    },
+    async ({ requirements }) => {
+      try {
+        const errors = [];
+        const warnings = [];
+        const checks = {};
+        const hasWallet = await walletExists();
+        checks.walletExists = hasWallet;
+        if (!hasWallet) {
+          errors.push("No wallet found. Run check_balance first to create a wallet.");
+        }
+        const caip2Network = toCaip2(requirements.network);
+        const chainConfig = getChainConfig(caip2Network);
+        checks.networkSupported = !!chainConfig;
+        if (!chainConfig) {
+          errors.push(
+            `Network not supported: ${requirements.network}. Supported networks: Base (eip155:8453), Base Sepolia (eip155:84532), Ethereum, Optimism, Arbitrum, Polygon.`
+          );
+        }
+        checks.schemeSupported = requirements.scheme === "exact";
+        if (requirements.scheme !== "exact") {
+          errors.push(
+            `Payment scheme not supported: ${requirements.scheme}. Only 'exact' scheme is supported for EVM chains.`
+          );
+        }
+        if (!hasWallet || !chainConfig) {
+          return mcpSuccess({
+            valid: false,
+            readyToExecute: false,
+            checks,
+            errors,
+            warnings
+          });
+        }
+        const { address } = await getOrCreateWallet();
+        let balanceResult;
+        try {
+          balanceResult = await hasSufficientBalance(
+            address,
+            requirements.amount,
+            caip2Network
+          );
+          checks.sufficientBalance = balanceResult.sufficient;
+          if (!balanceResult.sufficient) {
+            errors.push(
+              `Insufficient balance. Required: ${formatUSDC(balanceResult.requiredAmount)}, Available: ${formatUSDC(balanceResult.currentBalance)}, Shortfall: ${formatUSDC(balanceResult.shortfall)}`
+            );
+          }
+        } catch (err) {
+          checks.sufficientBalance = false;
+          errors.push(`Failed to check balance: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const expectedUsdc = chainConfig?.usdcAddress?.toLowerCase();
+        const providedAsset = requirements.asset.toLowerCase();
+        checks.assetIsUSDC = expectedUsdc === providedAsset;
+        if (!checks.assetIsUSDC) {
+          warnings.push(
+            `Asset may not be USDC. Expected: ${expectedUsdc}, Got: ${providedAsset}. Proceeding anyway, but verify the asset is correct.`
+          );
+        }
+        checks.signatureCapable = true;
+        const valid = errors.length === 0;
+        const response = {
+          valid,
+          readyToExecute: valid,
+          checks
+        };
+        if (balanceResult) {
+          response.balance = {
+            current: formatUSDC(balanceResult.currentBalance),
+            required: formatUSDC(balanceResult.requiredAmount),
+            sufficient: balanceResult.sufficient
+          };
+        }
+        response.network = {
+          requested: requirements.network,
+          resolved: caip2Network,
+          name: getChainName(caip2Network),
+          supported: !!chainConfig
+        };
+        if (errors.length > 0) {
+          response.errors = errors;
+        }
+        if (warnings.length > 0) {
+          response.warnings = warnings;
+        }
+        return mcpSuccess(response);
+      } catch (err) {
+        return mcpError(err, { tool: "validate_payment" });
+      }
+    }
+  );
+}
+
+// src/tools/execute_call.ts
+import { z as z3 } from "zod";
+function registerExecuteCallTool(server) {
+  server.tool(
+    "execute_call",
+    "Make a paid request to an x402-protected endpoint. Handles 402 payment flow automatically: detects payment requirements, signs payment, and executes request.",
+    {
+      url: z3.string().url().describe("The x402-protected endpoint URL"),
+      method: z3.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("GET").describe("HTTP method"),
+      body: z3.unknown().optional().describe("Request body for POST/PUT/PATCH methods"),
+      headers: z3.record(z3.string()).optional().describe("Additional headers to include in the request")
+    },
+    async ({ url, method, body, headers }) => {
+      try {
+        const { account, address } = await getOrCreateWallet();
+        const { httpClient } = createX402Client({ account });
+        const result = await makeX402Request(httpClient, url, {
+          method,
+          body,
+          headers
+        });
+        if (!result.success) {
+          const errorResponse = {
+            success: false,
+            statusCode: result.statusCode,
+            error: result.error
+          };
+          if (result.paymentRequired) {
+            errorResponse.paymentRequired = {
+              x402Version: result.paymentRequired.x402Version,
+              requirements: result.paymentRequired.accepts.map((req) => ({
+                network: req.network,
+                networkName: getChainName(req.network),
+                price: formatUSDC(BigInt(req.amount)),
+                priceRaw: req.amount
+              }))
+            };
+          }
+          return mcpError(result.error?.message || "Request failed", errorResponse);
+        }
+        const response = {
+          success: true,
+          statusCode: result.statusCode,
+          data: result.data
+        };
+        if (result.settlement) {
+          response.settlement = {
+            transactionHash: result.settlement.transactionHash,
+            network: result.settlement.network,
+            networkName: getChainName(result.settlement.network),
+            payer: address
+          };
+          if (result.paymentRequired?.accepts?.[0]) {
+            response.settlement = {
+              ...response.settlement,
+              amountPaid: formatUSDC(BigInt(result.paymentRequired.accepts[0].amount))
+            };
+          }
+        }
+        if (result.paymentRequired) {
+          response.x402Version = result.paymentRequired.x402Version;
+        }
+        return mcpSuccess(response);
+      } catch (err) {
+        return mcpError(err, { tool: "execute_call", url });
+      }
+    }
+  );
+}
+
+// src/index.ts
+async function main() {
+  log.clear();
+  log.info("Starting x402scan-mcp server...");
+  const server = new McpServer({
+    name: "x402scan",
+    version: "0.0.1"
+  });
+  registerCheckBalanceTool(server);
+  registerQueryEndpointTool(server);
+  registerValidatePaymentTool(server);
+  registerExecuteCallTool(server);
+  log.info("Registered 4 tools: check_balance, query_endpoint, validate_payment, execute_call");
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log.info(`Connected to transport, ready for requests. Log file: ${log.path}`);
+  process.on("SIGINT", async () => {
+    log.info("Shutting down...");
+    await server.close();
+    process.exit(0);
+  });
+  process.on("SIGTERM", async () => {
+    log.info("Shutting down...");
+    await server.close();
+    process.exit(0);
+  });
+}
+main().catch((error) => {
+  log.error("Fatal error", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "x402scan-mcp",
+  "version": "0.0.1",
+  "description": "Generic MCP server for calling x402-protected APIs with automatic payment handling",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "x402scan-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:mcpb": "tsx scripts/build-mcpb.ts",
+    "dev": "tsx src/index.ts",
+    "dev:bun": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "publish-package": "tsx scripts/publish.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@x402/core": "^2.0.0",
+    "@x402/evm": "^2.0.0",
+    "viem": "^2.31.3",
+    "zod": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "payments",
+    "ai",
+    "claude",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/merit-systems/x402scan-mcp"
+  }
+}