@floatonnear/mcp 0.6.4 → 0.6.5

package/dist/amounts.d.ts

@@ -18,3 +18,38 @@
 export declare function toBaseUnits(amount: string, decimals: number): bigint;
 /** Render base units as a canonical human string: no trailing point, no trailing zeroes. */
 export declare function fromBaseUnits(units: bigint, decimals: number): string;
+/**
+ * The contract speaks BASE UNITS; a person reading a budget does not.
+ *
+ * `get_tree` returns `daily_cap: "25000000"` for a 25 USDC cap, while
+ * `vault_budget` — reading the same number through `get_node_budget` — returns
+ * `"25"`. Two tools, one vault, one figure, two formats, and nothing said
+ * which was which. In a demo that reads as a bug even when both are correct,
+ * and `"25000000"` next to a `per_tx_cap` of `"10000000"` invites someone to
+ * conclude the caps are enormous.
+ *
+ * CONVERTED ONLY WHERE THE DECIMALS ARE KNOWN. Caps are stored PER TOKEN and a
+ * vault may hold limits for several, but this server knows the decimals of
+ * exactly one — `NEAR_VAULT_TOKEN_DECIMALS`, which describes
+ * `NEAR_VAULT_TOKEN`. Scaling some other token by 6 would print a number that
+ * is wrong by orders of magnitude while looking tidy, which is strictly worse
+ * than the raw figure it replaced. So a token we cannot vouch for keeps its
+ * base units and says so, rather than being guessed at.
+ *
+ * `decimals` is echoed on every converted entry so the base figure stays
+ * derivable; nothing is lost, it is only no longer the default reading.
+ */
+export interface TreeLimit {
+    token: string;
+    daily_cap: string;
+    per_tx_cap: string;
+}
+export interface TreeNode {
+    limits?: TreeLimit[];
+    child_cap_sum?: [string, string][];
+    [k: string]: unknown;
+}
+export declare function humaniseTreeNode(node: TreeNode, cfg: {
+    token?: string;
+    decimals: number;
+}): TreeNode;

package/dist/amounts.js

@@ -53,3 +53,35 @@ export function fromBaseUnits(units, decimals) {
     const frac = (units % scale).toString().padStart(decimals, "0").replace(/0+$/, "");
     return frac ? `${whole}.${frac}` : whole.toString();
 }
+export function humaniseTreeNode(node, cfg) {
+    if (!node || typeof node !== "object")
+        return node;
+    const known = (token) => !!cfg.token && token === cfg.token;
+    const human = (v) => {
+        // EXPLICIT SHAPE CHECK, because `BigInt("")` is `0n` rather than a throw —
+        // and `BigInt("  ")` is too. A try/catch alone therefore converted an
+        // empty or whitespace cap into "0", which is not a parse failure the
+        // reader can see: "0" is a meaningful budget, and the wrong one. Caught by
+        // its own test, which is the only reason this is not shipping.
+        if (typeof v !== "string" || !/^\d+$/.test(v))
+            return v;
+        try {
+            return fromBaseUnits(BigInt(v), cfg.decimals);
+        }
+        catch {
+            // Still guarded: fromBaseUnits rejects decimals outside its own range,
+            // and a figure the contract produced is a fact worth surfacing
+            // unchanged rather than an exception to swallow.
+            return v;
+        }
+    };
+    const limits = node.limits?.map((l) => known(l.token)
+        ? { ...l, daily_cap: human(l.daily_cap), per_tx_cap: human(l.per_tx_cap), decimals: cfg.decimals }
+        : { ...l, decimals: null, units: "base" });
+    const childCapSum = node.child_cap_sum?.map(([token, amount]) => (known(token) ? [token, human(amount)] : [token, amount]));
+    return {
+        ...node,
+        ...(limits ? { limits } : {}),
+        ...(childCapSum ? { child_cap_sum: childCapSum } : {}),
+    };
+}

package/dist/roles.d.ts

@@ -8,6 +8,7 @@ export declare class RoleSelectionError extends Error {
 }
 export declare function selectRole(cfg: {
     agentKeysPath?: string;
+    vault?: string;
 }, role: string): {
     agentId: string;
     agentKey: string;
@@ -15,6 +16,7 @@ export declare function selectRole(cfg: {
 /** Every role that could actually sign, for listing back to a caller. */
 export declare function listRoles(cfg: {
     agentKeysPath?: string;
+    vault?: string;
 }): RoleCredential[];
 /**
  * EVERY credential in the keyring, named or not.
@@ -36,6 +38,7 @@ export declare function listRoles(cfg: {
  */
 export declare function listAgents(cfg: {
     agentKeysPath?: string;
+    vault?: string;
 }): {
     agentId: string;
     role: string | null;

package/dist/roles.js

@@ -29,11 +29,42 @@ function loadable(path) {
     // never be selected.
     return parsed.filter((e) => e && typeof e.agentId === "string" && typeof e.secret === "string");
 }
+/**
+ * Keyring entries belonging to THIS vault.
+ *
+ * A credential's `agentId` IS the vault account it was issued for. Nothing
+ * filtered on it, so every function here operated on the whole file — every
+ * vault the user has ever created, on either network.
+ *
+ * Measured 2026-11-10 against a mainnet vault: `vault_roles` listed
+ * `rudeisland4178-testnet.fac.floatv4.testnet` and
+ * `work12-testnet-fleet.fac.floatv4.testnet` as that vault's agents. Both are
+ * TESTNET accounts from earlier experiments, and neither has any relationship
+ * to the configured mainnet vault.
+ *
+ * `vault_roles` listing them is a display bug. `selectRole` was worse: asked
+ * for role "root" it would hand `vault_pay` the testnet fleet key to sign a
+ * MAINNET payment. That fails at the chain — the key is not on the vault — but
+ * the tool chose a credential from a different network and the error arrives
+ * with no hint of why.
+ *
+ * `vault` empty means nothing is configured, so there is nothing to scope to
+ * and every entry is returned. That is the `vault_create` case, where the
+ * server legitimately runs with no vault at all.
+ */
+function forVault(cfg) {
+    const entries = loadable(cfg.agentKeysPath ?? ".float/agent-keys.json");
+    if (!cfg.vault)
+        return entries;
+    return entries.filter((e) => e.agentId === cfg.vault);
+}
 export class RoleSelectionError extends Error {
 }
 export function selectRole(cfg, role) {
     const path = cfg.agentKeysPath ?? ".float/agent-keys.json";
-    const entries = loadable(path);
+    // SCOPED. A role name is not unique across vaults — "root" exists in every
+    // one — so an unscoped lookup picks whichever was written first.
+    const entries = forVault(cfg);
     const known = entries
         .map((e) => (typeof e.role === "string" ? e.role : null))
         .filter(Boolean);
@@ -50,7 +81,7 @@ export function selectRole(cfg, role) {
 }
 /** Every role that could actually sign, for listing back to a caller. */
 export function listRoles(cfg) {
-    return loadable(cfg.agentKeysPath ?? ".float/agent-keys.json")
+    return forVault(cfg)
         .filter((e) => typeof e.role === "string")
         .map((e) => ({
         agentId: e.agentId,
@@ -78,7 +109,7 @@ export function listRoles(cfg) {
  * name is genuinely absent and the fix is `vault_add_role`, not a guess.
  */
 export function listAgents(cfg) {
-    return loadable(cfg.agentKeysPath ?? ".float/agent-keys.json").map((e) => ({
+    return forVault(cfg).map((e) => ({
         agentId: e.agentId,
         role: typeof e.role === "string" ? e.role : null,
         nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,

package/dist/server.js

@@ -53,7 +53,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { topUpFor, paymentsAfterTopUp } from "./gas-math.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { fromBaseUnits, toBaseUnits } from "./amounts.js";
+import { fromBaseUnits, humaniseTreeNode, toBaseUnits } from "./amounts.js";
 import { DEFAULT_GAS_TGAS, planAddNode, planAddRole, planBindVirtualAgent, planUnbindVirtualAgent, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, toCliCommand, planSetApprovalThreshold, planApprovePayment, planRejectPayment, planWithdraw, } from "./payloads.js";
 import { accountExists, rpcForNetwork, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
 import { AGENT_NODE_ID, generateAgentKey } from "./agent-key.js";
@@ -292,7 +292,7 @@ WORTH KNOWING
   An implicit account (a 64-character hex id) cannot own a vault at all. Tell the user to use a
   named account rather than retrying.
   Amounts are whole tokens in these tools (1.5 means 1.5 USDC), never base units.`;
-const server = new McpServer({ name: "float", version: "0.6.4" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "float", version: "0.6.5" }, { instructions: INSTRUCTIONS });
 // ----------------------------------------------------------------- reads
 /**
  * Wait for a create to land, and prove the result belongs to the user.
@@ -420,7 +420,12 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
         ],
     });
 });
-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_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => {
+    const tree = (await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {}));
+    return json(Array.isArray(tree)
+        ? tree.map((n) => humaniseTreeNode(n, { token: cfg.token, decimals: cfg.decimals }))
+        : 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.", {
     nodeId: z.number().int().min(0),
     token: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floatonnear/mcp",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "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",