@ldgr/mcp 0.1.3 → 0.1.4

package/README.md

@@ -13,7 +13,7 @@ A remote MCP connection cannot install software, access local files, unlock a wa
 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.3
+npm install --global @ldgr/mcp@0.1.4
 ldgr-mcp wallet create --testnet
 # Or: ldgr-mcp wallet import --testnet
 ldgr-mcp wallet list
@@ -68,6 +68,7 @@ Restart the MCP process after upgrading; a running process keeps its loaded SDK.
 | `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 |
 
@@ -104,6 +105,26 @@ 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

package/dist/cli.js

@@ -249,7 +249,7 @@ class AssetMismatchError extends Error {
 class WalletNetworkMismatchError extends Error {
 }
 function createLdgrMcpServer(options = {}) {
-  const server = new McpServer({ name: "ldgr", version: "0.1.3" }, { 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 });
@@ -349,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);
@@ -398,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.3",
+    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" : ""}`,
@@ -477,7 +492,7 @@ async function startLdgrMcpStdio(options = {}) {
 }
 
 // src/cli.ts
-var HELP = `LDGR MCP 0.1.3
+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

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.3" }, { 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.3",
+    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/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

@@ -247,7 +247,7 @@ class AssetMismatchError extends Error {
 class WalletNetworkMismatchError extends Error {
 }
 function createLdgrMcpServer(options = {}) {
-  const server = new McpServer({ name: "ldgr", version: "0.1.3" }, { 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 });
@@ -347,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);
@@ -396,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.3",
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {