@floatonnear/mcp 0.1.0 → 0.2.0

package/dist/payloads.d.ts

@@ -103,3 +103,21 @@ 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.
+ */
+export declare function planSetApprovalThreshold(vault: string, nodeId: number, amountBase: string | null): 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,58 @@ 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.
+ */
+export function planSetApprovalThreshold(vault, nodeId, amountBase) {
+    return {
+        receiverId: vault,
+        methodName: "set_approval_threshold",
+        args: { node_id: nodeId, amount: amountBase },
+        gasTgas: DEFAULT_GAS_TGAS,
+        depositYocto: ONE_YOCTO,
+        summary: amountBase
+            ? `Payments above ${amountBase} (base units) from node ${nodeId} will need your approval`
+            : `Remove the approval threshold on node ${nodeId} — payments up to the caps run unattended`,
+        warnings: amountBase
+            ? []
+            : ["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";
@@ -77,7 +77,17 @@ const limitShape = z
     decimals: z.number().int().min(0).max(38).default(6),
 }))
     .min(1);
-const server = new McpServer({ name: "near-vault", version: "0.1.0" });
+// The name a client displays in its server list, so this string -- not the
+// package name, not the config key -- is the product's label in the one place
+// the product is visible. It was "near-vault": the repo's directory name,
+// leaking outward as the user-facing identity while the config key create-float
+// writes has always been `float`.
+//
+// The version stays a literal rather than being read from package.json at
+// 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.2.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.", {
@@ -198,6 +208,12 @@ 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. Pass amountBase null to remove it. Not signed by this server.", { nodeId: z.number().int().min(0), amountBase: z.string().min(1).nullable() }, async ({ nodeId, amountBase }) => renderPlan(planSetApprovalThreshold(requireVault(), nodeId, amountBase)));
+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.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"
-    }
-  }
-}
+{
+  "name": "@floatonnear/mcp",
+  "version": "0.2.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"
+    }
+  }
+}