@floatonnear/mcp 0.6.3 → 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,4 +16,31 @@ 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.
+ *
+ * `listRoles` filters to entries carrying a `role`, which is right for
+ * SELECTION — you cannot pick by a name that does not exist. It is wrong for
+ * REPORTING, and `vault_roles` used it for reporting.
+ *
+ * `vault_create({ bindAgent: true })` calls `generateAgentKey({ vault })` with
+ * no role, so `JSON.stringify` drops the field and the entry is invisible to
+ * `listRoles`. Measured 2026-11-10: a vault with a funded, correctly-pinned
+ * gas key and a live agent node reported `vault_roles` -> `[]`, which reads as
+ * "you have no agents" rather than "you have one with no name". The user then
+ * cannot tell an empty keyring from a working unnamed agent, and the obvious
+ * next move — bind another — is the wrong one.
+ *
+ * Returns `role: null` for those rather than inventing a name, because the
+ * name is genuinely absent and the fix is `vault_add_role`, not a guess.
+ */
+export declare function listAgents(cfg: {
+    agentKeysPath?: string;
+    vault?: string;
+}): {
+    agentId: string;
+    role: string | null;
+    nodeId?: number;
+}[];

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,
@@ -59,3 +90,28 @@ export function listRoles(cfg) {
         nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
     }));
 }
+/**
+ * EVERY credential in the keyring, named or not.
+ *
+ * `listRoles` filters to entries carrying a `role`, which is right for
+ * SELECTION — you cannot pick by a name that does not exist. It is wrong for
+ * REPORTING, and `vault_roles` used it for reporting.
+ *
+ * `vault_create({ bindAgent: true })` calls `generateAgentKey({ vault })` with
+ * no role, so `JSON.stringify` drops the field and the entry is invisible to
+ * `listRoles`. Measured 2026-11-10: a vault with a funded, correctly-pinned
+ * gas key and a live agent node reported `vault_roles` -> `[]`, which reads as
+ * "you have no agents" rather than "you have one with no name". The user then
+ * cannot tell an empty keyring from a working unnamed agent, and the obvious
+ * next move — bind another — is the wrong one.
+ *
+ * Returns `role: null` for those rather than inventing a name, because the
+ * name is genuinely absent and the fix is `vault_add_role`, not a guess.
+ */
+export function listAgents(cfg) {
+    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.d.ts

@@ -16,7 +16,11 @@
  *
  * Configure with:
  *   NEAR_VAULT_CONTRACT        required by every tool EXCEPT vault_create
- *   NEAR_VAULT_RPC_URL         default https://test.rpc.fastnear.com
+ *   NEAR_VAULT_RPC_URL         OPTIONAL. Defaults to the RPC for
+ *                              NEAR_VAULT_NETWORK — free.rpc.fastnear.com on
+ *                              mainnet, test.rpc.fastnear.com on testnet. It
+ *                              used to default to the testnet URL regardless,
+ *                              so every mainnet install read the wrong chain.
  *   NEAR_VAULT_TOKEN           default token for pay/budget calls
  *   NEAR_VAULT_TOKEN_DECIMALS  default 6
  *   NEAR_VAULT_AGENT_ID        only needed to PAY. Taken from the key file's

package/dist/server.js

@@ -16,7 +16,11 @@
  *
  * Configure with:
  *   NEAR_VAULT_CONTRACT        required by every tool EXCEPT vault_create
- *   NEAR_VAULT_RPC_URL         default https://test.rpc.fastnear.com
+ *   NEAR_VAULT_RPC_URL         OPTIONAL. Defaults to the RPC for
+ *                              NEAR_VAULT_NETWORK — free.rpc.fastnear.com on
+ *                              mainnet, test.rpc.fastnear.com on testnet. It
+ *                              used to default to the testnet URL regardless,
+ *                              so every mainnet install read the wrong chain.
  *   NEAR_VAULT_TOKEN           default token for pay/budget calls
  *   NEAR_VAULT_TOKEN_DECIMALS  default 6
  *   NEAR_VAULT_AGENT_ID        only needed to PAY. Taken from the key file's
@@ -49,13 +53,13 @@ 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, DEFAULT_RPC_URL, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
+import { accountExists, rpcForNetwork, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
 import { AGENT_NODE_ID, generateAgentKey } from "./agent-key.js";
 import { resolveKeySource } from "./key-file.js";
 import { dirname } from "node:path";
-import { listRoles, selectRole } from "./roles.js";
+import { listAgents, listRoles, selectRole } from "./roles.js";
 /**
  * A decimal NEAR string to yoctoNEAR, without floating point.
  *
@@ -114,9 +118,46 @@ for (const err of [agentKeySource.error, quoteSignerSource.error]) {
     if (err)
         console.error(`float: ${err}`);
 }
+/**
+ * The network, resolved BEFORE `cfg` so the RPC can follow it.
+ *
+ * It used to be read inside the object literal, which meant `rpcUrl` could not
+ * see it and fell back to a constant. See below.
+ */
+const NETWORK = process.env.NEAR_VAULT_NETWORK ?? "testnet";
 const cfg = {
     vault: process.env.NEAR_VAULT_CONTRACT ?? "",
-    rpcUrl: process.env.NEAR_VAULT_RPC_URL ?? DEFAULT_RPC_URL,
+    /**
+     * THE RPC FOLLOWS THE NETWORK. It did not, and that broke every mainnet
+     * install.
+     *
+     * This was `process.env.NEAR_VAULT_RPC_URL ?? DEFAULT_RPC_URL`, and
+     * `DEFAULT_RPC_URL` is the TESTNET endpoint. So a user who set
+     * `NEAR_VAULT_NETWORK=mainnet` — the documented way to be on mainnet — and
+     * did not also happen to set `NEAR_VAULT_RPC_URL` had all fourteen tools
+     * that use `cfg.rpcUrl` querying TESTNET for a mainnet vault. Reads answered
+     * "account does not exist" about an account holding 3.35 NEAR, and
+     * `vault_pay` would have submitted a real payment to the wrong chain.
+     *
+     * Measured 2026-11-10 on test015-near.usefloat.near: `vault_config` and
+     * `vault_tree` reported the vault missing while `vault_await_create` read
+     * its config fine — the two tools differ only in that `vault_create` and
+     * `vault_await_create` call `rpcForNetwork()` and everything else took this
+     * constant.
+     *
+     * THAT ASYMMETRY ALSO DEFEATED THE DIAGNOSIS. The testnet theory was correct
+     * and was "refuted" by testing it with `vault_await_create`, the one tool
+     * immune to the bug — so the right answer was discarded on the strength of a
+     * check that could not fail. Pick the probe that exercises the broken path,
+     * not the convenient one.
+     *
+     * `rpcForNetwork` honours `NEAR_VAULT_RPC_URL` only when it applies to the
+     * network in play, which is the behaviour `vault_create` already relied on.
+     */
+    rpcUrl: rpcForNetwork(NETWORK, {
+        configuredNetwork: NETWORK,
+        override: process.env.NEAR_VAULT_RPC_URL,
+    }),
     token: process.env.NEAR_VAULT_TOKEN ?? "",
     decimals: Number(process.env.NEAR_VAULT_TOKEN_DECIMALS ?? "6"),
     // The credentials file carries the account as well as the key, so one path
@@ -126,7 +167,7 @@ const cfg = {
     agentKey: agentKeySource.secret,
     agentKeyError: agentKeySource.error,
     agentKeyAccountId: agentKeySource.accountId,
-    network: process.env.NEAR_VAULT_NETWORK ?? "testnet",
+    network: NETWORK,
     // Onboarding only. Both have safe defaults and neither is needed by any
     // tool that touches an existing vault.
     factory: process.env.NEAR_VAULT_FACTORY,
@@ -251,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.3" }, { 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.
@@ -275,7 +316,10 @@ const server = new McpServer({ name: "float", version: "0.6.3" }, { instructions
  * after a write can be a whole transaction behind.
  */
 server.tool("vault_await_create", "After the user signs the create link, confirm the vault is live and VERIFY IT IS THEIRS. Reads the chain, so it needs no key. Call this instead of asking the user to paste their vault id back — vault_create already told you the address.", {
-    vault: z.string().describe("the derived vault id, from vault_create's `confirm.vault`"),
+    vault: z
+        .string()
+        .optional()
+        .describe("the derived vault id, from vault_create's `confirm.vault`. OMIT IT if the user already created their vault and you never built the link — it is derived from `owner` via the factory's own vault_id_for view."),
     owner: z.string().describe("who it must belong to — compared against the vault's own get_config.owner"),
     network: z.enum(["mainnet", "testnet"]).optional(),
     timeoutSeconds: z
@@ -291,10 +335,41 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
         configuredNetwork: cfg.network,
         override: process.env.NEAR_VAULT_RPC_URL,
     });
+    // DERIVE IT WHEN THE CALLER HAS NO LINK TO QUOTE.
+    //
+    // A user who says "I already created it" never gave this server a plan to
+    // read `confirm.vault` out of, and does not know their vault id — it is
+    // derived, not chosen. Requiring it here left the agent with only one tool
+    // that knows the derivation: `vault_create`. Measured 2026-11-10, that is
+    // exactly what an agent did, and `vault_create` THREW — correctly —
+    // "already exists and test015.near owns it". The agent then reported that
+    // refusal to the user as "Confirmed ✅". It reached the right answer by
+    // reinterpreting an error, which is luck, not a workflow.
+    //
+    // So adoption gets a first-class path: `owner` alone is enough. The
+    // derivation comes from the factory's `vault_id_for` view, the same single
+    // source `buildCreatePlan` uses and deliberately does not reimplement.
+    let target = vault;
+    if (!target) {
+        const fac = cfg.factory ?? FACTORY_BY_NETWORK[net];
+        if (!fac) {
+            return text(`No factory is configured for ${net}, so the vault id cannot be derived. ` +
+                `Pass \`vault\` directly, or set NEAR_VAULT_FACTORY.`);
+        }
+        const derived = await viewFunction(rpc, fac, "vault_id_for", {
+            owner,
+        }).catch(() => null);
+        if (!derived) {
+            return text(`${fac} could not derive a vault id for ${owner} on ${net}. Either the ` +
+                `owner id is wrong, or it has no legal derived id (an implicit account ` +
+                `has none — the derived name exceeds 64 characters).`);
+        }
+        target = derived;
+    }
     const deadline = Date.now() + (timeoutSeconds ?? 90) * 1000;
     let appeared = false;
     for (;;) {
-        if (await accountExists(rpc, vault).catch(() => false)) {
+        if (await accountExists(rpc, target).catch(() => false)) {
             appeared = true;
             break;
         }
@@ -305,29 +380,29 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
     if (!appeared) {
         return json({
             status: "NOT_YET",
-            vault,
-            instruction: `${vault} does not exist yet. That is not a failure — the user may not have ` +
+            vault: target,
+            instruction: `${target} does not exist yet. That is not a failure — the user may not have ` +
                 `signed, or may have cancelled. Ask whether they approved it, and call this ` +
                 `again. Do NOT tell them the vault is created.`,
         });
     }
     // THE OWNER READ IS THE POINT. Getting here only proves an account exists.
-    const config = await viewFunction(rpc, vault, "get_config", {}).catch(() => null);
+    const config = await viewFunction(rpc, target, "get_config", {}).catch(() => null);
     if (!config || typeof config.owner !== "string") {
         return json({
             status: "UNVERIFIED",
-            vault,
-            instruction: `${vault} exists but its get_config could not be read, so whether it is ${owner}'s ` +
+            vault: target,
+            instruction: `${target} exists but its get_config could not be read, so whether it is ${owner}'s ` +
                 `is UNKNOWN — not assumed. It may not be a Float vault at all. Do not point an ` +
-                `agent at it until this is resolved: near view ${vault} get_config`,
+                `agent at it until this is resolved: near view ${target} get_config`,
         });
     }
     if (config.owner !== owner) {
         return json({
             status: "NOT_YOURS",
-            vault,
+            vault: target,
             actualOwner: config.owner,
-            instruction: `${vault} exists but is owned by ${config.owner}, NOT ${owner}. The vault id ` +
+            instruction: `${target} exists but is owned by ${config.owner}, NOT ${owner}. The vault id ` +
                 `derivation is not injective, so a different account can hold this address — ` +
                 `whoever created it first. Do NOT configure anything against it. Create one ` +
                 `under a label instead, which lands on a different address.`,
@@ -335,17 +410,22 @@ server.tool("vault_await_create", "After the user signs the create link, confirm
     }
     return json({
         status: "LIVE",
-        vault,
+        vault: target,
         owner: config.owner,
         config,
         nextSteps: [
-            `Set NEAR_VAULT_CONTRACT=${vault} so every other tool reads this vault.`,
+            `Set NEAR_VAULT_CONTRACT=${target} so every other tool reads this vault.`,
             `vault_tree shows the budget; vault_budget shows what is left today.`,
             `Nothing can spend from it until an agent is bound with a budget — vault_add_role.`,
         ],
     });
 });
-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(),
@@ -435,7 +515,24 @@ server.tool("vault_add_role", "Add a NEW departmental agent to an existing vault
         ],
     });
 });
-server.tool("vault_roles", "List the agents this server can sign as, by role. Use it before vault_pay when a vault has more than one agent — the signing key decides which budget is charged. No key material is returned.", {}, async () => json(listRoles(cfg).map((r) => ({ role: r.role, nodeId: r.nodeId, agentId: r.agentId }))));
+server.tool("vault_roles", "List the agents this server can sign as, by role. Use it before vault_pay when a vault has more than one agent — the signing key decides which budget is charged. No key material is returned.", {}, async () => json(
+// `listAgents`, NOT `listRoles`. The latter filters to entries carrying a
+// role, which is correct for SELECTION and wrong for REPORTING: a
+// creation-time agent from `bindAgent` has no role, so a working vault
+// with a funded gas key reported `[]` — indistinguishable from having no
+// agent at all, and the obvious next move is then the wrong one.
+listAgents(cfg).map((r) => ({
+    role: r.role,
+    nodeId: r.nodeId,
+    agentId: r.agentId,
+    ...(r.role === null
+        ? {
+            note: "No role name — created by vault_create({bindAgent:true}), which does not " +
+                "name one. It can still sign; vault_pay selects it by nodeId or as the only " +
+                "credential. Give it a name with vault_add_role if you want several agents.",
+        }
+        : {}),
+}))));
 // ------------------------------------------------------------- onboarding
 server.tool("vault_create", "For a user who has NO vault yet. Works out where their vault will live, exactly what it costs to create, and returns a URL they approve in their own wallet. Needs no key and no existing vault — this is the only tool that works before NEAR_VAULT_CONTRACT is set. This server never signs it.", {
     owner: z

package/package.json

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