@floatonnear/mcp 0.1.1 → 0.3.0

package/dist/payloads.d.ts

@@ -103,3 +103,46 @@ export declare const OWNER_PLANNERS: {
 };
 /** A ready-to-run command, so approving does not require trusting this server. */
 export declare function toCliCommand(p: OwnerPayload, network?: string): string;
+/**
+ * Require the owner to approve payments above `amount` at this node.
+ *
+ * A threshold is a gate INSIDE the caps: it can only make the vault more
+ * conservative, never less, so there is no value of it that moves more money
+ * than the budget tree already allowed. `null` removes it.
+ *
+ * ---- `amount` IS HUMAN UNITS, and it used to be base units.
+ *
+ * Breaking change, 2026-10-31, made the same day the tool was published and
+ * before anyone used it. The parameter was `amountBase` and took raw base
+ * units, which made it the ONLY tool in this module on that convention:
+ *
+ *   vault_pay.amount                   human   "12.50"
+ *   planSetNodeCaps dailyCap/perTxCap  human   (the zod schema says so)
+ *   planSetApprovalThreshold           BASE    <- the odd one out
+ *
+ * And it is the one that configures a safety gate, so it FAILED OPEN. An owner
+ * thinking in human units who passed a figure at or above the per-tx cap in
+ * base units got a threshold ABOVE every cap in the tree: the gate never fires,
+ * nothing is ever held, and the transaction succeeds — so the owner believes the
+ * control is on. Measured against the live mainnet vault (per-tx cap 510000
+ * base = 0.51 USDC): "1000000" meaning "a million" yields a 1.0 USDC threshold,
+ * above every cap.
+ *
+ * The other direction fails closed and is merely annoying ("1" meaning 1 USDC
+ * became 0.000001, so everything got held), which is why only one direction is
+ * dangerous and why this is worth a breaking change rather than a doc fix.
+ *
+ * `toBaseUnits` throws rather than truncating excess precision — correct here:
+ * silently rounding 0.1234567 would set a threshold the owner did not choose.
+ */
+export declare function planSetApprovalThreshold(vault: string, nodeId: number, amount: string | null, decimals: number): OwnerPayload;
+/**
+ * Execute a held payment.
+ *
+ * Every limit is re-checked at approval time, so this can still be refused --
+ * by a cap tightened while it waited, or by an Intents quote that expired. That
+ * is the honest outcome and the warning says so.
+ */
+export declare function planApprovePayment(vault: string, requestId: string): OwnerPayload;
+/** Decline a held payment. The ticket is discarded and nothing moves. */
+export declare function planRejectPayment(vault: string, requestId: string): OwnerPayload;

package/dist/payloads.js

@@ -290,3 +290,87 @@ export function toCliCommand(p, network = "testnet") {
         `attached-deposit '${p.depositYocto} yoctoNEAR' ` +
         `sign-as <YOUR-OWNER-ACCOUNT> network-config ${network} sign-with-keychain send`);
 }
+/**
+ * Require the owner to approve payments above `amount` at this node.
+ *
+ * A threshold is a gate INSIDE the caps: it can only make the vault more
+ * conservative, never less, so there is no value of it that moves more money
+ * than the budget tree already allowed. `null` removes it.
+ *
+ * ---- `amount` IS HUMAN UNITS, and it used to be base units.
+ *
+ * Breaking change, 2026-10-31, made the same day the tool was published and
+ * before anyone used it. The parameter was `amountBase` and took raw base
+ * units, which made it the ONLY tool in this module on that convention:
+ *
+ *   vault_pay.amount                   human   "12.50"
+ *   planSetNodeCaps dailyCap/perTxCap  human   (the zod schema says so)
+ *   planSetApprovalThreshold           BASE    <- the odd one out
+ *
+ * And it is the one that configures a safety gate, so it FAILED OPEN. An owner
+ * thinking in human units who passed a figure at or above the per-tx cap in
+ * base units got a threshold ABOVE every cap in the tree: the gate never fires,
+ * nothing is ever held, and the transaction succeeds — so the owner believes the
+ * control is on. Measured against the live mainnet vault (per-tx cap 510000
+ * base = 0.51 USDC): "1000000" meaning "a million" yields a 1.0 USDC threshold,
+ * above every cap.
+ *
+ * The other direction fails closed and is merely annoying ("1" meaning 1 USDC
+ * became 0.000001, so everything got held), which is why only one direction is
+ * dangerous and why this is worth a breaking change rather than a doc fix.
+ *
+ * `toBaseUnits` throws rather than truncating excess precision — correct here:
+ * silently rounding 0.1234567 would set a threshold the owner did not choose.
+ */
+export function planSetApprovalThreshold(vault, nodeId, amount, decimals) {
+    const base = amount === null ? null : toBaseUnits(amount, decimals).toString();
+    return {
+        receiverId: vault,
+        methodName: "set_approval_threshold",
+        args: { node_id: nodeId, amount: base },
+        gasTgas: DEFAULT_GAS_TGAS,
+        depositYocto: ONE_YOCTO,
+        // Human units in the summary too. The old line read "Payments above
+        // 1000000 (base units)", which is unreadable in precisely the moment the
+        // owner is checking the plan before signing it.
+        summary: amount
+            ? `Payments above ${amount} from node ${nodeId} will need your approval`
+            : `Remove the approval threshold on node ${nodeId} — payments up to the caps run unattended`,
+        warnings: amount
+            ? []
+            : ["After this, nothing at this node waits for a human: only the caps apply."],
+    };
+}
+/**
+ * Execute a held payment.
+ *
+ * Every limit is re-checked at approval time, so this can still be refused --
+ * by a cap tightened while it waited, or by an Intents quote that expired. That
+ * is the honest outcome and the warning says so.
+ */
+export function planApprovePayment(vault, requestId) {
+    return {
+        receiverId: vault,
+        methodName: "approve_payment",
+        args: { request_id: requestId },
+        gasTgas: DEFAULT_GAS_TGAS,
+        depositYocto: ONE_YOCTO,
+        summary: `Approve and send held payment ${requestId}`,
+        warnings: [
+            "This MOVES MONEY. Check the amount and payee with vault_pending_approval first.",
+            "Limits are re-checked now, so it can still be refused — a cap lowered since the request, or a cross-chain quote that has expired.",
+        ],
+    };
+}
+/** Decline a held payment. The ticket is discarded and nothing moves. */
+export function planRejectPayment(vault, requestId) {
+    return {
+        receiverId: vault,
+        methodName: "reject_payment",
+        args: { request_id: requestId },
+        gasTgas: DEFAULT_GAS_TGAS,
+        depositYocto: ONE_YOCTO,
+        summary: `Reject held payment ${requestId}`,
+        warnings: ["The agent must request again if it still needs the money."],
+    };
+}

package/dist/server.js

@@ -22,7 +22,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { fromBaseUnits, toBaseUnits } from "./amounts.js";
-import { DEFAULT_GAS_TGAS, planAddNode, planCreateAgentAccount, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, toCliCommand, } from "./payloads.js";
+import { DEFAULT_GAS_TGAS, planAddNode, planCreateAgentAccount, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, toCliCommand, planSetApprovalThreshold, planApprovePayment, planRejectPayment, } from "./payloads.js";
 import { DEFAULT_RPC_URL, newRequestId, requireAgentKey, viewFunction } from "./rpc.js";
 import { buildRoute, sendRequestPayment } from "./sign.js";
 import { getQuote, signBinding, toBase64 } from "./quote.js";
@@ -87,7 +87,7 @@ const limitShape = z
 // startup: a wrong relative path would break the server outright instead of
 // merely reporting a stale version. server.smoke.test.ts asserts the two agree,
 // so a bump cannot land with only one of them moved.
-const server = new McpServer({ name: "float", version: "0.1.1" });
+const server = new McpServer({ name: "float", version: "0.3.0" });
 // ----------------------------------------------------------------- reads
 server.tool("vault_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {})));
 server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed, in-flight (pending) and available, in human units. Omit `day` for today. No key required.", {
@@ -208,6 +208,20 @@ server.tool("vault_plan_create_agent", "Build an UNSIGNED payload to create an a
 server.tool("vault_plan_freeze", "Build an UNSIGNED payload to freeze or unfreeze a node. Freezing blocks the node AND its whole subtree. Not signed by this server.", { nodeId: z.number().int().min(0), frozen: z.boolean() }, async ({ nodeId, frozen }) => renderPlan(planFreezeNode(requireVault(), nodeId, frozen)));
 server.tool("vault_plan_set_recipients", "Build an UNSIGNED payload to set a node's payee allowlist. This REPLACES the inherited list rather than adding to it; pass null to inherit. Not signed by this server.", { nodeId: z.number().int().min(0), recipients: z.array(z.string()).nullable() }, async ({ nodeId, recipients }) => renderPlan(planSetRecipients(requireVault(), nodeId, recipients)));
 server.tool("vault_plan_set_cooldown", "Build an UNSIGNED payload to set the minimum seconds between a node's payments. Not signed by this server.", { nodeId: z.number().int().min(0), cooldownSec: z.number().int().min(0) }, async ({ nodeId, cooldownSec }) => renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec)));
+server.tool("vault_pending_approval", "Look up a payment that is HELD awaiting the owner's approval. Returns null if there is no ticket for that id — already approved, already rejected, or never held.", { requestId: z.string().min(1) }, async ({ requestId }) => json((await viewFunction(cfg.rpcUrl, requireVault(), "get_pending_approval", {
+    request_id: requestId,
+})) ?? null));
+server.tool("vault_plan_set_approval_threshold", 'Build an UNSIGNED payload requiring the owner\'s approval for payments above an amount at this node. A threshold sits INSIDE the caps and can only make the vault more conservative. `amount` is HUMAN units, the same convention as vault_pay — "0.25" is a quarter of a USDC. Pass amount null to remove the threshold. Not signed by this server.', {
+    nodeId: z.number().int().min(0),
+    // HUMAN units, matching vault_pay and vault_plan_set_caps. This took BASE
+    // units until 2026-10-31 and was the only tool here that did — on the one
+    // control that configures a safety gate, where the mistake fails OPEN. See
+    // planSetApprovalThreshold in payloads.ts for the measurement.
+    amount: z.string().min(1).nullable().describe('human units, e.g. "0.25" — NOT base units'),
+    decimals: z.number().int().min(0).max(38).default(6),
+}, async ({ nodeId, amount, decimals }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amount, decimals)));
+server.tool("vault_plan_approve_payment", "Build an UNSIGNED payload to APPROVE a held payment, which sends it. Every limit is re-checked at approval, so it can still be refused. Not signed by this server.", { requestId: z.string().min(1) }, async ({ requestId }) => renderPlan(planApprovePayment(requireVault(), requestId)));
+server.tool("vault_plan_reject_payment", "Build an UNSIGNED payload to REJECT a held payment. Nothing moves and the ticket is discarded. Not signed by this server.", { requestId: z.string().min(1) }, async ({ requestId }) => renderPlan(planRejectPayment(requireVault(), requestId)));
 server.tool("vault_plan_pause", "Build an UNSIGNED payload to pause or resume the whole vault. Pausing halts every agent payment. Not signed by this server.", { paused: z.boolean() }, async ({ paused }) => renderPlan(planSetPaused(requireVault(), paused)));
 server.tool("vault_plan_purge", "Build an UNSIGNED payload to delete settled payment records older than a UTC day. Spend totals are NOT refunded, but a deleted request id becomes reusable. Not signed by this server.", {
     beforeDay: z.number().int().min(0),

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@floatonnear/mcp",
-  "version": "0.1.1",
-  "type": "module",
-  "description": "MCP server for the hierarchical budget vault. The agent key signs request_payment only; owner methods emit unsigned payloads for wallet approval.",
-  "license": "MIT",
-  "bin": {
-    "mcp": "dist/server.js",
-    "float-mcp": "dist/server.js"
-  },
-  "files": [
-    "dist/"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.2",
-    "@noble/curves": "^1.9.7",
-    "@noble/hashes": "^1.8.0",
-    "near-api-js": "^7.4.0",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.9.0",
-    "vitest": "^5.0.5"
-  },
-  "exports": {
-    ".": "./dist/index.js",
-    "./amounts": "./dist/amounts.js",
-    "./sign": "./dist/sign.js",
-    "./payloads": "./dist/payloads.js",
-    "./quote": {
-      "types": "./dist/quote.d.ts",
-      "import": "./dist/quote.js"
-    }
-  }
-}
+{
+  "name": "@floatonnear/mcp",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "MCP server for the hierarchical budget vault. The agent key signs request_payment only; owner methods emit unsigned payloads for wallet approval.",
+  "license": "MIT",
+  "bin": {
+    "mcp": "dist/server.js",
+    "float-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "near-api-js": "^7.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^5.0.5"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./amounts": "./dist/amounts.js",
+    "./sign": "./dist/sign.js",
+    "./payloads": "./dist/payloads.js",
+    "./quote": {
+      "types": "./dist/quote.d.ts",
+      "import": "./dist/quote.js"
+    }
+  }
+}