@blockrun/mcp 0.13.0 → 0.14.0

package/README.md

@@ -66,6 +66,14 @@ Prompts and a worked example for these are in [`skills/image-prompting/SKILL.md`
 
 ---
 
+## Prerequisites
+
+- **Node.js ≥ 18** (`node -v`)
+- **~$5 USDC** on Base or Solana (the server auto-creates a wallet on first run; see [Fund your wallet](#fund-your-wallet))
+- **An MCP client**: Claude Code, Claude Desktop, Cursor, Windsurf, or ChatGPT Desktop
+
+---
+
 ## Install
 
 **Claude Code (recommended)**
@@ -93,6 +101,23 @@ ensures `-y` is passed to `npx`, not parsed by `claude mcp add`.
 claude mcp add blockrun -s user --transport http https://mcp.blockrun.ai/mcp
 ```
 
+**Cursor** — add to `~/.cursor/mcp.json` (macOS / Linux) or `%APPDATA%\Cursor\mcp.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "blockrun": {
+      "command": "npx",
+      "args": ["-y", "@blockrun/mcp@latest"]
+    }
+  }
+}
+```
+
+**Windsurf** — same JSON, in:
+- macOS: `~/.codeium/windsurf/mcp_config.json`
+- Linux: `~/.config/.codeium/windsurf/mcp_config.json`
+- Windows: `%APPDATA%\Codeium\windsurf\mcp_config.json`
+
 ---
 
 ## Fund your wallet
@@ -118,6 +143,7 @@ $5 covers ~5,000 market queries, ~500 Exa searches, ~250 image generations, or ~
 | `blockrun_music` | MiniMax music generation | per track |
 | `blockrun_price` | Pyth-backed realtime + OHLC — crypto / FX / commodity (free), 12 stock markets (paid) | free or $0.001/call |
 | `blockrun_markets` | Polymarket (markets, candles, trades, orderbooks, leaderboards, smart-wallet PnL/clusters, UMA oracle), Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance Futures, cross-platform match + search | $0.001–0.005/query |
+| `blockrun_surf` | Surf (asksurf.ai) — 84 endpoints: CEX market data, on-chain SQL (13 chains, 80+ ClickHouse tables), 100M+ labeled wallets, Polymarket + Kalshi side-by-side, social mindshare, news, search, Surf-1.5 chat with citations | $0.001–0.02/call |
 | `blockrun_x` | X/Twitter — profiles, tweets, followers, mentions, search (AttentionVC) | per call |
 | `blockrun_exa` | Neural web search (Exa) — research, competitors, papers, URL content | $0.01/query |
 | `blockrun_search` | Grok Live Search — web + news with citations | ~$0.025 per source |
@@ -127,12 +153,56 @@ $5 covers ~5,000 market queries, ~500 Exa searches, ~250 image generations, or ~
 
 ---
 
+## Tips for effective LLMs
+
+> **For LLMs and agents invoking BlockRun MCP tools:**
+
+- **CRITICAL: When any `blockrun_*` tool returns a payment / balance / 402 error, call `blockrun_wallet` *first* to check status, then `action:"setup"` to get funding instructions.** Don't retry the failing tool blindly — the wallet is empty.
+- **CRITICAL: For `blockrun_markets` and `blockrun_surf`, the 80+ endpoint catalog lives in `skills/markets/SKILL.md` and `skills/surf/SKILL.md`, NOT in the tool description.** Browse the skill before guessing endpoint paths.
+- **CRITICAL: `blockrun_chat routing:"smart"` (ClawRouter) only works on Base wallets.** On Solana, pass `mode:` or `model:` to pick a model directly.
+- **CRITICAL: `blockrun_music` and `blockrun_video` are payment-on-completion async.** Failures or client-side timeouts do NOT charge. Don't retry-loop them — they may take 60–180s.
+- **CRITICAL: Before spawning child agents, allocate per-agent budget:** `blockrun_wallet action:"delegate" agent_id:"X" agent_limit:1.00`. Pass `agent_id:"X"` to every downstream `blockrun_*` call — the child is auto-blocked when the budget hits zero.
+- **Free tier first for drafts**: `blockrun_chat mode:"free"` (NVIDIA), `blockrun_dex`, `blockrun_price` (crypto / FX / commodity), and `blockrun_models` are all $0. Use them to scaffold before paying for premium models.
+
+---
+
+## Key Use Cases
+
+What kinds of questions can Claude (or any LLM agent) answer once BlockRun MCP is installed:
+
+1. **Price reads / market data**
+   > *"What's BTC trading at? Compare with last week's average."* → `blockrun_price` (free) or `blockrun_surf` path:`market/price`
+
+2. **Prediction-market consensus**
+   > *"What's Polymarket's odds for the next Fed rate decision?"* → `blockrun_markets` path:`polymarket/events` + filter
+
+3. **On-chain forensics**
+   > *"This wallet (0xabc...) — what's it labeled as? What does it hold? When did it whale up?"* → `blockrun_surf` paths:`wallet/labels/batch`, `wallet/detail`, `wallet/net-worth`
+
+4. **Cited research with sources**
+   > *"Find the 5 most-cited papers on speculative decoding from the last 90 days. Summarize the dominant approach."* → `blockrun_exa` action:`search` then `contents`
+
+5. **Image generation with on-image text**
+   > *"Generate a poster announcing GPT-5.5 on BlockRun, retro-futuristic, with the headline 'NOW LIVE'."* → `blockrun_image` + the `image-prompting` skill 5-section framework
+
+6. **Voice phone-out**
+   > *"Call +1-415-555-... and confirm the appointment on Friday at 3pm."* → `blockrun_phone` action:`voice_call`, then poll `voice_status`
+
+7. **Multi-agent research with budget cap**
+   > *"Spawn 3 research agents on competing L1 narratives. Cap each at $0.50."* → `blockrun_wallet delegate × 3` → children call `blockrun_chat` + `blockrun_exa` with their `agent_id`
+
+8. **Cross-chain SQL forensics**
+   > *"Top 10 tokens by DEX volume on Base in the last 24h."* → `blockrun_surf` path:`onchain/sql`, body: `{ sql: "SELECT..." }`
+
+---
+
 ## Why not just use the APIs directly?
 
 | | Direct APIs | BlockRun |
 |---|---|---|
 | Exa | Sign up, $20/mo minimum | $0.01/call, no subscription |
 | Polymarket | Undocumented, rate-limited | $0.001/call, clean JSON |
+| Surf (asksurf.ai) | Account + monthly plan | $0.001/call, no Surf account, 84 endpoints |
 | Twitter/X API | $100–$5000/month | $0.03/page, no approval |
 | Multiple sources | 4 accounts, 4 API keys, 4 billing pages | 1 wallet |
 
@@ -140,15 +210,71 @@ One wallet. All sources. No dashboards.
 
 ---
 
+## When NOT to use BlockRun MCP
+
+BlockRun shines when you want **unified billing + many sources + LLM-readable errors**. It is not the right fit for:
+
+- **High-volume single-API workloads (≥10k calls/day to one source).** Direct subscriptions amortize better past the break-even point — Polymarket's free public API plus your own caching beats $0.001 × 10k/day if you don't need cross-source aggregation.
+- **Compliance-sensitive flows that need a fiat invoice / audit trail.** BlockRun settles in USDC; receipts are on-chain (Basescan / Solscan) but are not tax invoices. For enterprise procurement, contract directly with the upstream provider.
+- **Latency-critical sub-100ms reads.** Each x402 call adds ~200–500ms of payment-signing + settlement overhead vs. a direct authenticated request. For HFT-style flows, run your own infra.
+- **You only need one source forever.** If you'll only ever call Polymarket, or only ever Exa, save the indirection — sign up upstream and skip the wallet.
+
+Use BlockRun when you want pay-per-call for *exploration*, *aggregation*, or *agent-driven* workloads where you can't predict which source you'll reach for next.
+
+---
+
 ## Multi-agent budget delegation
 
 Delegate a spending budget to a child agent with `agent_id`. The child is auto-blocked when the budget runs out — useful for autonomous agents that shouldn't run up unbounded costs.
 
 ---
 
+## Troubleshooting
+
+- **`Insufficient balance` / HTTP 402 after retry** → Run `blockrun_wallet action:"setup"`. Send USDC on Base (or Solana — see [Environment Variables](#environment-variables)).
+- **`Smart routing (ClawRouter) is not available on Solana`** → Pass `model:` or `mode:` explicitly to `blockrun_chat`, or switch back to Base by unsetting `SOLANA_WALLET_KEY` and removing `~/.blockrun/.solana-session`.
+- **`claude mcp list` doesn't show `blockrun`** → Check `node -v` (must be ≥18). Clear the npx cache: `rm -rf ~/.npm/_npx`. Re-run the install command from above.
+- **`fetch failed` / timeout when checking wallet balance** → Base RPC transient outage. The tool already falls through 3 public RPCs; retry after 30s. Persistent failures usually = local proxy / firewall blocking outbound RPC.
+- **`ENOENT: ~/.blockrun/.session`** → Expected on first run. The server auto-creates the wallet; check stderr for the `WALLET_CREATED` line confirming the address.
+- **`Video generation timed out` (5-min cap)** → Upstream Seedance / xAI queue congestion. **No charge** (payment-on-completion). Retry, or pick a faster model (`bytedance/seedance-1.5-pro`).
+- **`Music generation timed out` (200s cap)** → Same pattern. **No charge**. Retry; if it persists, the upstream model is rate-limited — try off-peak.
+
+---
+
+## Environment Variables
+
+| Variable / File | Default | Effect |
+|---|---|---|
+| `~/.blockrun/.session` | auto-created on first run | EVM private key (0x...). File exists → use Base. |
+| `~/.blockrun/.solana-session` | not created | Solana private key. File exists → switch to Solana. |
+| `SOLANA_WALLET_KEY` | unset | Env-var override of `.solana-session`. Set → use Solana. |
+
+Chain selection priority (see `src/utils/wallet.ts:24`):
+
+1. `SOLANA_WALLET_KEY` env var present → Solana
+2. `~/.blockrun/.solana-session` exists → Solana
+3. Otherwise → Base (`~/.blockrun/.session` auto-created)
+
+**Switching chains:**
+
+- Base → Solana: `export SOLANA_WALLET_KEY=...`, or `echo "<secret>" > ~/.blockrun/.solana-session`
+- Solana → Base: `unset SOLANA_WALLET_KEY && rm ~/.blockrun/.solana-session` (the existing `.session` is reused, so it's the same Base wallet)
+
+The server also runs a non-blocking npm registry check at startup and prints an `Update available` notice to stderr when a newer `@blockrun/mcp` version exists. Upgrade by re-running the install command — no manual `npm update` needed.
+
+---
+
 ## How it works
 
-Pay-per-call via [x402](https://x402.org) micropayments in USDC on Base. Your wallet lives at `~/.blockrun/.session`. Private key never leaves your machine.
+Pay-per-call via [x402](https://x402.org) micropayments in USDC. Your wallet lives at `~/.blockrun/.session` (Base) or `~/.blockrun/.solana-session` (Solana). The private key never leaves your machine.
+
+---
+
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, the tool-vs-skill design rule, and how to add a new partner API.
+
+Issues: [github.com/blockrunai/blockrun-mcp/issues](https://github.com/blockrunai/blockrun-mcp/issues)
 
 ---
 

package/dist/index.js

@@ -6,38 +6,58 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/utils/wallet.ts
+import fs from "fs";
 import {
   LLMClient,
   ImageClient,
   PriceClient,
+  SolanaLLMClient,
   getOrCreateWallet,
+  loadSolanaWallet,
   getPaymentLinks,
   formatWalletCreatedMessage,
-  formatNeedsFundingMessage
+  formatNeedsFundingMessage,
+  SOLANA_WALLET_FILE_PATH
 } from "@blockrun/llm";
-var _client = null;
+var _evmClient = null;
 var _imageClient = null;
 var _priceClient = null;
-var _walletInfo = null;
-function ensureWallet() {
-  if (!_walletInfo) {
-    _walletInfo = getOrCreateWallet();
-    if (_walletInfo.isNew) {
-      console.error(formatWalletCreatedMessage(_walletInfo.address));
+var _evmWalletInfo = null;
+var _solanaClient = null;
+function getChain() {
+  if (process.env.SOLANA_WALLET_KEY) return "solana";
+  try {
+    if (fs.existsSync(SOLANA_WALLET_FILE_PATH)) return "solana";
+  } catch {
+  }
+  return "base";
+}
+function ensureEvmWallet() {
+  if (!_evmWalletInfo) {
+    _evmWalletInfo = getOrCreateWallet();
+    if (_evmWalletInfo.isNew) {
+      console.error(formatWalletCreatedMessage(_evmWalletInfo.address));
     }
   }
-  return _walletInfo;
+  return _evmWalletInfo;
 }
 function getOrCreateWalletKey() {
-  const info = ensureWallet();
+  const info = ensureEvmWallet();
   return info.privateKey;
 }
 function getClient() {
-  if (!_client) {
+  if (getChain() === "solana") {
+    if (!_solanaClient) {
+      const privateKey = process.env.SOLANA_WALLET_KEY || loadSolanaWallet() || void 0;
+      _solanaClient = new SolanaLLMClient(privateKey ? { privateKey } : void 0);
+    }
+    return _solanaClient;
+  }
+  if (!_evmClient) {
     const privateKey = getOrCreateWalletKey();
-    _client = new LLMClient({ privateKey });
+    _evmClient = new LLMClient({ privateKey });
   }
-  return _client;
+  return _evmClient;
 }
 function getImageClient() {
   if (!_imageClient) {
@@ -53,8 +73,21 @@ function getPriceClient() {
   }
   return _priceClient;
 }
-function getWalletInfo() {
-  const info = ensureWallet();
+async function getWalletInfo() {
+  if (getChain() === "solana") {
+    const client = getClient();
+    const address = await client.getWalletAddress();
+    return {
+      address,
+      network: "Solana",
+      chainId: null,
+      currency: "USDC",
+      isNew: false,
+      explorerUrl: `https://solscan.io/account/${address}`,
+      fundingUrl: "https://sol.blockrun.ai"
+    };
+  }
+  const info = ensureEvmWallet();
   const links = getPaymentLinks(info.address);
   return {
     address: info.address,
@@ -62,11 +95,19 @@ function getWalletInfo() {
     chainId: 8453,
     currency: "USDC",
     isNew: info.isNew,
-    basescanUrl: links.basescan,
+    explorerUrl: links.basescan,
     fundingUrl: links.blockrun
   };
 }
 async function getUsdcBalance(address) {
+  if (getChain() === "solana") {
+    try {
+      const client = getClient();
+      return await client.getBalance();
+    } catch {
+      return null;
+    }
+  }
   const USDC_ADDRESS2 = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
   const BASE_RPC_URLS = [
     "https://mainnet.base.org",
@@ -101,7 +142,8 @@ import { z } from "zod";
 // src/utils/qr.ts
 import QRCode from "qrcode";
 import open from "open";
-import * as fs from "fs";
+import * as fs2 from "fs";
+import sharp from "sharp";
 
 // src/utils/constants.ts
 import * as path from "path";
@@ -123,22 +165,53 @@ var MODEL_TIERS = {
 };
 
 // src/utils/qr.ts
+var SOLANA_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 function getEip681Uri(address, amountUsdc = 1) {
   const amountWei = Math.floor(amountUsdc * 1e6);
   return `ethereum:${USDC_ADDRESS}@${BASE_CHAIN_ID}/transfer?address=${address}&uint256=${amountWei}`;
 }
-async function generateQrPng(address) {
-  const eip681Uri = getEip681Uri(address);
-  if (!fs.existsSync(WALLET_DIR)) {
-    fs.mkdirSync(WALLET_DIR, { recursive: true, mode: 448 });
+function getSolanaPayUri(address, amountUsdc = 1) {
+  return `solana:${address}?spl-token=${SOLANA_USDC_MINT}&amount=${amountUsdc}&label=BlockRun`;
+}
+function buildSolanaLogoSvg(size) {
+  const half = size / 2;
+  return `<svg width="${size}" height="${size}" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="g" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#9945FF"/>
+      <stop offset="100%" style="stop-color:#14F195"/>
+    </linearGradient>
+    <clipPath id="c"><circle cx="${half}" cy="${half}" r="${half}"/></clipPath>
+  </defs>
+  <circle cx="${half}" cy="${half}" r="${half}" fill="url(#g)" clip-path="url(#c)"/>
+  <text x="${half}" y="${half + 14}" font-size="40" font-weight="bold" fill="white"
+    font-family="Arial,sans-serif" text-anchor="middle">\u25CE</text>
+</svg>`;
+}
+async function overlayLogo(qrBuf, chain, qrSize) {
+  if (chain !== "solana") return qrBuf;
+  const logoSize = Math.round(qrSize * 0.18);
+  const pad = Math.round(logoSize * 0.08);
+  const logoBuf = await sharp(Buffer.from(buildSolanaLogoSvg(logoSize))).resize(logoSize, logoSize).extend({ top: pad, bottom: pad, left: pad, right: pad, background: { r: 255, g: 255, b: 255, alpha: 1 } }).toBuffer();
+  const totalSize = logoSize + pad * 2;
+  const offset = Math.round((qrSize - totalSize) / 2);
+  return sharp(qrBuf).composite([{ input: logoBuf, left: offset, top: offset }]).toBuffer();
+}
+async function generateQrPng(address, chain = "base") {
+  const uri = chain === "solana" ? getSolanaPayUri(address) : getEip681Uri(address);
+  const qrSize = 400;
+  if (!fs2.existsSync(WALLET_DIR)) {
+    fs2.mkdirSync(WALLET_DIR, { recursive: true, mode: 448 });
   }
-  await QRCode.toFile(QR_FILE, eip681Uri, {
+  const qrBuf = await QRCode.toBuffer(uri, {
     type: "png",
-    width: 400,
+    width: qrSize,
     margin: 2,
     errorCorrectionLevel: "H",
     color: { dark: "#000000", light: "#FFFFFF" }
   });
+  const finalBuf = await overlayLogo(qrBuf, chain, qrSize);
+  fs2.writeFileSync(QR_FILE, finalBuf);
   return QR_FILE;
 }
 async function openQrInViewer(qrPath) {
@@ -157,15 +230,17 @@ function formatError(message) {
   if (isServerError) {
     errorText += `
 
-This is a temporary API issue. The xAI/Grok API may be experiencing problems.
+This is a temporary API issue. The API may be experiencing problems.
 Try again in a few minutes, or use a different model (e.g., openai/gpt-4o).`;
   } else if (isPaymentError) {
+    const chain = getChain();
+    const network = chain === "solana" ? "Solana" : "Base";
     errorText += `
 
 This error usually means your wallet needs funding.
 Run blockrun_wallet with action: "setup" to get funding instructions.
 
-Quick fix: Send USDC to your wallet on Base network.`;
+Quick fix: Send USDC to your wallet on ${network} network.`;
   }
   return errorText;
 }
@@ -210,8 +285,9 @@ Do NOT call this for actual AI queries \u2014 use blockrun_chat for that.`,
       }
     },
     async ({ action, budget_action, budget_amount, agent_id, agent_limit }) => {
-      const info = getWalletInfo();
+      const info = await getWalletInfo();
       const address = info.address;
+      const chain = getChain();
       if (action === "budget") {
         const budgetAct = budget_action || "check";
         if (budgetAct === "set") {
@@ -289,10 +365,11 @@ Pass agent_id: "${agent_id}" in any blockrun_* tool call to track and enforce th
       }
       if (action === "qr") {
         try {
-          const qrPath = await generateQrPng(address);
+          const qrPath = await generateQrPng(address, chain);
           await openQrInViewer(qrPath);
+          const scanNote = chain === "solana" ? "Scan with a Solana wallet (Phantom, Solflare) to send USDC on Solana." : "Scan with MetaMask to send USDC on Base.";
           return {
-            content: [{ type: "text", text: `QR code opened! Scan with MetaMask to send USDC on Base.
+            content: [{ type: "text", text: `QR code opened! ${scanNote}
 
 Address: ${address}
 QR saved: ${qrPath}` }]
@@ -307,14 +384,46 @@ QR saved: ${qrPath}` }]
       if (action === "setup") {
         let qrMessage = "";
         try {
-          const qrPath = await generateQrPng(address);
+          const qrPath = await generateQrPng(address, chain);
           await openQrInViewer(qrPath);
           qrMessage = `
 QR code opened for scanning! (${qrPath})`;
         } catch {
           qrMessage = "\n(QR generation failed - use address above)";
         }
-        const text2 = `
+        const text2 = chain === "solana" ? `
+================================================================================
+                        BLOCKRUN WALLET SETUP (SOLANA)
+================================================================================
+
+Your Solana wallet address: ${address}
+${qrMessage}
+
+HOW TO FUND YOUR WALLET:
+------------------------
+
+Option 1: Transfer from Coinbase
+  1. Open Coinbase app or website
+  2. Go to Send/Receive \u2192 Select USDC
+  3. Choose "Solana" network (important!)
+  4. Paste: ${address}
+  5. Send $1-5 to start
+
+Option 2: Transfer from any Solana wallet (Phantom, Solflare, Backpack)
+  - Send USDC (SPL) to: ${address}
+  - Make sure to use Solana network, not EVM
+
+Option 3: Bridge from other chains
+  https://portalbridge.com \u2192 Bridge USDC to Solana \u2192 Send to address above
+
+VERIFY BALANCE: https://solscan.io/account/${address}
+
+PRICING (pay per use):
+  - GPT-4o: ~$0.005/request | Claude Sonnet: ~$0.003/request
+  - Gemini Flash: ~$0.0001/request | Full pricing: https://blockrun.ai/pricing
+
+SECURITY: Private key stored at ~/.blockrun/.solana-session (never leaves your machine)
+================================================================================` : `
 ================================================================================
                         BLOCKRUN WALLET SETUP
 ================================================================================
@@ -351,9 +460,10 @@ SECURITY: Private key stored at ~/.blockrun/.session (never leaves your machine)
       const balance = await getUsdcBalance(address);
       const balanceStr = balance !== null ? `$${balance.toFixed(6)} USDC` : "Unable to fetch";
       const lowBalance = balance !== null && balance < 1;
+      const explorerLabel = chain === "solana" ? "Solscan" : "Basescan";
       const text = `Wallet: ${address}
 Balance: ${balanceStr}${lowBalance ? " (low - add funds)" : ""}
-Network: Base | View: ${info.basescanUrl}
+Network: ${info.network} | View: ${info.explorerUrl}
 ${info.isNew ? "\nNEW WALLET - Run with action: 'setup' for funding instructions" : ""}`;
       return {
         content: [{ type: "text", text }],
@@ -363,7 +473,8 @@ ${info.isNew ? "\nNEW WALLET - Run with action: 'setup' for funding instructions
           network: info.network,
           chainId: info.chainId,
           isNew: info.isNew,
-          basescanUrl: info.basescanUrl
+          explorerUrl: info.explorerUrl,
+          explorerLabel
         }
       };
     }
@@ -372,6 +483,7 @@ ${info.isNew ? "\nNEW WALLET - Run with action: 'setup' for funding instructions
 
 // src/tools/chat.ts
 import { z as z2 } from "zod";
+import { LLMClient as LLMClient2 } from "@blockrun/llm";
 
 // src/utils/budget.ts
 function checkBudget(budget, agentId) {
@@ -448,6 +560,12 @@ Run blockrun_models to see all 41+ models with pricing.`,
         };
       }
       if (routing === "smart") {
+        if (!(llm instanceof LLMClient2)) {
+          return {
+            content: [{ type: "text", text: "Smart routing (ClawRouter) is not available on Solana. Use a specific model or mode instead." }],
+            isError: true
+          };
+        }
         try {
           const result = await llm.smartChat(message, {
             system,
@@ -1594,6 +1712,201 @@ Pricing:
   );
 }
 
+// src/tools/phone.ts
+import { z as z14 } from "zod";
+function registerPhoneTool(server) {
+  server.registerTool(
+    "blockrun_phone",
+    {
+      description: `Phone number intelligence, provisioning, and outbound AI voice calls via BlockRun x402.
+
+Pricing:
+- lookup: $0.01 \u2014 carrier + line type for any number
+- lookup_fraud: $0.05 \u2014 + SIM swap / call forwarding signals
+- numbers_buy: $5.00 \u2014 provision a US/CA number for 30 days
+- numbers_renew: $5.00 \u2014 extend lease 30 days
+- numbers_list: $0.001 \u2014 list your wallet-owned numbers
+- numbers_release: free \u2014 release number back to pool
+- voice_call: $0.54 flat \u2014 outbound AI voice call via Bland.ai (up to 5 min default)
+- voice_status: free \u2014 poll call status + transcript
+
+Voice call flow:
+  1. blockrun_phone action:"voice_call" to:"+1..." task:"Confirm appointment for..."
+  2. Returns call_id immediately (call runs async)
+  3. blockrun_phone action:"voice_status" call_id:"..." to poll until completed
+
+Voice presets: nat, josh, maya, june, paige, derek, florian
+Phone numbers use E.164 format: +14155552671`,
+      inputSchema: {
+        action: z14.enum([
+          "lookup",
+          "lookup_fraud",
+          "numbers_buy",
+          "numbers_renew",
+          "numbers_list",
+          "numbers_release",
+          "voice_call",
+          "voice_status"
+        ]).describe("Action to perform"),
+        phone_number: z14.string().optional().describe("E.164 phone number, e.g. +14155552671 (required for lookup, lookup_fraud, numbers_renew, numbers_release)"),
+        country: z14.string().optional().describe("Country for numbers_buy: US or CA (default: US)"),
+        area_code: z14.string().optional().describe("Preferred 3-digit area code for numbers_buy (best effort)"),
+        to: z14.string().optional().describe("Destination E.164 number (required for voice_call)"),
+        task: z14.string().optional().describe("What the AI should do on the call, 10\u20134000 chars (required for voice_call)"),
+        from: z14.string().optional().describe("Your provisioned BlockRun caller ID number (optional for voice_call)"),
+        voice: z14.enum(["nat", "josh", "maya", "june", "paige", "derek", "florian"]).optional().describe("AI voice preset"),
+        max_duration: z14.number().min(1).max(30).optional().describe("Max call duration in minutes (1\u201330, default: 5)"),
+        language: z14.string().optional().describe("Language code, e.g. en-US (default: en-US)"),
+        first_sentence: z14.string().optional().describe("Custom opening line for the AI agent"),
+        wait_for_greeting: z14.boolean().optional().describe("Wait for recipient to speak before AI starts"),
+        call_id: z14.string().optional().describe("Call ID from voice_call response (required for voice_status)")
+      }
+    },
+    async ({
+      action,
+      phone_number,
+      country,
+      area_code,
+      to,
+      task,
+      from,
+      voice,
+      max_duration,
+      language,
+      first_sentence,
+      wait_for_greeting,
+      call_id
+    }) => {
+      const client = getClient();
+      const req = client;
+      const chain = getChain();
+      try {
+        let result;
+        switch (action) {
+          case "lookup": {
+            if (!phone_number) return { content: [{ type: "text", text: "phone_number required (E.164)" }], isError: true };
+            result = await req.requestWithPaymentRaw("/v1/phone/lookup", { phoneNumber: phone_number });
+            break;
+          }
+          case "lookup_fraud": {
+            if (!phone_number) return { content: [{ type: "text", text: "phone_number required (E.164)" }], isError: true };
+            result = await req.requestWithPaymentRaw("/v1/phone/lookup/fraud", { phoneNumber: phone_number });
+            break;
+          }
+          case "numbers_buy": {
+            const body = {};
+            if (country) body.country = country;
+            if (area_code) body.areaCode = area_code;
+            result = await req.requestWithPaymentRaw("/v1/phone/numbers/buy", body);
+            break;
+          }
+          case "numbers_renew": {
+            if (!phone_number) return { content: [{ type: "text", text: "phone_number required (E.164)" }], isError: true };
+            result = await req.requestWithPaymentRaw("/v1/phone/numbers/renew", { phoneNumber: phone_number });
+            break;
+          }
+          case "numbers_list": {
+            result = await req.requestWithPaymentRaw("/v1/phone/numbers/list", {});
+            break;
+          }
+          case "numbers_release": {
+            if (!phone_number) return { content: [{ type: "text", text: "phone_number required (E.164)" }], isError: true };
+            result = await req.requestWithPaymentRaw("/v1/phone/numbers/release", { phoneNumber: phone_number });
+            break;
+          }
+          case "voice_call": {
+            if (!to) return { content: [{ type: "text", text: "to (destination phone number) required" }], isError: true };
+            if (!task) return { content: [{ type: "text", text: "task required (what the AI should do on the call)" }], isError: true };
+            const body = { to, task };
+            if (from) body.from = from;
+            if (voice) body.voice = voice;
+            if (max_duration !== void 0) body.max_duration = max_duration;
+            if (language) body.language = language;
+            if (first_sentence) body.first_sentence = first_sentence;
+            if (wait_for_greeting !== void 0) body.wait_for_greeting = wait_for_greeting;
+            result = await req.requestWithPaymentRaw("/v1/voice/call", body);
+            break;
+          }
+          case "voice_status": {
+            if (!call_id) return { content: [{ type: "text", text: "call_id required" }], isError: true };
+            const apiBase = chain === "solana" ? "https://sol.blockrun.ai/api" : "https://blockrun.ai/api";
+            const resp = await fetch(`${apiBase}/v1/voice/call/${encodeURIComponent(call_id)}`, {
+              signal: AbortSignal.timeout(15e3)
+            });
+            if (!resp.ok) {
+              const err = await resp.text().catch(() => resp.statusText);
+              return { content: [{ type: "text", text: formatError(`voice_status ${resp.status}: ${err}`) }], isError: true };
+            }
+            result = await resp.json();
+            break;
+          }
+        }
+        const text = typeof result === "object" ? JSON.stringify(result, null, 2) : String(result);
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: result
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: formatError(err instanceof Error ? err.message : String(err)) }], isError: true };
+      }
+    }
+  );
+}
+
+// src/tools/surf.ts
+import { z as z15 } from "zod";
+function registerSurfTool(server) {
+  server.registerTool(
+    "blockrun_surf",
+    {
+      description: `Unified crypto data via Surf (asksurf.ai) \u2014 84 endpoints, one API.
+
+Coverage: CEX market data (16 exchanges), on-chain SQL across 13 chains, 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social mindshare / CT intelligence, news, unified search, and Surf-1.5 chat with citations.
+
+Pricing (settled in USDC to Surf's Base treasury):
+- Tier 1 $0.001 \u2014 prices, rankings, lists, news, profiles, simple reads
+- Tier 2 $0.005 \u2014 order books, candles, search, wallet detail, social aggregates
+- Tier 3 $0.020 \u2014 raw on-chain SQL, structured queries, surf-1.5 chat
+
+Common paths (full 84-endpoint catalog in the surf skill):
+- market/price?symbol=BTC                     (T1)
+- exchange/price?pair=BTC-USDT                (T1)
+- prediction-market/polymarket/ranking         (T1)
+- search/web?q=ethereum+pectra+upgrade        (T2)
+- wallet/detail?address=0x...                 (T2)
+- social/mindshare?q=ethereum&interval=1d     (T2)
+- onchain/sql        + body:{ sql: "SELECT ..." }                  (T3)
+- chat/completions   + body:{ model:"surf/surf-1.5", messages:[]}  (T3, $0.02 flat)
+
+Method is auto-routed: pass 'body' for POST endpoints; otherwise GET with 'params'.
+Each Surf endpoint pre-validates required params before settling \u2014 you get a 400 (not a charge) if a required field is missing. Browse the full catalog: https://blockrun.ai/marketplace/surf`,
+      inputSchema: {
+        path: z15.string().describe("Endpoint path under /v1/surf/, e.g. 'market/price', 'prediction-market/polymarket/ranking', 'wallet/detail', 'onchain/sql', 'chat/completions'"),
+        params: z15.record(z15.string(), z15.string()).optional().describe("Query parameters for GET endpoints, e.g. { symbol: 'BTC' } or { address: '0x...', chain: 'ethereum' }"),
+        body: z15.any().optional().describe("JSON body for POST endpoints. Provide for: onchain/query, onchain/sql, chat/completions. When set, the call is sent as POST; otherwise GET with params.")
+      }
+    },
+    async ({ path: path3, params, body }) => {
+      try {
+        const client = getClient();
+        const cleanPath = path3.replace(/^\/+/, "").replace(/^v1\/surf\//, "").replace(/^api\/v1\/surf\//, "");
+        const endpoint = `/v1/surf/${cleanPath}`;
+        const result = body !== void 0 ? await client.requestWithPaymentRaw(endpoint, body) : await client.getWithPaymentRaw(endpoint, params);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          structuredContent: result
+        };
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: formatError(errMsg) }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/mcp-handler.ts
 function initializeMcpServer(server) {
   const budget = { limit: null, spent: 0, calls: 0, agents: /* @__PURE__ */ new Map() };
@@ -1611,17 +1924,22 @@ function initializeMcpServer(server) {
   registerTwitterTool(server);
   registerDexTool(server);
   registerModalTool(server);
+  registerPhoneTool(server);
+  registerSurfTool(server);
   server.registerResource(
     "wallet",
     "blockrun://wallet",
     { description: "Wallet address and status", mimeType: "application/json" },
-    async () => ({
-      contents: [{
-        uri: "blockrun://wallet",
-        mimeType: "application/json",
-        text: JSON.stringify(getWalletInfo(), null, 2)
-      }]
-    })
+    async () => {
+      const info = await getWalletInfo();
+      return {
+        contents: [{
+          uri: "blockrun://wallet",
+          mimeType: "application/json",
+          text: JSON.stringify(info, null, 2)
+        }]
+      };
+    }
   );
   server.registerResource(
     "models",
@@ -1647,7 +1965,7 @@ function initializeMcpServer(server) {
 }
 
 // src/utils/key-leak-scanner.ts
-import fs2 from "fs";
+import fs3 from "fs";
 import path2 from "path";
 import os2 from "os";
 function looksLikeRawPrivateKey(value) {
@@ -1674,8 +1992,8 @@ function walk(obj, file, jsonPath, out) {
 }
 function scanFile(file) {
   try {
-    if (!fs2.existsSync(file)) return [];
-    const raw = fs2.readFileSync(file, "utf-8");
+    if (!fs3.existsSync(file)) return [];
+    const raw = fs3.readFileSync(file, "utf-8");
     const data = JSON.parse(raw);
     const out = [];
     walk(data, file, "", out);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Give your AI agent web search, deep research, prediction markets, crypto data, X/Twitter intelligence. Paid via x402 micropayments.",
   "type": "module",
@@ -14,7 +14,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts --format esm --dts --clean --external sharp",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
@@ -48,6 +48,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "open": "^11.0.0",
     "qrcode": "^1.5.4",
+    "sharp": "^0.34.5",
     "viem": "^2.21.0",
     "zod": "^4.3.5"
   },