@floatonnear/mcp 0.6.3 → 0.6.4

package/dist/roles.d.ts

@@ -16,3 +16,28 @@ export declare function selectRole(cfg: {
 export declare function listRoles(cfg: {
     agentKeysPath?: 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;
+}): {
+    agentId: string;
+    role: string | null;
+    nodeId?: number;
+}[];

package/dist/roles.js

@@ -59,3 +59,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 loadable(cfg.agentKeysPath ?? ".float/agent-keys.json").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
@@ -51,11 +55,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { fromBaseUnits, 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.4" }, { 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,11 +410,11 @@ 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.`,
         ],
@@ -435,7 +510,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.4",
   "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",