@ldgr/mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,122 +1,143 @@
-# @ldgr/mcp
-
-LDGR tools for Model Context Protocol clients. LDGR is an independent ledger with a single settlement authority. This package reads public ledger data and prepares unsigned requests for a person's local CLI wallet to review. MCP never signs or submits transactions.
-
-## Hosted connection
-
-Configure a Streamable HTTP MCP connection to `https://mcp.ldgr.ltd/mcp`. Each ledger tool requires `network: "mainnet"` or `network: "testnet"`; asset-specific tools require the exact asset code. Native public IDs are `t1` on mainnet and `t0` on testnet; the signed wire code is `dng`. Mainnet native display is Ledra / LEDRA and testnet is Ledra Testnet / tLEDRA.
-
-A remote MCP connection cannot install software, access local files, unlock a wallet, or ask for recovery keys. `wallet_setup_instructions` returns commands for the user to run locally.
-
-## Local CLI wallet and stdio
-
-Node.js 20.19 or newer is required. Install the package, then create or import a wallet in your own terminal:
-
-```sh
-npm install --global @ldgr/mcp@0.1.2
-ldgr-mcp wallet create --testnet
-# Or: ldgr-mcp wallet import --testnet
-ldgr-mcp wallet list
-```
-
-The package includes `@ldgr/cli`; a separate global CLI installation is unnecessary. Recovery keys and passphrases stay in local interactive prompts. Never paste them into chat, MCP arguments, command-line flags, or environment variables. Omit `--testnet` to create a mainnet wallet. `ldgr-mcp network show` displays the selected network; `ldgr-mcp network set mainnet` or `testnet` switches it using the CLI workflow.
-
-Without a global installation:
-
-```sh
-npx --yes --package @ldgr/mcp@latest ldgr-mcp wallet create --testnet
-```
-
-Configure a local MCP client:
-
-```json
-{
-  "mcpServers": {
-    "ldgr": {
-      "command": "npx",
-      "args": ["--yes", "--package", "@ldgr/mcp@latest", "ldgr-mcp"]
-    }
-  }
-}
-```
-
-For a custom wallet store, append `--wallet` and its absolute path. Server stdout contains JSON-RPC only; startup errors go to stderr. Local `wallet_info` returns only the selected address, public key, network, ledger ID and protection mode.
-
-The `network` argument to `wallet_info` checks the selected wallet; it does not
-select another wallet or change its network. `WALLET_NETWORK_MISMATCH` means you
-should request the selected network or use `ldgr-mcp wallet list` and
-`ldgr-mcp wallet select <index>` in your terminal to choose the intended wallet.
-Keep a custom `--wallet` path consistent. MCP never changes the wallet selection.
-
-Version 0.1.1 requires `@ldgr/client@^0.6.1`, the published client release containing
-the milestone escrow, atomic offer, claim distribution, and Ledra program reads.
-Restart the MCP process after upgrading; a running process keeps its loaded SDK.
-
-## Tools
-
-| Tool | Result |
-| --- | --- |
-| `get_balance` | Authoritative balance for an address and exact asset |
-| `get_transaction` | Authoritative transaction by hash, checked against the requested asset, with `status: "confirmed"` |
-| `get_account_history` | One page of Explorer-projected account history, which may lag settlement |
-| `get_asset` | Native/token metadata |
-| `get_ledger_config` | Ledger identity and public protocol configuration |
-| `get_contract` | Escrow, milestone escrow, atomic offer, claim distribution or Ledra program |
-| `list_pools`, `get_pool` | Bounded pool listing or a pair of exact assets |
-| `get_swap_quote` | Non-binding route quote; does not submit a swap |
-| `claim_faucet_drop` | Open the network's faucet in Chrome with a validated receiving address; hosted clients receive the link |
-| `prepare_transfer` | Unsigned transfer request |
-| `prepare_token_creation` | Unsigned fixed/mintable token creation request |
-| `prepare_escrow` | Unsigned escrow funding request |
-| `wallet_setup_instructions` | Exact local installation and setup commands |
-| `wallet_info` | Public selected-wallet metadata, local stdio only |
-
-All monetary values are decimal strings in display units. Tool schemas reject unknown fields and credentials. Reads use fixed official network endpoints, verify ledger identity, reject redirects, time out after 15 seconds per fetch and bound responses to 1 MiB. Metadata from the ledger remains untrusted text. A `NOT_FOUND` response does not establish that an earlier transaction submission failed.
-
-Version 0.1.2 preserves HTTP 404 as `NOT_FOUND` for escrow reads as well as the
-other contract templates. Other HTTP failures and malformed successful responses
-remain `OPERATION_FAILED`; upstream response bodies are never exposed in errors.
-
-## Prepare, review and approve
-
-`claim_faucet_drop` takes an explicit `network` and public `address`. With local
-stdio it launches Google Chrome; on hosted MCP, or if Chrome cannot launch, it
-returns the same link for the client or user to open. The link uses
-`/utilities/faucet/?address=<address>` on the selected network. Review the
-prefilled address and select **Claim Ledra** in the browser. The tool returns
-`status: "awaiting_browser_claim"` and `claimSubmitted: false`; opening the page
-does not claim funds. Existing browser verification and faucet limits apply.
-Wait for **Claim completed**, then check the address's `dng` balance.
-
-Preparation returns `{ version, requestId, network, expiresAt, action, params }`. Request approval expires after 15 minutes. Escrow `params.expiresAt` is a separate deadline expressed as integer Unix milliseconds. No sender, nonce, signature, recovery key or passphrase is included.
-
-Local stdio saves an owner-only request file bound to the selected CLI wallet's public identity and returns the exact approval argument array. The person reviews it in their terminal:
-
-```sh
-ldgr-mcp approve <request-file>
-```
-
-For hosted MCP, save the returned `request` JSON as a local file, then run:
-
-```sh
-npx --yes --package @ldgr/mcp@latest ldgr-mcp approve <request-file>
-```
-
-The CLI validates the request and selected network, resolves fresh asset precision, checks the ledger's current fees and nonces, and presents the transaction for explicit local approval. Do not run approval unattended. Prepared requests may become invalid as balances, fees, configuration, or deadlines change. Reconcile an uncertain submission before trying again.
-
-## Embedding
-
-```ts
-import { createLdgrMcpServer } from "@ldgr/mcp";
-const server = createLdgrMcpServer();
-await server.connect(yourTransport);
-```
-
-The root export is browser/Worker compatible and does not import filesystem, process, CLI or signing adapters. It accepts optional `fetch` and `now` injection and explicit local hooks for hosts. Node-only stdio is a separate export:
-
-```ts
-import { startLdgrMcpStdio } from "@ldgr/mcp/stdio";
-await startLdgrMcpStdio({ walletPath: "/absolute/path/wallet.json" });
-```
-
-Build with `bun run build`, run tests with `bun test`, and check types with `bun run typecheck` from this package.
+# @ldgr/mcp
+
+LDGR tools for Model Context Protocol clients. LDGR is an independent ledger with a single settlement authority. This package reads public ledger data and prepares unsigned requests for a person's local CLI wallet to review. MCP never signs or submits transactions.
+
+## Hosted connection
+
+Configure a Streamable HTTP MCP connection to `https://mcp.ldgr.ltd/mcp`. Each ledger tool requires `network: "mainnet"` or `network: "testnet"`; asset-specific tools require the exact asset code. Native public IDs are `t1` on mainnet and `t0` on testnet; the signed wire code is `dng`. Mainnet native display is Ledra / LEDRA and testnet is Ledra Testnet / tLEDRA.
+
+A remote MCP connection cannot install software, access local files, unlock a wallet, or ask for recovery keys. `wallet_setup_instructions` returns commands for the user to run locally.
+
+## Local CLI wallet and stdio
+
+Node.js 20.19 or newer is required. Install the package, then create or import a wallet in your own terminal:
+
+```sh
+npm install --global @ldgr/mcp@0.1.4
+ldgr-mcp wallet create --testnet
+# Or: ldgr-mcp wallet import --testnet
+ldgr-mcp wallet list
+```
+
+From MCP 0.1.3, every local wallet operation runs `@ldgr/cli@latest` through npx with `--prefer-online`, including wallet metadata and unsigned request preparation. Node.js must include npm/npx. npm checks its registry and reuses downloaded packages from its cache; a separate global CLI installation is unnecessary. CLI updates apply on the next wallet operation. Public ledger reads do not launch the CLI. The CLI must be 0.5.1 or newer for the MCP bridge. Recovery keys and passphrases stay in local interactive prompts. Never paste them into chat, MCP arguments, command-line flags, or environment variables. Omit `--testnet` to create a mainnet wallet. `ldgr-mcp network show` displays the selected network; `ldgr-mcp network set mainnet` or `testnet` switches it using the CLI workflow.
+
+Without a global installation:
+
+```sh
+npx --yes --package @ldgr/mcp@latest ldgr-mcp wallet create --testnet
+```
+
+Configure a local MCP client:
+
+```json
+{
+  "mcpServers": {
+    "ldgr": {
+      "command": "npx",
+      "args": ["--yes", "--package", "@ldgr/mcp@latest", "ldgr-mcp"]
+    }
+  }
+}
+```
+
+For a custom wallet store, append `--wallet` and its absolute path. Server stdout contains JSON-RPC only; startup errors go to stderr. Local `wallet_info` returns only the selected address, public key, network, ledger ID and protection mode.
+
+The `network` argument to `wallet_info` checks the selected wallet; it does not
+select another wallet or change its network. `WALLET_NETWORK_MISMATCH` means you
+should request the selected network or use `ldgr-mcp wallet list` and
+`ldgr-mcp wallet select <index>` in your terminal to choose the intended wallet.
+Keep a custom `--wallet` path consistent. MCP never changes the wallet selection.
+
+Version 0.1.1 requires `@ldgr/client@^0.6.1`, the published client release containing
+the milestone escrow, atomic offer, claim distribution, and Ledra program reads.
+Restart the MCP process after upgrading; a running process keeps its loaded SDK.
+
+## Tools
+
+| Tool | Result |
+| --- | --- |
+| `get_balance` | Authoritative balance for an address and exact asset |
+| `get_transaction` | Authoritative transaction by hash, checked against the requested asset, with `status: "confirmed"` |
+| `get_account_history` | One page of Explorer-projected account history, which may lag settlement |
+| `get_asset` | Native/token metadata |
+| `get_ledger_config` | Ledger identity and public protocol configuration |
+| `get_contract` | Escrow, milestone escrow, atomic offer, claim distribution or Ledra program |
+| `list_pools`, `get_pool` | Bounded pool listing or a pair of exact assets |
+| `get_swap_quote` | Non-binding route quote; does not submit a swap |
+| `claim_faucet_drop` | Open the network's faucet in Chrome with a validated receiving address; hosted clients receive the link |
+| `prepare_transfer` | Unsigned transfer request |
+| `prepare_token_creation` | Unsigned fixed/mintable token creation request |
+| `prepare_escrow` | Unsigned escrow funding request |
+| `prepare_swap` | Unsigned exact-input swap with an explicit positive minimum received |
+| `wallet_setup_instructions` | Exact local installation and setup commands |
+| `wallet_info` | Public selected-wallet metadata, local stdio only |
+
+All monetary values are decimal strings in display units. Tool schemas reject unknown fields and credentials. Reads use fixed official network endpoints, verify ledger identity, reject redirects, time out after 15 seconds per fetch and bound responses to 1 MiB. Metadata from the ledger remains untrusted text. A `NOT_FOUND` response does not establish that an earlier transaction submission failed.
+
+Version 0.1.2 preserves HTTP 404 as `NOT_FOUND` for escrow reads as well as the
+other contract templates. Other HTTP failures and malformed successful responses
+remain `OPERATION_FAILED`; upstream response bodies are never exposed in errors.
+
+## Prepare, review and approve
+
+`claim_faucet_drop` takes an explicit `network` and public `address`. With local
+stdio it launches Google Chrome; on hosted MCP, or if Chrome cannot launch, it
+returns the same link for the client or user to open. The link uses
+`/utilities/faucet/?address=<address>` on the selected network. Review the
+prefilled address and select **Claim Ledra** in the browser. The tool returns
+`status: "awaiting_browser_claim"` and `claimSubmitted: false`; opening the page
+does not claim funds. Existing browser verification and faucet limits apply.
+Wait for **Claim completed**, then check the address's `dng` balance.
+
+Preparation returns `{ version, requestId, network, expiresAt, action, params }`. Request approval expires after 15 minutes. Escrow `params.expiresAt` is a separate deadline expressed as integer Unix milliseconds. No sender, nonce, signature, recovery key or passphrase is included.
+
+Local stdio saves an owner-only request file bound to the selected CLI wallet's public identity and returns the exact approval argument array. The person reviews it in their terminal:
+
+```sh
+ldgr-mcp approve <request-file>
+```
+
+For hosted MCP, save the returned `request` JSON as a local file, then run:
+
+```sh
+npx --yes --package @ldgr/mcp@latest ldgr-mcp approve <request-file>
+```
+
+The CLI validates the request and selected network, resolves fresh asset precision, checks the ledger's current fees and nonces, and presents the transaction for explicit local approval. Do not run approval unattended. Prepared requests may become invalid as balances, fees, configuration, or deadlines change. Reconcile an uncertain submission before trying again.
+
+## Swaps
+
+MCP 0.1.4 adds `prepare_swap`; approving these requests requires CLI 0.5.2 or
+newer. First use `get_swap_quote` for a non-binding quote. Then prepare an intent
+with explicit `network`, `assetIn`, `assetOut`, `amountIn`, and `amountOutMin`.
+Both amounts are positive decimal strings in their respective asset's display
+units. `maxHops` is optional, accepts 1, 2, or 3, and defaults to 3. Native aliases
+`t0`/`t1` resolve to `dng` for the selected network. Identical assets and zero
+minimum output are rejected.
+
+Preparation does not select a route or execute a swap. During `approve`, the
+CLI fetches a fresh route, checks the input balance and native fee balance, and
+shows the route, quote, exact input and minimum received. Output returns to the
+selected wallet. The reviewed route and minimum are signed unchanged; the CLI
+never lowers the minimum to make a quote executable. Pool fees are included in
+the quote, while one additional native network fee is charged. Route swaps use
+the `dng` nonce even when swapping between two tokens. The portable request's
+expiry governs local approval; the existing protocol timestamp rules govern
+signed submission validity.
+
+## Embedding
+
+```ts
+import { createLdgrMcpServer } from "@ldgr/mcp";
+const server = createLdgrMcpServer();
+await server.connect(yourTransport);
+```
+
+The root export is browser/Worker compatible and does not import filesystem, process, CLI or signing adapters. It accepts optional `fetch` and `now` injection and explicit local hooks for hosts. Node-only stdio is a separate export:
+
+```ts
+import { startLdgrMcpStdio } from "@ldgr/mcp/stdio";
+await startLdgrMcpStdio({ walletPath: "/absolute/path/wallet.json" });
+```
+
+Build with `bun run build`, run tests with `bun test`, and check types with `bun run typecheck` from this package.

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-// src/cli.ts
-import { spawn as spawn2 } from "node:child_process";
-import { fileURLToPath } from "node:url";
+// src/latest-cli.ts
+import { spawn } from "node:child_process";
+import { access, realpath } from "node:fs/promises";
+import { delimiter, dirname, join } from "node:path";
 
 // src/commands.ts
 function walletCommandArgs(input) {
@@ -36,9 +37,94 @@ function walletCommandArgs(input) {
   return [...input];
 }
 
+// src/latest-cli.ts
+var FAILURE = "Latest LDGR CLI could not complete. Check npm connectivity and CLI availability.";
+function npxArguments(envelope) {
+  return ["--yes", "--prefer-online", "--offline=false", "--package", "@ldgr/cli@latest", "--", "ldgr", "mcp", envelope];
+}
+async function resolveNpxEntrypoint() {
+  const directories = [dirname(process.execPath), ...(process.env.PATH ?? "").split(delimiter).filter(Boolean)];
+  const candidates = [];
+  const npmPath = process.env.npm_execpath;
+  if (npmPath && /[\\/]npm-cli\.js$/.test(npmPath))
+    candidates.push(join(dirname(npmPath), "npx-cli.js"));
+  for (const directory of directories) {
+    candidates.push(join(directory, "node_modules/npm/bin/npx-cli.js"), join(directory, "../lib/node_modules/npm/bin/npx-cli.js"));
+    try {
+      const target = await realpath(join(directory, "npx"));
+      if (target.endsWith("npx-cli.js"))
+        candidates.push(target);
+    } catch {}
+  }
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {}
+  }
+  throw new Error("npm/npx is required for the local LDGR CLI. Install Node.js with npm.");
+}
+var runNpx = async (args, options) => {
+  const entry = await resolveNpxEntrypoint();
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entry, ...args], {
+      shell: false,
+      windowsHide: true,
+      stdio: options.interactive ? "inherit" : ["pipe", "pipe", "ignore"]
+    });
+    let stdout = "", bytes = 0;
+    child.once("error", () => reject(new Error(FAILURE)));
+    if (!options.interactive) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > 128 * 1024) {
+          child.kill();
+          reject(new Error(FAILURE));
+        } else
+          stdout += chunk;
+      });
+      child.stdin.on("error", () => reject(new Error(FAILURE)));
+      child.stdin.end(options.input);
+    }
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout }));
+  });
+};
+function createLatestCliAdapter(run = runNpx) {
+  async function machine(envelope) {
+    const input = JSON.stringify(envelope);
+    if (Buffer.byteLength(input) > 128 * 1024)
+      throw new Error(FAILURE);
+    const result = await run(npxArguments("--stdin"), { interactive: false, input });
+    try {
+      const value = JSON.parse(result.stdout);
+      if (result.code !== 0 || !value || typeof value !== "object" || Array.isArray(value) || "error" in value)
+        throw new Error;
+      return value;
+    } catch {
+      throw new Error(FAILURE);
+    }
+  }
+  return {
+    walletInfo: (walletPath) => machine({ operation: "wallet-info", walletPath }),
+    async saveRequest(request, options) {
+      const value = await machine({ operation: "save-request", request, ...options });
+      if (typeof value.requestPath !== "string" || !Array.isArray(value.approvalArgs) || !value.approvalArgs.every((arg) => typeof arg === "string"))
+        throw new Error(FAILURE);
+      return { requestPath: value.requestPath, approvalArgs: walletCommandArgs(value.approvalArgs) };
+    },
+    async command(input) {
+      const args = walletCommandArgs(input);
+      const envelope = Buffer.from(JSON.stringify({ operation: "command", args })).toString("base64url");
+      if (envelope.length > 6000)
+        throw new Error("Wallet command arguments are too long");
+      return (await run(npxArguments(envelope), { interactive: true })).code;
+    }
+  };
+}
+
 // src/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { getMcpWalletInfo, saveMcpRequest, validateMcpRequest } from "@ldgr/cli/mcp";
 
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -163,7 +249,7 @@ class AssetMismatchError extends Error {
 class WalletNetworkMismatchError extends Error {
 }
 function createLdgrMcpServer(options = {}) {
-  const server = new McpServer({ name: "ldgr", version: "0.1.2" }, { instructions: INSTRUCTIONS });
+  const server = new McpServer({ name: "ldgr", version: "0.1.4" }, { instructions: INSTRUCTIONS });
   const request = readTransport(options.fetch);
   const now = options.now ?? Date.now;
   const envelope = (network, source, data) => ({ network, source, data });
@@ -263,12 +349,27 @@ function createLdgrMcpServer(options = {}) {
     const a = exactAsset(args.assetA, args.network), b = exactAsset(args.assetB, args.network), client = await checkedClient(args.network, request);
     return envelope(args.network, "ledger", await client.amm.getPoolByPair(a, b));
   });
-  tool("get_swap_quote", "Read a non-binding swap quote for explicit input/output assets. Does not prepare, sign or submit a swap.", { network: networkSchema, assetIn: assetSchema, assetOut: assetSchema, amountIn: positiveDecimalSchema }, async (args) => {
+  tool("get_swap_quote", "Read a non-binding swap quote for explicit input/output assets. Use prepare_swap with an explicit positive minimum received to prepare an unsigned intent; only human CLI approval can execute it.", { network: networkSchema, assetIn: assetSchema, assetOut: assetSchema, amountIn: positiveDecimalSchema }, async (args) => {
     const assetIn = exactAsset(args.assetIn, args.network), assetOut = exactAsset(args.assetOut, args.network);
     checkNativeAmount(assetIn, args.amountIn, args.network);
     const client = await checkedClient(args.network, request);
     return envelope(args.network, "ledger", await client.amm.quoteRoute(assetIn, assetOut, args.amountIn, 3));
   });
+  tool("prepare_swap", "Prepare an unsigned exact-input swap for human CLI approval. Specify both assets, amountIn and a positive amountOutMin in decimal display units. The CLI fetches a fresh route of up to maxHops pools and shows it before signing; it never lowers the minimum. Output goes to the selected wallet. Preparation does not quote, unlock, sign or submit.", {
+    network: networkSchema,
+    assetIn: assetSchema,
+    assetOut: assetSchema,
+    amountIn: positiveDecimalSchema,
+    amountOutMin: positiveDecimalSchema,
+    maxHops: z2.number().int().min(1).max(3).default(3)
+  }, async (args) => {
+    const assetIn = exactAsset(args.assetIn, args.network), assetOut = exactAsset(args.assetOut, args.network);
+    if (assetIn === assetOut)
+      throw new Error("Swap assets must differ");
+    checkNativeAmount(assetIn, args.amountIn, args.network);
+    checkNativeAmount(assetOut, args.amountOutMin, args.network);
+    return prepared(unsignedRequest(args.network, "swap", { assetIn, assetOut, amountIn: args.amountIn, amountOutMin: args.amountOutMin, maxHops: args.maxHops }, now()));
+  }, false);
   tool("prepare_transfer", "Prepare an unsigned transfer for human review in the local CLI wallet. Does not unlock, sign or submit.", { network: networkSchema, to: addressSchema, asset: assetSchema, amount: positiveDecimalSchema, memo: referenceSchema.optional() }, async (args) => {
     const to = addressForNetwork(args.to, args.network), asset = exactAsset(args.asset, args.network);
     checkNativeAmount(asset, args.amount, args.network);
@@ -312,7 +413,7 @@ function createLdgrMcpServer(options = {}) {
   }, false);
   tool("wallet_setup_instructions", "Explain user-run CLI wallet installation, creation/import and MCP connection. This tool cannot install software or access local files.", { network: networkSchema }, async (args) => ({
     network: args.network,
-    install: "npm install --global @ldgr/mcp@0.1.2",
+    install: "npm install --global @ldgr/mcp@0.1.4",
     node: ">=20.19.0",
     create: `ldgr-mcp wallet create${args.network === "testnet" ? " --testnet" : ""}`,
     import: `ldgr-mcp wallet import${args.network === "testnet" ? " --testnet" : ""}`,
@@ -337,10 +438,10 @@ function createLdgrMcpServer(options = {}) {
 }
 
 // src/browser.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import { win32 } from "node:path";
 var launchChrome = (command, args, waitForExit) => new Promise((resolve, reject) => {
-  const child = spawn(command, [...args], {
+  const child = spawn2(command, [...args], {
     shell: false,
     stdio: "ignore",
     windowsHide: true,
@@ -376,13 +477,14 @@ async function openFaucetInBrowser(url, options = {}) {
 
 // src/stdio.ts
 async function startLdgrMcpStdio(options = {}) {
+  const cli = createLatestCliAdapter();
   const server = createLdgrMcpServer({
     fetch: options.fetch,
     now: options.now,
     local: {
       openBrowser: openFaucetInBrowser,
-      walletInfo: () => getMcpWalletInfo(options.walletPath),
-      saveRequest: (request) => saveMcpRequest(validateMcpRequest(request), { walletPath: options.walletPath, directory: options.requestDirectory })
+      walletInfo: () => cli.walletInfo(options.walletPath),
+      saveRequest: (request) => cli.saveRequest(request, { walletPath: options.walletPath, directory: options.requestDirectory })
     }
   });
   await server.connect(new StdioServerTransport);
@@ -390,7 +492,7 @@ async function startLdgrMcpStdio(options = {}) {
 }
 
 // src/cli.ts
-var HELP = `LDGR MCP 0.1.2
+var HELP = `LDGR MCP 0.1.4
 
 ldgr-mcp                         Start local MCP over stdio
 ldgr-mcp --wallet <path>         Start MCP with a selected wallet store
@@ -414,13 +516,7 @@ try {
   } else if (args.length === 0 || args.length === 2 && args[0] === "--wallet" && args[1] && !args[1].startsWith("-")) {
     await startLdgrMcpStdio({ walletPath: args[1] });
   } else {
-    const forwarded = walletCommandArgs(args);
-    const entry = fileURLToPath(import.meta.resolve("@ldgr/cli/cli"));
-    process.exitCode = await new Promise((resolve, reject) => {
-      const child = spawn2(process.execPath, [entry, ...forwarded], { stdio: "inherit", shell: false });
-      child.once("error", reject);
-      child.once("exit", (code) => resolve(code ?? 1));
-    });
+    process.exitCode = await createLatestCliAdapter().command(args);
   }
 } catch {
   console.error("LDGR MCP could not complete. Check --help, the local wallet and request file. Recovery keys and passphrases belong only in local interactive prompts.");

package/dist/index.js

@@ -121,7 +121,7 @@ class AssetMismatchError extends Error {
 class WalletNetworkMismatchError extends Error {
 }
 function createLdgrMcpServer(options = {}) {
-  const server = new McpServer({ name: "ldgr", version: "0.1.2" }, { instructions: INSTRUCTIONS });
+  const server = new McpServer({ name: "ldgr", version: "0.1.4" }, { instructions: INSTRUCTIONS });
   const request = readTransport(options.fetch);
   const now = options.now ?? Date.now;
   const envelope = (network, source, data) => ({ network, source, data });
@@ -221,12 +221,27 @@ function createLdgrMcpServer(options = {}) {
     const a = exactAsset(args.assetA, args.network), b = exactAsset(args.assetB, args.network), client = await checkedClient(args.network, request);
     return envelope(args.network, "ledger", await client.amm.getPoolByPair(a, b));
   });
-  tool("get_swap_quote", "Read a non-binding swap quote for explicit input/output assets. Does not prepare, sign or submit a swap.", { network: networkSchema, assetIn: assetSchema, assetOut: assetSchema, amountIn: positiveDecimalSchema }, async (args) => {
+  tool("get_swap_quote", "Read a non-binding swap quote for explicit input/output assets. Use prepare_swap with an explicit positive minimum received to prepare an unsigned intent; only human CLI approval can execute it.", { network: networkSchema, assetIn: assetSchema, assetOut: assetSchema, amountIn: positiveDecimalSchema }, async (args) => {
     const assetIn = exactAsset(args.assetIn, args.network), assetOut = exactAsset(args.assetOut, args.network);
     checkNativeAmount(assetIn, args.amountIn, args.network);
     const client = await checkedClient(args.network, request);
     return envelope(args.network, "ledger", await client.amm.quoteRoute(assetIn, assetOut, args.amountIn, 3));
   });
+  tool("prepare_swap", "Prepare an unsigned exact-input swap for human CLI approval. Specify both assets, amountIn and a positive amountOutMin in decimal display units. The CLI fetches a fresh route of up to maxHops pools and shows it before signing; it never lowers the minimum. Output goes to the selected wallet. Preparation does not quote, unlock, sign or submit.", {
+    network: networkSchema,
+    assetIn: assetSchema,
+    assetOut: assetSchema,
+    amountIn: positiveDecimalSchema,
+    amountOutMin: positiveDecimalSchema,
+    maxHops: z2.number().int().min(1).max(3).default(3)
+  }, async (args) => {
+    const assetIn = exactAsset(args.assetIn, args.network), assetOut = exactAsset(args.assetOut, args.network);
+    if (assetIn === assetOut)
+      throw new Error("Swap assets must differ");
+    checkNativeAmount(assetIn, args.amountIn, args.network);
+    checkNativeAmount(assetOut, args.amountOutMin, args.network);
+    return prepared(unsignedRequest(args.network, "swap", { assetIn, assetOut, amountIn: args.amountIn, amountOutMin: args.amountOutMin, maxHops: args.maxHops }, now()));
+  }, false);
   tool("prepare_transfer", "Prepare an unsigned transfer for human review in the local CLI wallet. Does not unlock, sign or submit.", { network: networkSchema, to: addressSchema, asset: assetSchema, amount: positiveDecimalSchema, memo: referenceSchema.optional() }, async (args) => {
     const to = addressForNetwork(args.to, args.network), asset = exactAsset(args.asset, args.network);
     checkNativeAmount(asset, args.amount, args.network);
@@ -270,7 +285,7 @@ function createLdgrMcpServer(options = {}) {
   }, false);
   tool("wallet_setup_instructions", "Explain user-run CLI wallet installation, creation/import and MCP connection. This tool cannot install software or access local files.", { network: networkSchema }, async (args) => ({
     network: args.network,
-    install: "npm install --global @ldgr/mcp@0.1.2",
+    install: "npm install --global @ldgr/mcp@0.1.4",
     node: ">=20.19.0",
     create: `ldgr-mcp wallet create${args.network === "testnet" ? " --testnet" : ""}`,
     import: `ldgr-mcp wallet import${args.network === "testnet" ? " --testnet" : ""}`,

package/dist/latest-cli.d.ts

@@ -0,0 +1,25 @@
+import type { UnsignedMcpRequest } from "./requests";
+type RunOptions = {
+    readonly interactive: boolean;
+    readonly input?: string;
+};
+type Runner = (args: readonly string[], options: RunOptions) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+/** Only fixed arguments or a base64url envelope reach npm's internal command shell. */
+export declare function npxArguments(envelope: string): string[];
+/** Execute npm's JS entry directly: Windows .cmd launchers require a shell. */
+export declare function resolveNpxEntrypoint(): Promise<string>;
+export declare function createLatestCliAdapter(run?: Runner): {
+    walletInfo: (walletPath?: string) => Promise<unknown>;
+    saveRequest(request: UnsignedMcpRequest, options: {
+        walletPath?: string;
+        directory?: string;
+    }): Promise<{
+        requestPath: string;
+        approvalArgs: string[];
+    }>;
+    command(input: readonly string[]): Promise<number>;
+};
+export {};

package/dist/requests.d.ts

@@ -5,7 +5,7 @@ export type UnsignedMcpRequest = {
     readonly requestId: string;
     readonly network: McpNetwork;
     readonly expiresAt: string;
-    readonly action: "transfer" | "create_token" | "open_escrow";
+    readonly action: "transfer" | "create_token" | "open_escrow" | "swap";
     readonly params: Readonly<Record<string, string | number | undefined>>;
 };
 export declare const networkSchema: z.ZodEnum<{

package/dist/stdio.js

@@ -1,6 +1,128 @@
 // src/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { getMcpWalletInfo, saveMcpRequest, validateMcpRequest } from "@ldgr/cli/mcp";
+
+// src/latest-cli.ts
+import { spawn } from "node:child_process";
+import { access, realpath } from "node:fs/promises";
+import { delimiter, dirname, join } from "node:path";
+
+// src/commands.ts
+function walletCommandArgs(input) {
+  if (input.some((value) => !value || /[\x00-\x1f\x7f]/.test(value)))
+    throw new TypeError("Invalid wallet arguments");
+  const positional = [];
+  let testnet = false, wallet = false;
+  for (let index = 0;index < input.length; index++) {
+    const value = input[index];
+    if (value === "--wallet") {
+      if (wallet || !input[index + 1] || input[index + 1].startsWith("-"))
+        throw new TypeError("Invalid wallet path");
+      wallet = true;
+      index++;
+    } else if (value === "--testnet") {
+      if (testnet)
+        throw new TypeError("Repeated network flag");
+      testnet = true;
+    } else if (value.startsWith("-"))
+      throw new TypeError("Unsupported wallet option");
+    else
+      positional.push(value);
+  }
+  const [first, second, third] = positional;
+  const creation = first === "wallet" && (second === "create" || second === "import");
+  if (testnet && !creation)
+    throw new TypeError("--testnet only applies to wallet create/import");
+  const valid = first === "wallet" && second === "create" && positional.length === 2 || first === "wallet" && second === "import" && (positional.length === 2 || positional.length === 3) || first === "wallet" && second === "list" && positional.length === 2 || first === "wallet" && second === "select" && positional.length === 3 && /^[0-9]+$/.test(third) || first === "approve" && positional.length === 2 || first === "address" && positional.length === 1 || first === "network" && second === "show" && positional.length === 2 || first === "network" && second === "set" && positional.length === 3 && (third === "mainnet" || third === "testnet");
+  if (!valid)
+    throw new TypeError("Unsupported wallet command");
+  return [...input];
+}
+
+// src/latest-cli.ts
+var FAILURE = "Latest LDGR CLI could not complete. Check npm connectivity and CLI availability.";
+function npxArguments(envelope) {
+  return ["--yes", "--prefer-online", "--offline=false", "--package", "@ldgr/cli@latest", "--", "ldgr", "mcp", envelope];
+}
+async function resolveNpxEntrypoint() {
+  const directories = [dirname(process.execPath), ...(process.env.PATH ?? "").split(delimiter).filter(Boolean)];
+  const candidates = [];
+  const npmPath = process.env.npm_execpath;
+  if (npmPath && /[\\/]npm-cli\.js$/.test(npmPath))
+    candidates.push(join(dirname(npmPath), "npx-cli.js"));
+  for (const directory of directories) {
+    candidates.push(join(directory, "node_modules/npm/bin/npx-cli.js"), join(directory, "../lib/node_modules/npm/bin/npx-cli.js"));
+    try {
+      const target = await realpath(join(directory, "npx"));
+      if (target.endsWith("npx-cli.js"))
+        candidates.push(target);
+    } catch {}
+  }
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {}
+  }
+  throw new Error("npm/npx is required for the local LDGR CLI. Install Node.js with npm.");
+}
+var runNpx = async (args, options) => {
+  const entry = await resolveNpxEntrypoint();
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entry, ...args], {
+      shell: false,
+      windowsHide: true,
+      stdio: options.interactive ? "inherit" : ["pipe", "pipe", "ignore"]
+    });
+    let stdout = "", bytes = 0;
+    child.once("error", () => reject(new Error(FAILURE)));
+    if (!options.interactive) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > 128 * 1024) {
+          child.kill();
+          reject(new Error(FAILURE));
+        } else
+          stdout += chunk;
+      });
+      child.stdin.on("error", () => reject(new Error(FAILURE)));
+      child.stdin.end(options.input);
+    }
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout }));
+  });
+};
+function createLatestCliAdapter(run = runNpx) {
+  async function machine(envelope) {
+    const input = JSON.stringify(envelope);
+    if (Buffer.byteLength(input) > 128 * 1024)
+      throw new Error(FAILURE);
+    const result = await run(npxArguments("--stdin"), { interactive: false, input });
+    try {
+      const value = JSON.parse(result.stdout);
+      if (result.code !== 0 || !value || typeof value !== "object" || Array.isArray(value) || "error" in value)
+        throw new Error;
+      return value;
+    } catch {
+      throw new Error(FAILURE);
+    }
+  }
+  return {
+    walletInfo: (walletPath) => machine({ operation: "wallet-info", walletPath }),
+    async saveRequest(request, options) {
+      const value = await machine({ operation: "save-request", request, ...options });
+      if (typeof value.requestPath !== "string" || !Array.isArray(value.approvalArgs) || !value.approvalArgs.every((arg) => typeof arg === "string"))
+        throw new Error(FAILURE);
+      return { requestPath: value.requestPath, approvalArgs: walletCommandArgs(value.approvalArgs) };
+    },
+    async command(input) {
+      const args = walletCommandArgs(input);
+      const envelope = Buffer.from(JSON.stringify({ operation: "command", args })).toString("base64url");
+      if (envelope.length > 6000)
+        throw new Error("Wallet command arguments are too long");
+      return (await run(npxArguments(envelope), { interactive: true })).code;
+    }
+  };
+}
 
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -125,7 +247,7 @@ class AssetMismatchError extends Error {
 class WalletNetworkMismatchError extends Error {
 }
 function createLdgrMcpServer(options = {}) {
-  const server = new McpServer({ name: "ldgr", version: "0.1.2" }, { instructions: INSTRUCTIONS });
+  const server = new McpServer({ name: "ldgr", version: "0.1.4" }, { instructions: INSTRUCTIONS });
   const request = readTransport(options.fetch);
   const now = options.now ?? Date.now;
   const envelope = (network, source, data) => ({ network, source, data });
@@ -225,12 +347,27 @@ function createLdgrMcpServer(options = {}) {
     const a = exactAsset(args.assetA, args.network), b = exactAsset(args.assetB, args.network), client = await checkedClient(args.network, request);
     return envelope(args.network, "ledger", await client.amm.getPoolByPair(a, b));
   });
-  tool("get_swap_quote", "Read a non-binding swap quote for explicit input/output assets. Does not prepare, sign or submit a swap.", { network: networkSchema, assetIn: assetSchema, assetOut: assetSchema, amountIn: positiveDecimalSchema }, async (args) => {
+  tool("get_swap_quote", "Read a non-binding swap quote for explicit input/output assets. Use prepare_swap with an explicit positive minimum received to prepare an unsigned intent; only human CLI approval can execute it.", { network: networkSchema, assetIn: assetSchema, assetOut: assetSchema, amountIn: positiveDecimalSchema }, async (args) => {
     const assetIn = exactAsset(args.assetIn, args.network), assetOut = exactAsset(args.assetOut, args.network);
     checkNativeAmount(assetIn, args.amountIn, args.network);
     const client = await checkedClient(args.network, request);
     return envelope(args.network, "ledger", await client.amm.quoteRoute(assetIn, assetOut, args.amountIn, 3));
   });
+  tool("prepare_swap", "Prepare an unsigned exact-input swap for human CLI approval. Specify both assets, amountIn and a positive amountOutMin in decimal display units. The CLI fetches a fresh route of up to maxHops pools and shows it before signing; it never lowers the minimum. Output goes to the selected wallet. Preparation does not quote, unlock, sign or submit.", {
+    network: networkSchema,
+    assetIn: assetSchema,
+    assetOut: assetSchema,
+    amountIn: positiveDecimalSchema,
+    amountOutMin: positiveDecimalSchema,
+    maxHops: z2.number().int().min(1).max(3).default(3)
+  }, async (args) => {
+    const assetIn = exactAsset(args.assetIn, args.network), assetOut = exactAsset(args.assetOut, args.network);
+    if (assetIn === assetOut)
+      throw new Error("Swap assets must differ");
+    checkNativeAmount(assetIn, args.amountIn, args.network);
+    checkNativeAmount(assetOut, args.amountOutMin, args.network);
+    return prepared(unsignedRequest(args.network, "swap", { assetIn, assetOut, amountIn: args.amountIn, amountOutMin: args.amountOutMin, maxHops: args.maxHops }, now()));
+  }, false);
   tool("prepare_transfer", "Prepare an unsigned transfer for human review in the local CLI wallet. Does not unlock, sign or submit.", { network: networkSchema, to: addressSchema, asset: assetSchema, amount: positiveDecimalSchema, memo: referenceSchema.optional() }, async (args) => {
     const to = addressForNetwork(args.to, args.network), asset = exactAsset(args.asset, args.network);
     checkNativeAmount(asset, args.amount, args.network);
@@ -274,7 +411,7 @@ function createLdgrMcpServer(options = {}) {
   }, false);
   tool("wallet_setup_instructions", "Explain user-run CLI wallet installation, creation/import and MCP connection. This tool cannot install software or access local files.", { network: networkSchema }, async (args) => ({
     network: args.network,
-    install: "npm install --global @ldgr/mcp@0.1.2",
+    install: "npm install --global @ldgr/mcp@0.1.4",
     node: ">=20.19.0",
     create: `ldgr-mcp wallet create${args.network === "testnet" ? " --testnet" : ""}`,
     import: `ldgr-mcp wallet import${args.network === "testnet" ? " --testnet" : ""}`,
@@ -299,10 +436,10 @@ function createLdgrMcpServer(options = {}) {
 }
 
 // src/browser.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import { win32 } from "node:path";
 var launchChrome = (command, args, waitForExit) => new Promise((resolve, reject) => {
-  const child = spawn(command, [...args], {
+  const child = spawn2(command, [...args], {
     shell: false,
     stdio: "ignore",
     windowsHide: true,
@@ -338,13 +475,14 @@ async function openFaucetInBrowser(url, options = {}) {
 
 // src/stdio.ts
 async function startLdgrMcpStdio(options = {}) {
+  const cli = createLatestCliAdapter();
   const server = createLdgrMcpServer({
     fetch: options.fetch,
     now: options.now,
     local: {
       openBrowser: openFaucetInBrowser,
-      walletInfo: () => getMcpWalletInfo(options.walletPath),
-      saveRequest: (request) => saveMcpRequest(validateMcpRequest(request), { walletPath: options.walletPath, directory: options.requestDirectory })
+      walletInfo: () => cli.walletInfo(options.walletPath),
+      saveRequest: (request) => cli.saveRequest(request, { walletPath: options.walletPath, directory: options.requestDirectory })
     }
   });
   await server.connect(new StdioServerTransport);

package/package.json

@@ -1,29 +1,28 @@
-{
-  "name": "@ldgr/mcp",
-  "version": "0.1.2",
-  "type": "module",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./stdio": { "types": "./dist/stdio.d.ts", "import": "./dist/stdio.js" }
-  },
-  "bin": { "ldgr-mcp": "dist/cli.js" },
-  "files": ["dist", "README.md"],
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=20.19.0" },
-  "dependencies": {
-    "@ldgr/client": "^0.6.1",
-    "@ldgr/cli": "^0.5.0",
-    "@ldgr/protocol": "^0.5.0",
-    "@modelcontextprotocol/sdk": "1.32.2",
-    "zod": "^4.3.6"
-  },
-  "scripts": {
-    "build": "bun build src/index.ts src/stdio.ts src/cli.ts --outdir dist --target node --format esm --packages external && tsrs -p tsconfig.build.json",
-    "prepack": "bun run build",
-    "start": "bun src/cli.ts",
-    "test": "bun test",
-    "typecheck": "tsrs --noEmit -p tsconfig.json && tsrs --noEmit -p test/tsconfig.json"
-  },
-  "devDependencies": { "tsrs": "0.20.0-ts7.1.0-beta" }
-}
+{
+  "name": "@ldgr/mcp",
+  "version": "0.1.4",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./stdio": { "types": "./dist/stdio.d.ts", "import": "./dist/stdio.js" }
+  },
+  "bin": { "ldgr-mcp": "dist/cli.js" },
+  "files": ["dist", "README.md"],
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20.19.0" },
+  "dependencies": {
+    "@ldgr/client": "^0.6.1",
+    "@ldgr/protocol": "^0.5.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts src/stdio.ts src/cli.ts --outdir dist --target node --format esm --packages external && tsrs -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "start": "bun src/cli.ts",
+    "test": "bun test",
+    "typecheck": "tsrs --noEmit -p tsconfig.json && tsrs --noEmit -p test/tsconfig.json"
+  },
+  "devDependencies": { "tsrs": "0.20.0-ts7.1.0-beta" }
+}