@xlmtools/cli 0.1.0

package/dist/tools/budget.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { ok, err } from "../lib/format.js";
+import { setBudget, clearBudget, getStatus } from "../lib/budget.js";
+import { logger } from "../lib/logger.js";
+export function registerBudgetTool(server) {
+    server.registerTool("budget", {
+        title: "Session Budget",
+        description: "Set, check, or clear a spending limit for this session. " +
+            "The budget resets when the MCP server restarts. " +
+            "Cached responses do not count against the budget.",
+        inputSchema: z.object({
+            action: z
+                .enum(["set", "check", "clear"])
+                .describe("Action: set a limit, check status, or clear limit"),
+            amount: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Budget amount in USD (required for 'set')"),
+        }),
+    }, async ({ action, amount }) => {
+        logger.debug({ action, amount }, "budget tool invoked");
+        switch (action) {
+            case "set": {
+                if (amount === undefined) {
+                    return err("Amount is required for 'set'. Example: budget set 5.00");
+                }
+                setBudget(amount);
+                return ok({
+                    message: `Budget set to $${amount.toFixed(2)} for this session.`,
+                    ...getStatus(),
+                });
+            }
+            case "check": {
+                const status = getStatus();
+                if (status.max === null) {
+                    return ok({
+                        message: "No budget limit set. All tool calls will be charged normally.",
+                        ...status,
+                    });
+                }
+                return ok({
+                    message: `$${status.remaining?.toFixed(3)} remaining of $${status.max.toFixed(2)} budget.`,
+                    ...status,
+                });
+            }
+            case "clear": {
+                clearBudget();
+                return ok({
+                    message: "Budget limit cleared. All tool calls will be charged normally.",
+                    ...getStatus(),
+                });
+            }
+        }
+    });
+}

package/dist/tools/card.js

@@ -0,0 +1,51 @@
+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 registerCardTool(server) {
+    server.registerTool("card", {
+        title: "Virtual Card",
+        description: `Issue a virtual Mastercard for agent spending. Card is funded from your XLMTools USDC balance.
+Cost: $10 flat card creation fee + load amount + 3.5% processing.
+IMPORTANT: Card details are shown ONCE and not stored.
+MVP: ASGCard API integration pending — add @asgcard/sdk and ASGCARD_STELLAR_KEY to enable real cards.`,
+        inputSchema: z.object({
+            amount: z
+                .number()
+                .min(5)
+                .max(1000)
+                .default(20)
+                .describe("Amount to load in USD ($5-$1000)"),
+            name: z
+                .string()
+                .default("AI AGENT")
+                .describe("Name on card"),
+            email: z
+                .string()
+                .email()
+                .default("agent@xlmtools.dev")
+                .describe("Email for registration"),
+        }),
+    }, async ({ amount, name, email }) => {
+        logger.debug({ amount, name, email }, "card tool invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/card`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ amount, nameOnCard: name, email }),
+            });
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Card API error ${res.status}: ${body}`);
+            }
+            const data = await res.json();
+            const totalCharge = (10 + amount + amount * 0.035).toFixed(3);
+            return ok({ ...data, total_charged_usdc: totalCharge });
+        }
+        catch (e) {
+            logger.error({ err: e }, "card tool error");
+            return err(String(e));
+        }
+    });
+}

package/dist/tools/crypto.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+export function registerCryptoTool(server) {
+    server.registerTool("crypto", {
+        title: "Crypto Prices",
+        description: "Get real-time cryptocurrency prices, market caps, and 24h changes. Free.", inputSchema: z.object({
+            ids: z.string().describe("Comma-separated coin IDs (e.g. bitcoin,ethereum,stellar)"),
+            vs_currency: z.string().default("usd").describe("Quote currency (e.g. usd, eur)"),
+        }),
+    }, async ({ ids, vs_currency }) => {
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/crypto?ids=${encodeURIComponent(ids)}&vs_currency=${vs_currency}`);
+            if (!res.ok)
+                return err(`Crypto API error: ${res.status}`);
+            return ok(await res.json());
+        }
+        catch (e) {
+            return err(String(e));
+        }
+    });
+}

package/dist/tools/dex-candles.js

@@ -0,0 +1,47 @@
+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 registerDexCandlesTool(server) {
+    server.registerTool("dex-candles", {
+        title: "Stellar DEX Price Candles",
+        description: `Get OHLCV candlestick price data for any Stellar asset pair.\n` +
+            `Resolutions: 1m, 5m, 15m, 1h, 1d, 1w.\n` +
+            `Examples: "XLM/USDC" at "1h", "USDC/EURC" at "1d".\nFree.`, inputSchema: z.object({
+            pair: z
+                .string()
+                .describe('Asset pair (e.g. "XLM/USDC")'),
+            resolution: z
+                .enum(["1m", "5m", "15m", "1h", "1d", "1w"])
+                .default("1h")
+                .describe("Candle interval"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(20)
+                .describe("Number of candles (1-200)"),
+        }),
+    }, async ({ pair, resolution, limit }) => {
+        logger.debug({ pair, resolution, limit }, "dex-candles invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const params = new URLSearchParams({
+                pair,
+                resolution,
+                limit: String(limit),
+            });
+            const res = await fetch(`${config.apiUrl}/dex-candles?${params}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Candles error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "dex-candles error");
+            return err(`Candles failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/dex-orderbook.js

@@ -0,0 +1,38 @@
+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 registerDexOrderbookTool(server) {
+    server.registerTool("dex-orderbook", {
+        title: "Stellar DEX Orderbook",
+        description: `View the live orderbook for any Stellar asset pair. Shows bids, asks, and spread.\n` +
+            `Use pairs like "XLM/USDC", "USDC/EURC", or "CODE:ISSUER/XLM".\n` +
+            `Well-known assets: XLM, USDC, EURC, AQUA, yUSDC, BLND, SHX.\nFree.`, inputSchema: z.object({
+            pair: z
+                .string()
+                .describe('Asset pair (e.g. "XLM/USDC", "USDC/EURC")'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(10)
+                .describe("Number of price levels per side (1-200)"),
+        }),
+    }, async ({ pair, limit }) => {
+        logger.debug({ pair, limit }, "dex-orderbook invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/dex-orderbook?pair=${encodeURIComponent(pair)}&limit=${limit}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Orderbook error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "dex-orderbook error");
+            return err(`Orderbook failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/dex-trades.js

@@ -0,0 +1,46 @@
+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 registerDexTradesTool(server) {
+    server.registerTool("dex-trades", {
+        title: "Stellar DEX Trades",
+        description: `Get recent trades for any Stellar asset pair.\n` +
+            `Filter by trade type: "all", "orderbook", or "liquidity_pool".\nFree.`, inputSchema: z.object({
+            pair: z
+                .string()
+                .describe('Asset pair (e.g. "XLM/USDC")'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(10)
+                .describe("Number of trades (1-200)"),
+            trade_type: z
+                .enum(["all", "orderbook", "liquidity_pool"])
+                .default("all")
+                .describe("Filter by trade source"),
+        }),
+    }, async ({ pair, limit, trade_type }) => {
+        logger.debug({ pair, limit, trade_type }, "dex-trades invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const params = new URLSearchParams({
+                pair,
+                limit: String(limit),
+                trade_type,
+            });
+            const res = await fetch(`${config.apiUrl}/dex-trades?${params}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Trades error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "dex-trades error");
+            return err(`Trades failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/domain.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+export function registerDomainTool(server) {
+    server.registerTool("domain", {
+        title: "Domain Availability",
+        description: "Check if a domain name is available. Free.", inputSchema: z.object({
+            name: z.string().describe("Domain name to check (e.g. stellar-tools.xyz)"),
+        }),
+    }, async ({ name }) => {
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/domain?name=${encodeURIComponent(name)}`);
+            if (!res.ok)
+                return err(`Domain API error: ${res.status}`);
+            return ok(await res.json());
+        }
+        catch (e) {
+            return err(String(e));
+        }
+    });
+}

package/dist/tools/image.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 registerImageTool(server) {
+    server.registerTool("image", {
+        title: "AI Image Generation",
+        description: `Generate images from a text prompt using AI.\nCost: $${TOOL_PRICES.image} USDC per image (paid via Stellar MPP).`, inputSchema: z.object({
+            prompt: z
+                .string()
+                .describe("Text prompt describing the image to generate"),
+            size: z
+                .enum(["1024x1024", "1024x1792", "1792x1024"])
+                .default("1024x1024")
+                .describe("Output image dimensions"),
+        }),
+    }, async ({ prompt, size }) => {
+        logger.debug({ prompt, size }, "image tool invoked");
+        return withCache("image", { prompt, size }, () => withBudget("image", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const res = await fetch(`${config.apiUrl}/image`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ prompt, size }),
+                });
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`Image API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "image tool error");
+                return err(`Image generation failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/dist/tools/oracle-price.js

@@ -0,0 +1,36 @@
+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 registerOraclePriceTool(server) {
+    server.registerTool("oracle-price", {
+        title: "Stellar Oracle Price",
+        description: `Get real-time prices from Reflector, Stellar's decentralized oracle.\n` +
+            `Feeds: "crypto" (BTC, ETH, SOL, etc.), "fiat" (EUR, GBP, JPY), "dex" (Stellar DEX pairs).\n` +
+            `Prices are updated every 5 minutes via multi-node consensus.\nFree.`, inputSchema: z.object({
+            asset: z
+                .string()
+                .describe('Asset ticker (e.g. "BTC", "ETH", "EUR", "SOL")'),
+            feed: z
+                .enum(["crypto", "fiat", "dex"])
+                .default("crypto")
+                .describe("Oracle feed to query"),
+        }),
+    }, async ({ asset, feed }) => {
+        logger.debug({ asset, feed }, "oracle-price invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const params = new URLSearchParams({ asset, feed });
+            const res = await fetch(`${config.apiUrl}/oracle-price?${params}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Oracle error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "oracle-price error");
+            return err(`Oracle failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/reddit.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { loadOrCreateWallet } from "../lib/wallet.js";
+import { ok, err } from "../lib/format.js";
+import { logger } from "../lib/logger.js";
+import { TOOL_PRICES } from "../lib/config.js";
+export function registerRedditTool(server) {
+    server.registerTool("reddit", {
+        title: "Reddit Search",
+        description: `Search Reddit posts and comments in real-time.\nCost: $${TOOL_PRICES.reddit} USDC per query (paid via Stellar MPP).`,
+        inputSchema: z.object({
+            query: z.string().describe("Search query"),
+            subreddit: z
+                .string()
+                .optional()
+                .describe("Limit search to a specific subreddit (without r/ prefix)"),
+            sort: z
+                .enum(["relevance", "hot", "new", "top"])
+                .default("relevance")
+                .describe("Sort order for results"),
+        }),
+    }, async ({ query, subreddit, sort }) => {
+        logger.debug({ query, subreddit, sort }, "reddit tool invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const params = new URLSearchParams({ q: query, sort });
+            if (subreddit)
+                params.set("subreddit", subreddit);
+            const res = await fetch(`${config.apiUrl}/reddit?${params.toString()}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Reddit API error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "reddit tool error");
+            return err(`Reddit search failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/research.js

@@ -0,0 +1,39 @@
+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 registerResearchTool(server) {
+    server.registerTool("research", {
+        title: "Deep Research",
+        description: `Deep research on any topic — returns summarized, sourced results from multiple web pages.\nCost: $${TOOL_PRICES.research} USDC per query (paid via Stellar MPP).`, inputSchema: z.object({
+            query: z.string().describe("Research query"),
+            num_results: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(5)
+                .describe("Number of results to return (1-20)"),
+        }),
+    }, async ({ query, num_results }) => {
+        logger.debug({ query, num_results }, "research tool invoked");
+        return withCache("research", { query, num_results }, () => withBudget("research", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const res = await fetch(`${config.apiUrl}/research?q=${encodeURIComponent(query)}&num_results=${num_results}`);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`Research API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "research tool error");
+                return err(`Research failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/dist/tools/scrape.js

@@ -0,0 +1,32 @@
+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 registerScrapeTool(server) {
+    server.registerTool("scrape", {
+        title: "Web Scraper",
+        description: `Extract clean text content from any public URL.\nCost: $${TOOL_PRICES.scrape} USDC per scrape (paid via Stellar MPP).`, inputSchema: z.object({
+            url: z.string().url().describe("URL of the page to scrape"),
+        }),
+    }, async ({ url }) => {
+        logger.debug({ url }, "scrape tool invoked");
+        return withCache("scrape", { url }, () => withBudget("scrape", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const res = await fetch(`${config.apiUrl}/scrape?url=${encodeURIComponent(url)}`);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`Scrape API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "scrape tool error");
+                return err(`Scrape failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/dist/tools/screenshot.js

@@ -0,0 +1,37 @@
+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 registerScreenshotTool(server) {
+    server.registerTool("screenshot", {
+        title: "Web Screenshot",
+        description: `Capture a screenshot of any public URL and return it as an image.\nCost: $${TOOL_PRICES.screenshot} USDC per screenshot (paid via Stellar MPP).`, inputSchema: z.object({
+            url: z.string().url().describe("URL of the page to screenshot"),
+            format: z
+                .enum(["png", "jpg", "webp"])
+                .default("png")
+                .describe("Image format for the screenshot"),
+        }),
+    }, async ({ url, format }) => {
+        logger.debug({ url, format }, "screenshot tool invoked");
+        return withCache("screenshot", { url, format }, () => withBudget("screenshot", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const params = new URLSearchParams({ url, format });
+                const res = await fetch(`${config.apiUrl}/screenshot?${params.toString()}`);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`Screenshot API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "screenshot tool error");
+                return err(`Screenshot failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/dist/tools/search.js

@@ -0,0 +1,39 @@
+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 registerSearchTool(server) {
+    server.registerTool("search", {
+        title: "Web Search",
+        description: `Search the web and news in real-time. Returns results with source URLs.\nCost: $${TOOL_PRICES.search} USDC per search (paid via Stellar MPP).`, inputSchema: z.object({
+            query: z.string().describe("Search query"),
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(10)
+                .describe("Number of results (1-20)"),
+        }),
+    }, async ({ query, count }) => {
+        logger.debug({ query, count }, "search tool invoked");
+        return withCache("search", { query, count }, () => withBudget("search", async () => {
+            try {
+                const config = loadOrCreateWallet();
+                const res = await fetch(`${config.apiUrl}/search?q=${encodeURIComponent(query)}&count=${count}`);
+                if (!res.ok) {
+                    const body = await res.text();
+                    return err(`Search API error ${res.status}: ${body}`);
+                }
+                return okPaid(await res.json());
+            }
+            catch (e) {
+                logger.error({ err: e }, "search tool error");
+                return err(`Search failed: ${String(e)}`);
+            }
+        }));
+    });
+}

package/dist/tools/stellar-account.js

@@ -0,0 +1,30 @@
+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 registerStellarAccountTool(server) {
+    server.registerTool("stellar-account", {
+        title: "Stellar Account Lookup",
+        description: `Look up any Stellar account: balances, trustlines, signers, and status.\n` +
+            `Provide a Stellar public key (starts with G, 56 characters).\nFree.`, inputSchema: z.object({
+            address: z
+                .string()
+                .describe("Stellar public key (G-address)"),
+        }),
+    }, async ({ address }) => {
+        logger.debug({ address }, "stellar-account invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/stellar-account?address=${encodeURIComponent(address)}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Account lookup error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "stellar-account error");
+            return err(`Account lookup failed: ${String(e)}`);
+        }
+    });
+}

package/dist/tools/stellar-asset.js

@@ -0,0 +1,31 @@
+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 registerStellarAssetTool(server) {
+    server.registerTool("stellar-asset", {
+        title: "Stellar Asset Info",
+        description: `Look up any Stellar asset: supply, trustlines, rating, issuer org, and more.\n` +
+            `Combines on-chain data (Horizon) with analytics (StellarExpert).\n` +
+            `Examples: "USDC", "AQUA", "yUSDC", or "CODE:ISSUER".\nFree.`, inputSchema: z.object({
+            asset: z
+                .string()
+                .describe('Asset to look up (e.g. "USDC", "XLM", "AQUA", "CODE:ISSUER")'),
+        }),
+    }, async ({ asset }) => {
+        logger.debug({ asset }, "stellar-asset invoked");
+        try {
+            const config = loadOrCreateWallet();
+            const res = await fetch(`${config.apiUrl}/stellar-asset?asset=${encodeURIComponent(asset)}`);
+            if (!res.ok) {
+                const body = await res.text();
+                return err(`Asset lookup error ${res.status}: ${body}`);
+            }
+            return ok(await res.json());
+        }
+        catch (e) {
+            logger.error({ err: e }, "stellar-asset error");
+            return err(`Asset lookup failed: ${String(e)}`);
+        }
+    });
+}