@xlmtools/cli 0.1.0

package/dist/tools/stellar-pools.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+import { logger } from "../lib/logger.js";
+export function registerStellarPoolsTool(server) {
+    server.registerTool("stellar-pools", {
+        title: "Stellar Liquidity Pools",
+        description: `Browse Stellar liquidity pools. Optionally filter by asset.\n` +
+            `Shows reserves, shares, trustlines, and fees.\nFree.`, inputSchema: z.object({
+            asset: z
+                .string()
+                .optional()
+                .describe('Filter by asset (e.g. "XLM", "USDC"). Omit for all pools.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(10)
+                .describe("Number of pools (1-200)"),
+        }),
+    }, async ({ asset, limit }) => {
+        logger.debug({ asset, limit }, "stellar-pools invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const params = new URLSearchParams({ limit: String(limit) });
+            if (asset)
+                params.set("asset", asset);
+            const res = await fetch(`${config.apiUrl}/stellar-pools?${params}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Pools error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "stellar-pools error");
+            return err(`Pools failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/stocks.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { okPaid, err } from "../lib/format.js";
+import { logger } from "../lib/logger.js";
+import { TOOL_PRICES } from "../lib/config.js";
+import { withBudget } from "../lib/budget.js";
+import { withCache } from "../lib/cache.js";
+export function registerStocksTool(server) {
+    server.registerTool("stocks", {
+        title: "Stock Quotes",
+        description: `Get real-time stock price and market data for any ticker symbol.\nCost: $${TOOL_PRICES.stocks} USDC per query (paid via Stellar MPP).`, inputSchema: z.object({
+            symbol: z
+                .string()
+                .describe("Stock ticker symbol (e.g. AAPL, TSLA, MSFT)"),
+        }),
+    }, async ({ symbol }) => {
+        logger.debug({ symbol }, "stocks tool invoked");
+        return withCache("stocks", { symbol }, () => withBudget("stocks", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const res = await fetch(`${config.apiUrl}/stocks?symbol=${encodeURIComponent(symbol)}`);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`Stocks API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "stocks tool error");
+                return err(`Stocks query failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/dist/tools/swap-quote.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+import { logger } from "../lib/logger.js";
+export function registerSwapQuoteTool(server) {
+    server.registerTool("swap-quote", {
+        title: "Stellar Swap Quote",
+        description: `Find the best swap path between any two Stellar assets using the native DEX.\n` +
+            `Shows rate, path hops, and slippage tips.\n` +
+            `Examples: swap 100 XLM to USDC, swap 50 USDC to EURC.\n` +
+            `Well-known assets: XLM, USDC, EURC, AQUA, yUSDC, BLND, SHX.\nFree.`, inputSchema: z.object({
+            from: z.string().describe('Source asset (e.g. "XLM", "USDC")'),
+            to: z.string().describe('Destination asset (e.g. "USDC", "EURC")'),
+            amount: z.string().describe("Amount to swap"),
+            mode: z
+                .enum(["send", "receive"])
+                .default("send")
+                .describe('"send" = you fix what you send; "receive" = you fix what you get'),
+        }),
+    }, async ({ from, to, amount, mode }) => {
+        logger.debug({ from, to, amount, mode }, "swap-quote invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const params = new URLSearchParams({ from, to, amount, mode });
+            const res = await fetch(`${config.apiUrl}/swap-quote?${params}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Swap quote error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "swap-quote error");
+            return err(`Swap quote failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/tools-list.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { TOOL_PRICES, FREE_TOOLS } from "../lib/config.js";
+import { ok } from "../lib/format.js";
+export function registerToolsListTool(server) {
+    server.registerTool("tools", {
+        title: "List Tools",
+        description: "List all XLMTools tools with their per-call cost in USDC.", inputSchema: z.object({}),
+    }, async () => {
+        return ok({
+            paid: Object.entries(TOOL_PRICES).map(([tool, cost]) => ({ tool, cost_usdc: cost })),
+            free: Array.from(FREE_TOOLS),
+            network: "stellar:testnet",
+            payment: "MPP charge mode — USDC auto-deducted per call",
+        });
+    });
+}

package/dist/tools/wallet-tool.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { Horizon } from "@stellar/stellar-sdk";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+import { logger } from "../lib/logger.js";
+export function registerWalletTool(server) {
+    server.registerTool("wallet", {
+        title: "XLMTools Wallet",
+        description: "Show your Stellar wallet address, current USDC balance, and how to fund it. Free.", inputSchema: z.object({}),
+    }, async () => {
+        logger.debug("wallet tool invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const horizon = new Horizon.Server("https://horizon-testnet.stellar.org");
+            const account = await horizon.loadAccount(config.stellarPublicKey);
+            const xlm = account.balances.find((b) => b.asset_type === "native");
+            const usdc = account.balances.find((b) => b.asset_type === "credit_alphanum4" &&
+                b.asset_code === "USDC");
+            return ok({
+                address: config.stellarPublicKey,
+                xlm_balance: xlm?.balance ?? "0",
+                usdc_balance: usdc?.balance ?? "0 (no USDC trustline yet)",
+                fund_instructions: [
+                    "1. Get testnet XLM: https://lab.stellar.org/account/fund",
+                    "2. Get testnet USDC: https://faucet.circle.com (select Stellar Testnet)",
+                    `3. Send USDC to: ${config.stellarPublicKey}`,
+                ],
+            });
+        }
+        catch (e) {
+            logger.error({ err: e }, "wallet tool error");
+            return err(`Failed to load account: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/weather.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+export function registerWeatherTool(server) {
+    server.registerTool("weather", {
+        title: "Weather",
+        description: "Current weather and conditions for any city. Free.", inputSchema: z.object({
+            location: z.string().describe("City name (e.g. Lagos, London, New York)"),
+        }),
+    }, async ({ location }) => {
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/weather?location=${encodeURIComponent(location)}`);
+            if (!res.ok)
+                return err(`Weather API error: ${res.status}`);
+            return ok(await res.json());
+        }
+        catch (e) {
+            return err(String(e));
+        }
+    });
+}

package/dist/tools/youtube.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { okPaid, err } from "../lib/format.js";
+import { logger } from "../lib/logger.js";
+import { TOOL_PRICES } from "../lib/config.js";
+import { withBudget } from "../lib/budget.js";
+import { withCache } from "../lib/cache.js";
+export function registerYoutubeTool(server) {
+    server.registerTool("youtube", {
+        title: "YouTube Search / Lookup",
+        description: `Search YouTube videos or look up a specific video by ID. Provide either query or id.\nCost: $${TOOL_PRICES.youtube} USDC per call (paid via Stellar MPP).`, inputSchema: z.object({
+            query: z.string().optional().describe("Search query to find videos"),
+            id: z.string().optional().describe("YouTube video ID for direct lookup"),
+        }),
+    }, async ({ query, id }) => {
+        logger.debug({ query, id }, "youtube tool invoked");
+        if (!query && !id) {
+            return err("Provide either query or id");
+        }
+        const params = { query, id };
+        return withCache("youtube", params, () => withBudget("youtube", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const qs = new URLSearchParams();
+                if (query)
+                    qs.set("q", query);
+                if (id)
+                    qs.set("id", id);
+                const res = await fetch(`${config.apiUrl}/youtube?${qs.toString()}`);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`YouTube API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "youtube tool error");
+                return err(`YouTube lookup failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@xlmtools/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "xlmtools": "dist/index.js",
+    "xlm": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@stellar/mpp": "^0.4.0",
+    "@stellar/stellar-sdk": "^15.0.1",
+    "mppx": "^0.5.5",
+    "pino": "^10.3.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+import { Mppx } from "mppx/client";
+import { stellar } from "@stellar/mpp/charge/client";
+import { Horizon } from "@stellar/stellar-sdk";
+import { loadOrCreateWallet, getKeypair } from "./lib/wallet.js";
+import { TOOL_PRICES } from "./lib/config.js";
+import { logger } from "./lib/logger.js";
+
+// ── Arg parsing ──────────────────────────────────────────
+
+function parseArgs(argv: string[]) {
+  const [tool, ...rest] = argv;
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i].startsWith("--") && i + 1 < rest.length) {
+      const key = rest[i].slice(2).replace(/-/g, "_");
+      flags[key] = rest[i + 1];
+      i++;
+    } else {
+      positional.push(rest[i]);
+    }
+  }
+
+  return { tool: tool ?? "", positional, flags };
+}
+
+// ── URL builder ──────────────────────────────────────────
+
+function buildRequest(
+  base: string,
+  tool: string,
+  pos: string[],
+  flags: Record<string, string>,
+): { url: string; init: RequestInit } {
+  const p = new URLSearchParams();
+
+  // Map each tool to its API endpoint + params
+  const toolMap: Record<string, () => { path: string; method?: string; body?: string }> = {
+    search:          () => { p.set("q", pos[0] ?? ""); if (flags.count) p.set("count", flags.count); return { path: "/search" }; },
+    research:        () => { p.set("q", pos[0] ?? ""); if (flags.num_results) p.set("num_results", flags.num_results); return { path: "/research" }; },
+    youtube:         () => { if (flags.id) p.set("id", flags.id); else p.set("q", pos[0] ?? flags.query ?? ""); return { path: "/youtube" }; },
+    screenshot:      () => { p.set("url", pos[0] ?? ""); if (flags.format) p.set("format", flags.format); return { path: "/screenshot" }; },
+    scrape:          () => { p.set("url", pos[0] ?? ""); return { path: "/scrape" }; },
+    image:           () => ({ path: "/image", method: "POST", body: JSON.stringify({ prompt: pos[0] ?? "", size: flags.size ?? "1024x1024" }) }),
+    stocks:          () => { p.set("symbol", pos[0] ?? ""); return { path: "/stocks" }; },
+    crypto:          () => { p.set("ids", pos[0] ?? ""); if (flags.vs_currency) p.set("vs_currency", flags.vs_currency); return { path: "/crypto" }; },
+    weather:         () => { p.set("location", pos[0] ?? ""); return { path: "/weather" }; },
+    domain:          () => { p.set("name", pos[0] ?? ""); return { path: "/domain" }; },
+    "dex-orderbook": () => { p.set("pair", pos[0] ?? ""); if (flags.limit) p.set("limit", flags.limit); return { path: "/dex-orderbook" }; },
+    "dex-candles":   () => { p.set("pair", pos[0] ?? ""); if (flags.resolution) p.set("resolution", flags.resolution); if (flags.limit) p.set("limit", flags.limit); return { path: "/dex-candles" }; },
+    "dex-trades":    () => { p.set("pair", pos[0] ?? ""); if (flags.limit) p.set("limit", flags.limit); if (flags.trade_type) p.set("trade_type", flags.trade_type); return { path: "/dex-trades" }; },
+    "swap-quote":    () => { p.set("from", pos[0] ?? flags.from ?? ""); p.set("to", pos[1] ?? flags.to ?? ""); p.set("amount", pos[2] ?? flags.amount ?? ""); if (flags.mode) p.set("mode", flags.mode); return { path: "/swap-quote" }; },
+    "stellar-asset": () => { p.set("asset", pos[0] ?? ""); return { path: "/stellar-asset" }; },
+    "stellar-account": () => { p.set("address", pos[0] ?? ""); return { path: "/stellar-account" }; },
+    "stellar-pools": () => { if (pos[0] || flags.asset) p.set("asset", pos[0] ?? flags.asset ?? ""); if (flags.limit) p.set("limit", flags.limit); return { path: "/stellar-pools" }; },
+    "oracle-price":  () => { p.set("asset", pos[0] ?? ""); if (flags.feed) p.set("feed", flags.feed); return { path: "/oracle-price" }; },
+  };
+
+  const builder = toolMap[tool];
+  if (!builder) {
+    process.stderr.write(`Unknown tool: ${tool}\nRun xlm --help for available tools.\n`);
+    process.exit(1);
+  }
+
+  const { path, method, body } = builder();
+  const qs = p.toString();
+  const url = qs ? `${base}${path}?${qs}` : `${base}${path}`;
+  const init: RequestInit = { method: method ?? "GET" };
+  if (body) {
+    init.headers = { "Content-Type": "application/json" };
+    init.body = body;
+  }
+
+  return { url, init };
+}
+
+// ── Local tool handlers ──────────────────────────────────
+
+async function handleWallet(publicKey: string) {
+  const server = new Horizon.Server("https://horizon-testnet.stellar.org");
+  try {
+    const account = await server.loadAccount(publicKey);
+    const xlm = account.balances.find(
+      (b: Horizon.HorizonApi.BalanceLine) => b.asset_type === "native",
+    );
+    const usdc = account.balances.find(
+      (b: Horizon.HorizonApi.BalanceLine) =>
+        "asset_code" in b && b.asset_code === "USDC",
+    );
+    return {
+      address: publicKey,
+      network: "stellar:testnet",
+      xlm_balance: xlm?.balance ?? "0",
+      usdc_balance: usdc && "balance" in usdc ? usdc.balance : "0",
+    };
+  } catch {
+    return {
+      address: publicKey,
+      network: "stellar:testnet",
+      xlm_balance: "0",
+      usdc_balance: "0",
+      note: "Account not funded yet",
+    };
+  }
+}
+
+function handleTools() {
+  const paid = Object.entries(TOOL_PRICES).map(([name, price]) => ({
+    name,
+    price: `$${price}`,
+  }));
+  // Note: `budget` is MCP-only — the CLI is a fresh process per invocation
+  // so a session-scoped cap is meaningless. Excluded from the CLI's free list.
+  const free = [
+    "crypto", "weather", "domain", "wallet", "tools",
+    "dex-orderbook", "dex-candles", "dex-trades", "swap-quote",
+    "stellar-asset", "stellar-account", "stellar-pools", "oracle-price",
+  ];
+  return { paid, free, network: "stellar:testnet", payment: "MPP / USDC" };
+}
+
+// ── Help text ────────────────────────────────────────────
+
+const HELP = `XLMTools CLI — Stellar-native tools with pay-per-call
+
+Usage: xlm <tool> [args] [--flag value]
+
+Paid tools ($0.001-$0.04 USDC via Stellar MPP):
+  search <query> [--count N]            Web search
+  research <query> [--num-results N]    Deep research
+  youtube <query> | --id <id>           YouTube search/lookup
+  screenshot <url> [--format png]       Capture URL screenshot
+  scrape <url>                          Extract text from URL
+  image <prompt> [--size 1024x1024]     AI image generation
+  stocks <symbol>                       Stock quotes
+
+Free tools:
+  crypto <ids> [--vs-currency usd]      Crypto prices
+  weather <location>                    Current weather
+  domain <name>                         Domain availability
+  dex-orderbook <pair> [--limit N]      Stellar DEX orderbook
+  dex-candles <pair>                    OHLCV candlesticks
+  dex-trades <pair>                     Recent DEX trades
+  swap-quote <from> <to> <amount>       DEX swap pathfinding
+  stellar-asset <asset>                 Asset info
+  stellar-account <address>             Account lookup
+  stellar-pools [--asset X]             Liquidity pools
+  oracle-price <asset> [--feed crypto]  Oracle prices
+  wallet                                Your Stellar wallet
+  tools                                 List all tools
+
+Examples:
+  xlm search "Stellar MPP micropayments"
+  xlm crypto bitcoin,ethereum,stellar
+  xlm weather Lagos
+  xlm stocks AAPL
+  xlm dex-orderbook XLM/USDC --limit 5
+  xlm wallet
+`;
+
+// ── Main ─────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const { tool, positional, flags } = parseArgs(args);
+
+  // Init wallet + mppx (payment handling)
+  const config = loadOrCreateWallet();
+  const keypair = getKeypair(config);
+
+  Mppx.create({
+    methods: [
+      stellar.charge({
+        keypair,
+        mode: "pull",
+        onProgress(event) {
+          logger.debug({ eventType: event.type }, "MPP payment event");
+        },
+      }),
+    ],
+  });
+
+  // ── Local tools (no API call needed) ──
+
+  if (tool === "wallet") {
+    const data = await handleWallet(config.stellarPublicKey);
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (tool === "tools") {
+    console.log(JSON.stringify(handleTools(), null, 2));
+    return;
+  }
+
+  // ── API tools ──
+
+  const isPaid = tool in TOOL_PRICES;
+  const { url, init } = buildRequest(config.apiUrl, tool, positional, flags);
+
+  if (isPaid) {
+    process.stderr.write(`  Tool: ${tool} · Cost: $${TOOL_PRICES[tool]} USDC\n`);
+  }
+
+  const res = await fetch(url, init);
+
+  if (!res.ok) {
+    const text = await res.text();
+    process.stderr.write(`Error ${res.status}: ${text}\n`);
+    process.exit(1);
+  }
+
+  const data = (await res.json()) as Record<string, unknown>;
+
+  // Print receipt footer for paid tools
+  if (isPaid && data.receipt) {
+    const { receipt, ...rest } = data;
+    const r = receipt as { tx_hash: string; amount: string; currency: string; network: string };
+    console.log(JSON.stringify(rest, null, 2));
+    const hash = r.tx_hash.length > 16 ? r.tx_hash.slice(0, 16) + "..." : r.tx_hash;
+    const network = r.network === "stellar:testnet" ? "stellar testnet" : r.network;
+    process.stderr.write(`\n  Payment: $${r.amount} ${r.currency} · tx/${hash} · ${network}\n`);
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+main().catch((e) => {
+  logger.error({ err: e }, "CLI fatal error");
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Mppx } from "mppx/client";
+import { stellar } from "@stellar/mpp/charge/client";
+import { loadOrCreateWallet, getKeypair } from "./lib/wallet.js";
+import { logger } from "./lib/logger.js";
+import { registerCryptoTool } from "./tools/crypto.js";
+import { registerWeatherTool } from "./tools/weather.js";
+import { registerDomainTool } from "./tools/domain.js";
+import { registerToolsListTool } from "./tools/tools-list.js";
+import { registerWalletTool } from "./tools/wallet-tool.js";
+import { registerSearchTool } from "./tools/search.js";
+import { registerResearchTool } from "./tools/research.js";
+
+import { registerYoutubeTool } from "./tools/youtube.js";
+import { registerScreenshotTool } from "./tools/screenshot.js";
+import { registerScrapeTool } from "./tools/scrape.js";
+import { registerImageTool } from "./tools/image.js";
+import { registerStocksTool } from "./tools/stocks.js";
+import { registerDexOrderbookTool } from "./tools/dex-orderbook.js";
+import { registerDexCandlesTool } from "./tools/dex-candles.js";
+import { registerDexTradesTool } from "./tools/dex-trades.js";
+import { registerSwapQuoteTool } from "./tools/swap-quote.js";
+import { registerStellarAssetTool } from "./tools/stellar-asset.js";
+import { registerStellarAccountTool } from "./tools/stellar-account.js";
+import { registerStellarPoolsTool } from "./tools/stellar-pools.js";
+import { registerOraclePriceTool } from "./tools/oracle-price.js";
+import { registerBudgetTool } from "./tools/budget.js";
+
+const config = loadOrCreateWallet();
+const keypair = getKeypair(config);
+
+// Mppx polyfills global fetch to auto-handle 402 payments
+Mppx.create({
+  methods: [
+    stellar.charge({
+      keypair,
+      mode: "pull",
+      onProgress(event) {
+        logger.debug({ eventType: event.type }, "MPP payment event");
+      },
+    }),
+  ],
+});
+
+// { logging: {} } enables ctx.mcpReq.log() in tool handlers
+const server = new McpServer(
+  { name: "xlmtools", version: "0.1.0" },
+  { capabilities: { tools: {}, logging: {} } }
+);
+
+// Free tools
+registerCryptoTool(server);
+registerWeatherTool(server);
+registerDomainTool(server);
+registerToolsListTool(server);
+registerWalletTool(server);
+registerBudgetTool(server);
+
+// Paid tools
+registerSearchTool(server);
+registerResearchTool(server);
+
+registerYoutubeTool(server);
+registerScreenshotTool(server);
+registerScrapeTool(server);
+registerImageTool(server);
+registerStocksTool(server);
+
+// Stellar-native tools (free)
+registerDexOrderbookTool(server);
+registerDexCandlesTool(server);
+registerDexTradesTool(server);
+registerSwapQuoteTool(server);
+registerStellarAssetTool(server);
+registerStellarAccountTool(server);
+registerStellarPoolsTool(server);
+registerOraclePriceTool(server);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info("XLMTools MCP server running");
+}
+
+main().catch((error) => {
+  logger.error({ err: error }, "Fatal error");
+  process.exit(1);
+});

package/src/lib/budget.ts

@@ -0,0 +1,78 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { err } from "./format.js";
+import { TOOL_PRICES } from "./config.js";
+import { logger } from "./logger.js";
+
+// Session-scoped budget state (resets on MCP server restart)
+let maxBudget: number | null = null;
+let totalSpent = 0;
+
+export function setBudget(max: number): void {
+  maxBudget = max;
+  // Reset spent counter so the new cap starts fresh. Users expect
+  // "I just set a $1.00 budget" to mean they have $1.00 to spend
+  // from now — not "$1.00 minus whatever I spent before setting it".
+  totalSpent = 0;
+  logger.info({ max }, "session budget set");
+}
+
+export function clearBudget(): void {
+  maxBudget = null;
+  totalSpent = 0;
+  logger.info("session budget cleared");
+}
+
+export function getStatus(): {
+  max: number | null;
+  spent: number;
+  remaining: number | null;
+} {
+  return {
+    max: maxBudget,
+    spent: Math.round(totalSpent * 1000) / 1000,
+    remaining:
+      maxBudget !== null
+        ? Math.round((maxBudget - totalSpent) * 1000) / 1000
+        : null,
+  };
+}
+
+function canSpend(amount: number): boolean {
+  if (maxBudget === null) return true;
+  // Round to 3 decimal places to avoid floating-point drift
+  const spent = Math.round(totalSpent * 1000) / 1000;
+  return spent + amount <= maxBudget;
+}
+
+function recordSpend(amount: number): void {
+  totalSpent += amount;
+  logger.debug({ amount, totalSpent }, "spend recorded");
+}
+
+/**
+ * Wrap a paid tool call with budget checking.
+ * If budget would be exceeded, returns an error without calling the API.
+ * On success, records the spend.
+ */
+export async function withBudget(
+  toolName: string,
+  fn: () => Promise<CallToolResult>,
+): Promise<CallToolResult> {
+  const price = parseFloat(TOOL_PRICES[toolName] ?? "0");
+  if (!canSpend(price)) {
+    const status = getStatus();
+    return err(
+      `Budget limit reached. This call costs $${TOOL_PRICES[toolName]} ` +
+        `but only $${status.remaining?.toFixed(3)} remains. ` +
+        `Use the budget tool to check or adjust your limit.`,
+    );
+  }
+
+  const result = await fn();
+
+  if (!result.isError) {
+    recordSpend(price);
+  }
+
+  return result;
+}