@xlmtools/cli 0.1.2 → 0.2.0

package/src/lib/wallet.ts

@@ -1,143 +0,0 @@
-import {
-  Keypair,
-  Horizon,
-  TransactionBuilder,
-  Networks,
-  Operation,
-  Asset,
-} from "@stellar/stellar-sdk";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { logger } from "./logger.js";
-
-const CONFIG_DIR = join(homedir(), ".xlmtools");
-const CONFIG_PATH = join(CONFIG_DIR, "config.json");
-
-// Circle USDC issuer on Stellar testnet
-const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
-const HORIZON_TESTNET = "https://horizon-testnet.stellar.org";
-
-interface XLMToolsConfig {
-  stellarPrivateKey: string;
-  stellarPublicKey: string;
-  apiUrl: string;
-}
-
-/**
- * Auto-fund a new wallet on Stellar TESTNET only.
- * This uses the public friendbot (free testnet XLM) and adds a USDC
- * trustline so the account can receive payments. This function must
- * never be called on mainnet — friendbot does not exist there.
- */
-async function fundTestnetWallet(keypair: Keypair): Promise<boolean> {
-  // Safety: only run on testnet
-  const network = process.env.STELLAR_NETWORK ?? "testnet";
-  if (network !== "testnet") {
-    logger.info({ network }, "Skipping auto-fund — not on testnet");
-    return false;
-  }
-
-  const publicKey = keypair.publicKey();
-
-  // Step 1: Fund with friendbot
-  process.stderr.write("  Funding wallet with testnet XLM...");
-  try {
-    const res = await fetch(
-      `https://friendbot.stellar.org?addr=${publicKey}`,
-    );
-    if (!res.ok) {
-      process.stderr.write(" failed\n");
-      logger.warn({ status: res.status }, "Friendbot funding failed");
-      return false;
-    }
-    process.stderr.write(" done\n");
-  } catch (e) {
-    process.stderr.write(" failed (network error)\n");
-    logger.warn({ err: e }, "Friendbot request failed");
-    return false;
-  }
-
-  // Step 2: Add USDC trustline
-  process.stderr.write("  Adding USDC trustline...");
-  try {
-    const server = new Horizon.Server(HORIZON_TESTNET);
-    const account = await server.loadAccount(publicKey);
-    const usdcAsset = new Asset("USDC", USDC_ISSUER);
-
-    const tx = new TransactionBuilder(account, {
-      fee: "100",
-      networkPassphrase: Networks.TESTNET,
-    })
-      .addOperation(Operation.changeTrust({ asset: usdcAsset }))
-      .setTimeout(30)
-      .build();
-
-    tx.sign(keypair);
-    await server.submitTransaction(tx);
-    process.stderr.write(" done\n");
-  } catch (e) {
-    process.stderr.write(" failed\n");
-    logger.warn({ err: e }, "USDC trustline failed");
-    return false;
-  }
-
-  return true;
-}
-
-export function loadOrCreateWallet(): XLMToolsConfig {
-  if (existsSync(CONFIG_PATH)) {
-    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as XLMToolsConfig;
-  }
-
-  const keypair = Keypair.random();
-  const config: XLMToolsConfig = {
-    stellarPrivateKey: keypair.secret(),
-    stellarPublicKey: keypair.publicKey(),
-    apiUrl: process.env.XLMTOOLS_API_URL ?? "https://api.xlmtools.com",
-  };
-
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
-
-  process.stderr.write(
-    "\n" +
-      "XLMTools — First Run Setup (Stellar Testnet)\n" +
-      "─".repeat(44) + "\n\n" +
-      `  Wallet:  ${config.stellarPublicKey}\n` +
-      `  Network: Stellar Testnet\n\n`,
-  );
-
-  // Auto-fund on testnet (non-blocking — don't break startup if it fails)
-  fundTestnetWallet(keypair)
-    .then((funded) => {
-      if (funded) {
-        process.stderr.write(
-          "\n  Wallet funded and ready.\n" +
-            "  Get testnet USDC: https://faucet.circle.com\n" +
-            "  (paste your wallet address above)\n\n" +
-            "─".repeat(40) + "\n\n",
-        );
-      } else {
-        process.stderr.write(
-          "\n  Auto-funding failed. Fund manually:\n" +
-            "  1. https://lab.stellar.org/account/fund  (testnet XLM)\n" +
-            "  2. https://faucet.circle.com             (testnet USDC)\n\n" +
-            "─".repeat(40) + "\n\n",
-        );
-      }
-    })
-    .catch(() => {
-      // Silently handle — wallet is still created, just unfunded
-    });
-
-  logger.info(
-    { publicKey: config.stellarPublicKey },
-    "New Stellar wallet generated",
-  );
-  return config;
-}
-
-export function getKeypair(config: XLMToolsConfig): Keypair {
-  return Keypair.fromSecret(config.stellarPrivateKey);
-}

package/src/tools/budget.ts

@@ -1,67 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-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: McpServer): void {
-  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.coerce.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/src/tools/crypto.ts

@@ -1,26 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.js";
-import { ok, err } from "../lib/format.js";
-
-export function registerCryptoTool(server: McpServer): void {
-  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 apiFetch(config, `/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/src/tools/dex-candles.ts

@@ -1,53 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.js";
-import { ok, err } from "../lib/format.js";
-import { logger } from "../lib/logger.js";
-
-export function registerDexCandlesTool(server: McpServer): void {
-  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.coerce.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 apiFetch(config, `/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/src/tools/dex-orderbook.ts

@@ -1,47 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.js";
-import { ok, err } from "../lib/format.js";
-import { logger } from "../lib/logger.js";
-
-export function registerDexOrderbookTool(server: McpServer): void {
-  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.coerce.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 apiFetch(
-          config,
-          `/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/src/tools/dex-trades.ts

@@ -1,52 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.js";
-import { ok, err } from "../lib/format.js";
-import { logger } from "../lib/logger.js";
-
-export function registerDexTradesTool(server: McpServer): void {
-  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.coerce.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 apiFetch(config, `/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/src/tools/domain.ts

@@ -1,25 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.js";
-import { ok, err } from "../lib/format.js";
-
-export function registerDomainTool(server: McpServer): void {
-  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 apiFetch(config, `/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/src/tools/image.ts

@@ -1,50 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.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: McpServer): void {
-  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 apiFetch(config, `/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: unknown) {
-            logger.error({ err: e }, "image tool error");
-            return err(`Image generation failed: ${String(e)}`);
-          }
-        }),
-      );
-    },
-  );
-}

package/src/tools/oracle-price.ts

@@ -1,43 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.js";
-import { ok, err } from "../lib/format.js";
-import { logger } from "../lib/logger.js";
-
-export function registerOraclePriceTool(server: McpServer): void {
-  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 apiFetch(config, `/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/src/tools/research.ts

@@ -1,49 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.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: McpServer): void {
-  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.coerce.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 apiFetch(
-              config,
-              `/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: unknown) {
-            logger.error({ err: e }, "research tool error");
-            return err(`Research failed: ${String(e)}`);
-          }
-        }),
-      );
-    },
-  );
-}

package/src/tools/scrape.ts

@@ -1,43 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.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: McpServer): void {
-  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 apiFetch(
-              config,
-              `/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: unknown) {
-            logger.error({ err: e }, "scrape tool error");
-            return err(`Scrape failed: ${String(e)}`);
-          }
-        }),
-      );
-    },
-  );
-}

package/src/tools/screenshot.ts

@@ -1,48 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { loadOrCreateWallet } from "../lib/wallet.js";
-import { apiFetch } from "../lib/api-fetch.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: McpServer): void {
-  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 apiFetch(
-              config,
-              `/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: unknown) {
-            logger.error({ err: e }, "screenshot tool error");
-            return err(`Screenshot failed: ${String(e)}`);
-          }
-        }),
-      );
-    },
-  );
-}