@routedock/mcp-server 0.2.1 → 0.2.2

package/README.md

@@ -2,6 +2,10 @@
 
 Model Context Protocol (MCP) server for RouteDock Stellar payments. Exposes RouteDock's payment functionality as standardized tools that LLM agents can use directly.
 
+## Requirements
+
+Node.js **22 or newer**, matching the supported runtime of all RouteDock npm packages.
+
 ## Overview
 
 This MCP server implements the thesis that base payment infrastructure should be built for machines, not humans. Instead of requiring every LLM agent to implement the full RouteDock SDK, agents can simply connect to this MCP server and use standardized tools:
@@ -36,7 +40,7 @@ Create a `.env` file (e.g., `~/.routedock/.env`):
 ```bash
 # Required
 STELLAR_SECRET="SDU5..."  # Use a dedicated low-balance testnet key for safety
-STELLAR_NETWORK="testnet"  # or "mainnet"
+STELLAR_NETWORK="testnet"  # "testnet" (default) or "mainnet" (aliases: "pubnet", "public")
 ROUTEDOCK_DAILY_CAP="1.00" # Required: Maximum daily spend in USDC
 
 # Optional (for session mode)
@@ -56,7 +60,9 @@ Pay for a single data request from a RouteDock provider. Automatically selects t
 
 **Parameters:**
 - `url` (required): Full URL of the provider endpoint
-- `max_amount` (required): Maximum USDC amount to pay
+- `max_amount` (required): Maximum USDC amount to pay, as a decimal string such as `"0.01"`: a positive
+  number with at most 7 decimal places and no currency symbol. Anything else (missing, `"$0.01"`, `"0"`,
+  a JSON number) is rejected before the provider is contacted.
 - `preferred_mode` (optional): Preferred payment mode (`x402`, `mpp-charge`, `mpp-session`)
 
 **Returns:** Payment result with mode, amount, transaction hash, and response data
@@ -69,10 +75,15 @@ check against the provider's `min_deposit`, not a fund transfer. Pass the return
 `stream_session` and `close_session` — the channel's collateral cannot be settled otherwise.
 
 **Parameters:**
-- `url` (required): Base URL of the provider
+- `url` (required): The provider's streaming endpoint, e.g. `https://api-b.routedock.xyz/stream/orderbook`.
+  Vouchers and the closing `DELETE` are sent to this exact URL. A bare origin such as
+  `https://api-b.routedock.xyz` is also accepted: the server reads the provider's
+  `/.well-known/routedock.json` and uses `endpoints.stream`, or the only endpoint if there is just one.
+  The endpoint must be `GET` and on the same origin. If none qualifies, the call fails without opening
+  a session and lists the manifest's endpoints so you can retry with a full URL.
 - `initial_deposit` (optional): Amount in USDC you intend the channel to be funded with
 
-**Returns:** `channel_id` and open transaction hash
+**Returns:** `channel_id`, open transaction hash, and `endpoint_url` (the URL the session streams from)
 
 ### stream_session
 
@@ -145,7 +156,7 @@ Once configured, you can ask Claude to:
 > "Check my Stellar balance"
 > "List providers that offer price data"
 > "Pay for data from https://api-a.routedock.xyz/price with a max of 0.01 USDC"
-> "Open a session with https://api-b.routedock.xyz for streaming orderbook data"
+> "Open a session with https://api-b.routedock.xyz/stream/orderbook for streaming orderbook data"
 > "Pull the next few messages from that session"
 > "Close the session and settle the channel"
 

package/dist/index.js

@@ -2,15 +2,14 @@
 
 // src/index.ts
 import { config as loadDotenv } from "dotenv";
-import path from "path";
-import os from "os";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { RouteDockClient, FileSpendStore } from "@routedock/routedock";
+import { RouteDockClient } from "@routedock/routedock";
+import { FileSpendStore } from "@routedock/routedock/node";
 import { createClient } from "@supabase/supabase-js";
 
 // src/tools.ts
@@ -47,7 +46,7 @@ var TOOLS = [
       properties: {
         url: {
           type: "string",
-          description: "The base URL of the provider (e.g., https://api-b.routedock.xyz)"
+          description: "The provider's streaming endpoint URL (e.g., https://api-b.routedock.xyz/stream/orderbook). Vouchers and the closing DELETE go to this exact URL. A bare origin (e.g., https://api-b.routedock.xyz) is also accepted and resolved to the provider's streaming endpoint from its /.well-known/routedock.json manifest."
         },
         initial_deposit: {
           type: "string",
@@ -131,6 +130,8 @@ var TOOLS = [
 ];
 
 // src/handlers.ts
+import { usdcToStroops } from "@routedock/routedock";
+import { HORIZON_URLS } from "@routedock/routedock/network";
 import { Keypair, Horizon } from "@stellar/stellar-sdk";
 function ok(payload) {
   return {
@@ -143,15 +144,30 @@ function err(message) {
     isError: true
   };
 }
+function parseUsdc(amount) {
+  if (typeof amount !== "string") return null;
+  try {
+    return usdcToStroops(amount);
+  } catch {
+    return null;
+  }
+}
 async function handlePayForData(args, deps2) {
   const { url, max_amount, preferred_mode } = args;
   const { client: client2 } = deps2;
+  const maxStroops = parseUsdc(max_amount);
+  if (maxStroops === null || maxStroops === 0n) {
+    return err(
+      `max_amount must be a positive USDC amount as a decimal string with at most 7 decimal places, e.g. "0.01" (received ${JSON.stringify(max_amount) ?? "nothing"})`
+    );
+  }
   const modeOptions = preferred_mode ? { forceMode: preferred_mode } : void 0;
   const estimate = await client2.estimateCost(url, modeOptions);
-  if (estimate.amount === void 0 || isNaN(parseFloat(estimate.amount))) {
+  const priceStroops = parseUsdc(estimate.amount);
+  if (priceStroops === null) {
     return err("Provider returned an undefined or invalid price");
   }
-  if (parseFloat(estimate.amount) > parseFloat(max_amount)) {
+  if (priceStroops > maxStroops) {
     return err(
       `Provider cost ${estimate.amount} ${estimate.asset} exceeds max_amount ${max_amount} USDC`
     );
@@ -166,18 +182,64 @@ async function handlePayForData(args, deps2) {
     data: result.data
   });
 }
+function resolveSessionEndpoint(origin, manifest) {
+  const raw = manifest?.endpoints;
+  const endpoints = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const entries = Object.entries(endpoints);
+  const listing = entries.length > 0 ? entries.map(([name2, e]) => `${name2}: ${String(e?.method)} ${String(e?.path)}`).join(", ") : "(none)";
+  const fail = (reason) => ({
+    error: `Could not resolve a streaming endpoint for ${origin}: ${reason}. Endpoints in its manifest: ${listing}. Call open_session again with the full endpoint URL (e.g. ${origin}/stream/orderbook).`
+  });
+  let chosen;
+  if (Object.hasOwn(endpoints, "stream")) {
+    chosen = ["stream", endpoints.stream];
+  } else if (entries.length === 1) {
+    chosen = entries[0];
+  }
+  if (!chosen) {
+    return fail(
+      entries.length === 0 ? "the manifest lists no endpoints" : `the manifest has no "stream" endpoint and ${entries.length} others to choose from`
+    );
+  }
+  const [name, endpoint] = chosen;
+  const method = typeof endpoint?.method === "string" ? endpoint.method.toUpperCase() : "";
+  if (method !== "GET") {
+    return fail(`endpoint "${name}" uses method ${String(endpoint?.method)}, but sessions stream with GET`);
+  }
+  if (typeof endpoint.path !== "string") {
+    return fail(`endpoint "${name}" has no path`);
+  }
+  let resolved;
+  try {
+    resolved = new URL(endpoint.path, origin);
+  } catch {
+    return fail(`endpoint "${name}" has an invalid path`);
+  }
+  if (resolved.origin !== origin) {
+    return fail(`endpoint "${name}" points outside ${origin}`);
+  }
+  return { url: resolved.href };
+}
 async function handleOpenSession(args, deps2, commitmentSecret) {
   const { url, initial_deposit } = args;
   const { client: client2, openSessions: openSessions2, fetchManifest } = deps2;
   if (!commitmentSecret) {
     return err("COMMITMENT_SECRET environment variable is required for session mode");
   }
+  const parsed = new URL(url);
+  const origin = parsed.origin;
+  const isBareOrigin = parsed.pathname === "" || parsed.pathname === "/";
+  let cachedManifest;
+  const loadManifest = async () => {
+    if (cachedManifest === void 0) {
+      const fetcher = fetchManifest ?? ((u) => fetch(u));
+      const manifestResponse = await fetcher(`${origin}/.well-known/routedock.json`);
+      cachedManifest = await manifestResponse.json();
+    }
+    return cachedManifest;
+  };
   if (initial_deposit) {
-    const baseUrl = new URL(url).origin;
-    const manifestUrl = `${baseUrl}/.well-known/routedock.json`;
-    const fetcher = fetchManifest ?? ((u) => fetch(u));
-    const manifestResponse = await fetcher(manifestUrl);
-    const manifest = await manifestResponse.json();
+    const manifest = await loadManifest();
     const minDeposit = manifest?.pricing?.["mpp-session"]?.min_deposit ?? manifest?.pricing?.["mpp-session-ws"]?.min_deposit;
     if (minDeposit && parseFloat(initial_deposit) < parseFloat(minDeposit)) {
       return err(
@@ -185,12 +247,21 @@ async function handleOpenSession(args, deps2, commitmentSecret) {
       );
     }
   }
-  const session = await client2.openSession(url);
+  let endpointUrl = url;
+  if (isBareOrigin) {
+    const resolution = resolveSessionEndpoint(origin, await loadManifest());
+    if ("error" in resolution) {
+      return err(resolution.error);
+    }
+    endpointUrl = resolution.url;
+  }
+  const session = await client2.openSession(endpointUrl);
   openSessions2.set(session.channelId, session);
   return ok({
     success: true,
     channel_id: session.channelId,
     open_tx_hash: session.openTxHash,
+    endpoint_url: endpointUrl,
     message: "Session opened successfully. Use stream_session to pull data and close_session to settle and release the channel collateral."
   });
 }
@@ -267,10 +338,6 @@ async function handleCloseSession(args, deps2) {
     vouchers_issued: result.vouchersIssued
   });
 }
-var HORIZON_URLS = {
-  mainnet: "https://horizon.stellar.org",
-  testnet: "https://horizon-testnet.stellar.org"
-};
 function normalizeBalances(balances) {
   return balances.map((b) => ({
     asset_type: b.asset_type,
@@ -351,6 +418,249 @@ async function handleListProviders(args, deps2) {
   });
 }
 
+// src/env.ts
+import path from "path";
+import os from "os";
+
+// package.json
+var package_default = {
+  name: "@routedock/mcp-server",
+  version: "0.2.2",
+  description: "MCP server for RouteDock Stellar payments - exposes payment tools to LLM agents",
+  license: "MIT",
+  homepage: "https://github.com/winsznx/routedock/tree/main/packages/mcp-server#readme",
+  bugs: {
+    url: "https://github.com/winsznx/routedock/issues"
+  },
+  publishConfig: {
+    provenance: true
+  },
+  repository: {
+    type: "git",
+    url: "https://github.com/winsznx/routedock.git",
+    directory: "packages/mcp-server"
+  },
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  files: [
+    "dist",
+    "README.md"
+  ],
+  bin: {
+    "routedock-mcp-server": "dist/index.js"
+  },
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    typecheck: "tsc --noEmit",
+    test: 'tsx --experimental-test-module-mocks --test "src/**/*.test.ts"',
+    start: "node dist/index.js"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@routedock/routedock": "workspace:^",
+    "@stellar/stellar-sdk": "^14.6.1",
+    "@supabase/supabase-js": "^2.47.0",
+    dotenv: "^17.4.2"
+  },
+  devDependencies: {
+    "@types/node": "^20.0.0",
+    tsup: "^8.0.0",
+    tsx: "^4.22.3",
+    typescript: "^5.4.5"
+  },
+  engines: {
+    node: ">=22"
+  },
+  keywords: [
+    "stellar",
+    "soroban",
+    "usdc",
+    "x402",
+    "mpp",
+    "payments",
+    "ai-agents",
+    "mcp"
+  ]
+};
+
+// src/env.ts
+var SERVER_NAME = "@routedock/mcp-server";
+var SERVER_VERSION = package_default.version;
+function validateStellarNetwork(networkInput, warn = console.warn) {
+  if (!networkInput || networkInput.trim() === "") {
+    return "testnet";
+  }
+  const normalized = networkInput.trim().toLowerCase();
+  if (normalized === "testnet") {
+    return "testnet";
+  }
+  if (normalized === "mainnet") {
+    return "mainnet";
+  }
+  if (normalized === "pubnet" || normalized === "public") {
+    warn(`WARNING: STELLAR_NETWORK='${networkInput}' is an alias for 'mainnet'. Using 'mainnet'.`);
+    return "mainnet";
+  }
+  throw new Error(
+    `Invalid STELLAR_NETWORK "${networkInput}". Allowed values: testnet, mainnet (or pubnet/public as alias for mainnet).`
+  );
+}
+function parseEnv(env = process.env, options) {
+  const warn = options?.warn ?? console.warn;
+  if (env.SUPABASE_SERVICE_KEY) {
+    warn(
+      "WARNING: Using SUPABASE_SERVICE_KEY bypasses RLS. Use an anon key for list_providers (anon + public_read_providers RLS is sufficient)."
+    );
+  }
+  const stellarSecret = env.STELLAR_SECRET || env.ROUTEDOCK_WALLET_SECRET;
+  if (!stellarSecret) {
+    throw new Error("STELLAR_SECRET or ROUTEDOCK_WALLET_SECRET environment variable is required");
+  }
+  const routedockDailyCap = env.ROUTEDOCK_DAILY_CAP;
+  if (!routedockDailyCap) {
+    throw new Error("ROUTEDOCK_DAILY_CAP environment variable is required to prevent unbounded spending");
+  }
+  const stellarNetwork = validateStellarNetwork(env.STELLAR_NETWORK, warn);
+  const commitmentSecret = env.COMMITMENT_SECRET;
+  const supabaseUrl = env.SUPABASE_URL;
+  const supabaseKey = env.SUPABASE_KEY || env.SUPABASE_SERVICE_KEY;
+  const spendStorePath2 = env.ROUTEDOCK_SPEND_STORE_PATH || path.join(os.homedir(), ".routedock", "spend.json");
+  return {
+    stellarSecret,
+    stellarNetwork,
+    commitmentSecret,
+    supabaseUrl,
+    supabaseKey,
+    routedockDailyCap,
+    spendStorePath: spendStorePath2
+  };
+}
+
+// src/shutdown.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
+async function closeAllSessions(openSessions2, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  const logError = options.logError ?? console.error;
+  const logInfo = options.logInfo ?? console.error;
+  const entries = Array.from(openSessions2.entries());
+  if (entries.length === 0) {
+    return { closed: 0, failed: 0, timedOut: 0, results: [] };
+  }
+  logInfo(`[mcp-server] Closing ${entries.length} active session(s)...`);
+  const trackers = entries.map(([channelId, session]) => ({
+    channelId,
+    session,
+    status: "pending",
+    error: void 0
+  }));
+  const closePromises = trackers.map(async (tracker) => {
+    try {
+      await tracker.session.close();
+      tracker.status = "closed";
+      openSessions2.delete(tracker.channelId);
+      logInfo(`[mcp-server] Successfully closed session ${tracker.channelId}`);
+    } catch (err2) {
+      tracker.status = "error";
+      tracker.error = err2;
+      openSessions2.delete(tracker.channelId);
+      logError(`[mcp-server] Failed to close session ${tracker.channelId}:`, err2);
+    }
+  });
+  let timer;
+  const timeoutPromise = new Promise((resolve) => {
+    timer = setTimeout(() => resolve("TIMEOUT"), timeoutMs);
+  });
+  const allFinishedPromise = Promise.all(closePromises).then(() => "DONE");
+  const outcome = await Promise.race([allFinishedPromise, timeoutPromise]);
+  if (timer) {
+    clearTimeout(timer);
+  }
+  if (outcome === "TIMEOUT") {
+    for (const tracker of trackers) {
+      if (tracker.status === "pending") {
+        tracker.status = "timeout";
+        openSessions2.delete(tracker.channelId);
+        logError(
+          `[mcp-server] Timed out waiting to close session ${tracker.channelId} after ${timeoutMs}ms`
+        );
+      }
+    }
+  }
+  const results = trackers.map((t) => {
+    const status = t.status === "pending" ? "timeout" : t.status;
+    return {
+      channelId: t.channelId,
+      status,
+      error: t.error
+    };
+  });
+  const closed = results.filter((r) => r.status === "closed").length;
+  const failed = results.filter((r) => r.status === "error").length;
+  const timedOut = results.filter((r) => r.status === "timeout").length;
+  return { closed, failed, timedOut, results };
+}
+function setupShutdownHandlers(options) {
+  const {
+    openSessions: openSessions2,
+    transport,
+    stdin = process.stdin,
+    processObj = process,
+    timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS,
+    logError = console.error,
+    logInfo = console.error,
+    onExit = (code) => {
+      process.exit(code);
+    }
+  } = options;
+  let shutdownPromise = null;
+  const handleShutdown = (reason) => {
+    if (shutdownPromise) {
+      return shutdownPromise;
+    }
+    logInfo(`[mcp-server] Graceful shutdown initiated (${reason})`);
+    shutdownPromise = (async () => {
+      try {
+        const summary = await closeAllSessions(openSessions2, {
+          timeoutMs,
+          logError,
+          logInfo
+        });
+        const exitCode = summary.failed > 0 || summary.timedOut > 0 ? 1 : 0;
+        onExit(exitCode);
+        return summary;
+      } catch (err2) {
+        logError("[mcp-server] Unexpected error during shutdown:", err2);
+        onExit(1);
+        throw err2;
+      }
+    })();
+    return shutdownPromise;
+  };
+  processObj.once("SIGINT", () => {
+    void handleShutdown("SIGINT");
+  });
+  processObj.once("SIGTERM", () => {
+    void handleShutdown("SIGTERM");
+  });
+  if (stdin && typeof stdin.once === "function") {
+    stdin.once("end", () => {
+      void handleShutdown("stdin end");
+    });
+  }
+  if (transport) {
+    const prevOnClose = transport.onclose;
+    transport.onclose = () => {
+      if (typeof prevOnClose === "function") {
+        prevOnClose();
+      }
+      void handleShutdown("transport onclose");
+    };
+  }
+  return (reason = "manual") => handleShutdown(reason);
+}
+
 // src/index.ts
 var envPath = process.env.ROUTEDOCK_ENV_FILE;
 if (envPath) {
@@ -358,24 +668,23 @@ if (envPath) {
 } else {
   loadDotenv();
 }
-var STELLAR_SECRET = process.env.STELLAR_SECRET || process.env.ROUTEDOCK_WALLET_SECRET;
-var STELLAR_NETWORK = process.env.STELLAR_NETWORK || "testnet";
-var COMMITMENT_SECRET = process.env.COMMITMENT_SECRET;
-var SUPABASE_URL = process.env.SUPABASE_URL;
-var SUPABASE_KEY = process.env.SUPABASE_KEY || process.env.SUPABASE_SERVICE_KEY;
-if (process.env.SUPABASE_SERVICE_KEY) {
-  console.warn("WARNING: Using SUPABASE_SERVICE_KEY bypasses RLS. Use an anon key for list_providers (anon + public_read_providers RLS is sufficient).");
-}
-if (!STELLAR_SECRET) {
-  console.error("Error: STELLAR_SECRET or ROUTEDOCK_WALLET_SECRET environment variable is required");
+var config;
+try {
+  config = parseEnv(process.env);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
   process.exit(1);
 }
-var ROUTEDOCK_DAILY_CAP = process.env.ROUTEDOCK_DAILY_CAP;
-if (!ROUTEDOCK_DAILY_CAP) {
-  console.error("Error: ROUTEDOCK_DAILY_CAP environment variable is required to prevent unbounded spending");
-  process.exit(1);
-}
-var spendStorePath = process.env.ROUTEDOCK_SPEND_STORE_PATH || path.join(os.homedir(), ".routedock", "spend.json");
+var {
+  stellarSecret: STELLAR_SECRET,
+  stellarNetwork: STELLAR_NETWORK,
+  commitmentSecret: COMMITMENT_SECRET,
+  supabaseUrl: SUPABASE_URL,
+  supabaseKey: SUPABASE_KEY,
+  routedockDailyCap: ROUTEDOCK_DAILY_CAP,
+  spendStorePath
+} = config;
 var client = new RouteDockClient({
   wallet: STELLAR_SECRET,
   network: STELLAR_NETWORK,
@@ -397,8 +706,8 @@ var deps = {
 };
 var server = new Server(
   {
-    name: "@routedock/mcp-server",
-    version: "0.1.0"
+    name: SERVER_NAME,
+    version: SERVER_VERSION
   },
   {
     capabilities: {
@@ -445,6 +754,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 async function main() {
   const transport = new StdioServerTransport();
+  setupShutdownHandlers({ openSessions, transport });
   await server.connect(transport);
   console.error("@routedock/mcp-server running on stdio");
 }

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@routedock/mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "MCP server for RouteDock Stellar payments - exposes payment tools to LLM agents",
   "license": "MIT",
+  "homepage": "https://github.com/winsznx/routedock/tree/main/packages/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/winsznx/routedock/issues"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/winsznx/routedock.git",
@@ -19,11 +26,11 @@
     "routedock-mcp-server": "dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@stellar/stellar-sdk": "^14.6.1",
     "@supabase/supabase-js": "^2.47.0",
     "dotenv": "^17.4.2",
-    "@routedock/routedock": "^0.3.0"
+    "@routedock/routedock": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -31,6 +38,19 @@
     "tsx": "^4.22.3",
     "typescript": "^5.4.5"
   },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "stellar",
+    "soroban",
+    "usdc",
+    "x402",
+    "mpp",
+    "payments",
+    "ai-agents",
+    "mcp"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",