@xlmtools/cli 0.1.2 → 0.2.0

package/src/cli.ts

@@ -1,245 +0,0 @@
-#!/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 { apiFetch } from "./lib/api-fetch.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`);
-  }
-
-  // Route through apiFetch so the X-XLMTools-Client header (and any
-  // future cross-cutting concerns like retries / user-agent) are
-  // applied consistently with the MCP tools. apiFetch detects the
-  // full-URL form and passes it straight through.
-  const res = await apiFetch(config, 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

@@ -1,90 +0,0 @@
-#!/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

@@ -1,78 +0,0 @@
-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;
-}

package/src/lib/cache.ts

@@ -1,66 +0,0 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { logger } from "./logger.js";
-
-const TTL_MS = 5 * 60 * 1000; // 5 minutes
-
-interface CacheEntry {
-  result: CallToolResult;
-  expires: number;
-}
-
-const store = new Map<string, CacheEntry>();
-
-/**
- * Wrap a tool call with response caching.
- * Identical tool+params within the TTL return the cached result
- * with no API call and no payment.
- */
-export async function withCache(
-  toolName: string,
-  params: Record<string, unknown>,
-  fn: () => Promise<CallToolResult>,
-): Promise<CallToolResult> {
-  const key = `${toolName}:${JSON.stringify(params)}`;
-
-  const cached = store.get(key);
-  if (cached && Date.now() < cached.expires) {
-    logger.debug({ toolName }, "cache hit");
-
-    const original = cached.result;
-    if (original.content[0]?.type === "text") {
-      // Strip the "---\nPayment: ..." footer from cached text — no
-      // payment happened on this call, so the original tx hash would
-      // contradict the [cached — no charge] prefix.
-      const stripped = original.content[0].text.replace(
-        /\n---\nPayment: .*$/s,
-        "",
-      );
-      return {
-        ...original,
-        content: [
-          {
-            type: "text" as const,
-            text: `[cached — no charge]\n\n${stripped}`,
-          },
-        ],
-      };
-    }
-    return original;
-  }
-
-  const result = await fn();
-
-  if (!result.isError) {
-    store.set(key, { result, expires: Date.now() + TTL_MS });
-  }
-
-  // Evict expired entries periodically
-  if (store.size > 50) {
-    const now = Date.now();
-    for (const [k, v] of store) {
-      if (now >= v.expires) store.delete(k);
-    }
-  }
-
-  return result;
-}

package/src/lib/config.ts

@@ -1,18 +0,0 @@
-export const TOOL_PRICES: Record<string, string> = {
-  search:     "0.003",
-  research:   "0.010",
-
-  youtube:    "0.002",
-  screenshot: "0.010",
-  scrape:     "0.002",
-  image:      "0.040",
-  stocks:     "0.001",
-};
-
-export const FREE_TOOLS = new Set([
-  "crypto", "weather", "domain", "wallet", "tools",
-  // Stellar-native tools (free — Horizon + StellarExpert + Reflector are public APIs)
-  "dex-orderbook", "dex-candles", "dex-trades",
-  "swap-quote", "stellar-asset", "stellar-account",
-  "stellar-pools", "oracle-price",
-]);

package/src/lib/format.ts

@@ -1,51 +0,0 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-
-export interface ReceiptInfo {
-  tx_hash: string;
-  amount: string;
-  currency: string;
-  network: string;
-}
-
-function formatReceipt(receipt: ReceiptInfo): string {
-  const hashShort = receipt.tx_hash.length > 12
-    ? receipt.tx_hash.slice(0, 12) + "..."
-    : receipt.tx_hash;
-  const network = receipt.network === "stellar:testnet" ? "stellar testnet" : receipt.network;
-  return `\n---\nPayment: $${receipt.amount} ${receipt.currency} \u00b7 tx/${hashShort} \u00b7 ${network}`;
-}
-
-export function ok(data: unknown): CallToolResult {
-  return {
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    isError: false,
-  };
-}
-
-/**
- * Format a paid tool response, appending a receipt line if present.
- * Strips the receipt from the data to avoid cluttering the JSON output,
- * then appends a human-readable payment line.
- */
-export function okPaid(data: Record<string, unknown>): CallToolResult {
-  const receipt = data.receipt as ReceiptInfo | undefined;
-  if (!receipt) {
-    return ok(data);
-  }
-
-  // Strip receipt from the JSON data — show it as a footer instead
-  const { receipt: _, ...rest } = data;
-  const text = JSON.stringify(rest, null, 2) + formatReceipt(receipt);
-
-  return {
-    content: [{ type: "text", text }],
-    isError: false,
-  };
-}
-
-export function err(message: string): CallToolResult {
-  return {
-    content: [{ type: "text", text: `Error: ${message}` }],
-    isError: true,
-  };
-}

package/src/lib/logger.ts

@@ -1,6 +0,0 @@
-import pino from "pino";
-
-export const logger = pino(
-  { name: "xlmtools", level: process.env.LOG_LEVEL ?? "info" },
-  pino.destination(2)
-);