@floatonnear/mcp 0.5.0 → 0.6.1

package/dist/create.d.ts

@@ -109,10 +109,24 @@ export declare const GAS_RESERVATION_YOCTO: bigint;
 /**
  * Known factories.
  *
- * MAINNET IS DELIBERATELY ABSENT until one is deployed and verified. A wrong
- * default here does not fail safely: it sends a real user with real NEAR to
- * sign a 3.4 NEAR deposit into an account we do not control. Absent means the
- * tool asks, which is the correct behaviour for a value nobody has measured.
+ * MAINNET WAS DELIBERATELY ABSENT until one was deployed AND VERIFIED, because
+ * a wrong default here does not fail safely: it sends a real user with real
+ * NEAR to sign a ~3.4 NEAR deposit into an account we do not control.
+ *
+ * That precondition is now met. `usefloat.near` was registered on 2026-11-09
+ * (tx 2Gfh9H5T1VhEZ465NJ15CnuxFZpyMgsjchY66Lgsvntm) and the factory deployed
+ * into it, verified against the chain rather than against the deploy's own
+ * report:
+ *
+ *   local sha256                  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   chain code_hash (b58 -> hex)  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   deployed bytes fetched        163,525 — byte-for-byte equal to the artifact
+ *   get_config                    network mainnet, not paused, deposit 0.1
+ *   vault_id_for(test015.near)    test015-near.usefloat.near
+ *
+ * The name is TOP-LEVEL on purpose (DECISIONS.md 2026-11-08): it is embedded
+ * in every user's vault address permanently, because a vault is a sub-account
+ * of its factory, and `float.near` was already taken.
  */
 export declare const FACTORY_BY_NETWORK: Record<string, string | undefined>;
 export interface CreatePlanInput {

package/dist/create.js

@@ -109,14 +109,28 @@ export const GAS_RESERVATION_YOCTO = CREATE_GAS_TGAS * 10n ** 12n * 10n ** 9n;
 /**
  * Known factories.
  *
- * MAINNET IS DELIBERATELY ABSENT until one is deployed and verified. A wrong
- * default here does not fail safely: it sends a real user with real NEAR to
- * sign a 3.4 NEAR deposit into an account we do not control. Absent means the
- * tool asks, which is the correct behaviour for a value nobody has measured.
+ * MAINNET WAS DELIBERATELY ABSENT until one was deployed AND VERIFIED, because
+ * a wrong default here does not fail safely: it sends a real user with real
+ * NEAR to sign a ~3.4 NEAR deposit into an account we do not control.
+ *
+ * That precondition is now met. `usefloat.near` was registered on 2026-11-09
+ * (tx 2Gfh9H5T1VhEZ465NJ15CnuxFZpyMgsjchY66Lgsvntm) and the factory deployed
+ * into it, verified against the chain rather than against the deploy's own
+ * report:
+ *
+ *   local sha256                  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   chain code_hash (b58 -> hex)  ee925937c7b90771c477dd5e0a36770cd2c9654e…
+ *   deployed bytes fetched        163,525 — byte-for-byte equal to the artifact
+ *   get_config                    network mainnet, not paused, deposit 0.1
+ *   vault_id_for(test015.near)    test015-near.usefloat.near
+ *
+ * The name is TOP-LEVEL on purpose (DECISIONS.md 2026-11-08): it is embedded
+ * in every user's vault address permanently, because a vault is a sub-account
+ * of its factory, and `float.near` was already taken.
  */
 export const FACTORY_BY_NETWORK = {
     testnet: "fac.floatv4.testnet",
-    mainnet: undefined,
+    mainnet: "usefloat.near",
 };
 /** yoctoNEAR -> a NEAR string, without floating point. */
 export function yoctoToNear(y, dp = 5) {

package/dist/rpc.d.ts

@@ -17,6 +17,34 @@
  * https://docs.near.org/api/rpc/providers
  */
 export declare const DEFAULT_RPC_URL = "https://test.rpc.fastnear.com";
+/**
+ * The RPC to use for a given NETWORK.
+ *
+ * WHY THIS EXISTS. `vault_create` takes a `network` argument, resolved the
+ * right factory for it, and then asked `cfg.rpcUrl` — a single value
+ * defaulting to testnet. So a user asking for a mainnet vault got:
+ *
+ *   account usefloat.near does not exist while viewing
+ *
+ * about an account that demonstrably does exist. The factory was right and
+ * the chain was wrong, which reads as "the factory is broken" rather than
+ * "you asked the wrong network". Shipped in 0.6.0 and found by driving the
+ * published package instead of reading its diff.
+ */
+export declare const RPC_BY_NETWORK: Record<string, string>;
+/**
+ * Pick an RPC for `net`, honouring an operator override ONLY where it applies.
+ *
+ * An explicit NEAR_VAULT_RPC_URL is configured for ONE network — whichever the
+ * operator set NEAR_VAULT_NETWORK to. Applying it to the other network is the
+ * same bug in a new place: it would send a mainnet question to a testnet
+ * endpoint and report the answer as fact. So the override wins only when the
+ * requested network is the one it was configured for.
+ */
+export declare function rpcForNetwork(net: string, opts?: {
+    configuredNetwork?: string;
+    override?: string;
+}): string;
 export declare function encodeArgs(args: unknown): string;
 interface RawViewResponse {
     result?: number[];

package/dist/rpc.js

@@ -18,6 +18,38 @@ import { randomUUID } from "node:crypto";
  * https://docs.near.org/api/rpc/providers
  */
 export const DEFAULT_RPC_URL = "https://test.rpc.fastnear.com";
+/**
+ * The RPC to use for a given NETWORK.
+ *
+ * WHY THIS EXISTS. `vault_create` takes a `network` argument, resolved the
+ * right factory for it, and then asked `cfg.rpcUrl` — a single value
+ * defaulting to testnet. So a user asking for a mainnet vault got:
+ *
+ *   account usefloat.near does not exist while viewing
+ *
+ * about an account that demonstrably does exist. The factory was right and
+ * the chain was wrong, which reads as "the factory is broken" rather than
+ * "you asked the wrong network". Shipped in 0.6.0 and found by driving the
+ * published package instead of reading its diff.
+ */
+export const RPC_BY_NETWORK = {
+    testnet: "https://test.rpc.fastnear.com",
+    mainnet: "https://free.rpc.fastnear.com",
+};
+/**
+ * Pick an RPC for `net`, honouring an operator override ONLY where it applies.
+ *
+ * An explicit NEAR_VAULT_RPC_URL is configured for ONE network — whichever the
+ * operator set NEAR_VAULT_NETWORK to. Applying it to the other network is the
+ * same bug in a new place: it would send a mainnet question to a testnet
+ * endpoint and report the answer as fact. So the override wins only when the
+ * requested network is the one it was configured for.
+ */
+export function rpcForNetwork(net, opts = {}) {
+    if (opts.override && net === opts.configuredNetwork)
+        return opts.override;
+    return RPC_BY_NETWORK[net] ?? DEFAULT_RPC_URL;
+}
 export function encodeArgs(args) {
     // Explicit utf8: a memo is free text, goes on-chain, and a latin-1
     // truncation here would corrupt it silently.

package/dist/server.js

@@ -49,7 +49,7 @@ 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, DEFAULT_RPC_URL, newRequestId, requireAgentKey, viewAccessKeys, viewAccount, viewFunction, } from "./rpc.js";
+import { accountExists, rpcForNetwork, DEFAULT_RPC_URL, 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";
@@ -183,7 +183,57 @@ 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.5.0" });
+/**
+ * WHAT THE AGENT READS BEFORE IT TOUCHES A TOOL.
+ *
+ * 23 tool descriptions tell a model what each CALL does and nothing about what
+ * the product IS, when to reach for it, or which of the three trust lanes a
+ * given task belongs in. The MCP `instructions` field is the one place that
+ * can say so, and it is injected into the client's system prompt — which is
+ * why servers that set it feel like the agent "already understands the
+ * project", and why ours did not.
+ *
+ * Kept to what a model cannot infer from a tool list: the workflow order, the
+ * fact that this server never signs policy, and the three refusals that are
+ * answers rather than errors. Everything that IS inferable from a schema is
+ * left to the schema.
+ */
+const INSTRUCTIONS = `Float gives an AI agent a spending budget that a smart contract enforces, on NEAR.
+The agent's key can call exactly one method on exactly one contract: it cannot move tokens
+directly, cannot raise its own limit, and cannot reach owner functions. Those are protocol-level
+key restrictions, not policy checks.
+
+Reach for these tools when the user wants to pay for something from an agent budget, set up or
+change spending limits, see what an agent has spent, or wind a vault down.
+
+THREE LANES, and the difference is the whole design:
+  READ    vault_tree, vault_budget, vault_config, vault_roles, vault_request. No key, no risk.
+  PAY     vault_pay. The ONLY tool that signs, and only with a restricted agent key.
+  PLAN    vault_plan_*. These RETURN AN UNSIGNED PAYLOAD. This server never signs a policy
+          change; the human approves it in their own wallet. Do not describe a plan as done.
+
+WORKFLOW
+  1. No vault yet? vault_create. It needs no key and no existing vault, and returns a URL the
+     user approves in their own wallet. Never ask anyone for a private key or seed phrase.
+  2. Look before acting: vault_tree shows the budget shape, vault_budget what is left today.
+  3. Pay with vault_pay. Check the result: a refusal is a recorded outcome, not an exception.
+  4. Change policy with a vault_plan_* tool, then hand the payload to the user to sign.
+  5. Winding down is a CLI job, not a tool: npx @floatonnear/float-exit. It returns the tokens,
+     the gas-key balances and the storage deposit. vault_teardown_report says what is recoverable.
+
+REFUSALS ARE ANSWERS. Report the reason code, do not retry blindly:
+  DAILY_BUDGET         this agent's own cap is spent.
+  PARENT_DAILY_BUDGET  a SIBLING drained the shared pool; this agent's own cap may look free.
+  PER_TX_LIMIT         one payment was too large; splitting it may still be refused by the cap.
+  NO_RECIPIENTS_SET    the node pays nobody yet; that is an owner decision, via vault_plan_set_recipients.
+
+WORTH KNOWING
+  Budgets are hierarchical: a payment charges every ancestor, so a vault-wide ceiling holds even
+  when a child's cap looks free.
+  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.1" }, { instructions: INSTRUCTIONS });
 // ----------------------------------------------------------------- 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.", {
@@ -302,7 +352,14 @@ server.tool("vault_create", "For a user who has NO vault yet. Works out where th
             `NEAR_VAULT_FACTORY. There is deliberately no built-in mainnet default: ` +
             `guessing it wrong would send a real deposit somewhere unverified.`);
     }
-    const rpc = cfg.rpcUrl;
+    // THE RPC MUST FOLLOW THE NETWORK, not the process's default. 0.6.0
+    // resolved the right factory for `net` and then asked the testnet RPC
+    // about it, so a mainnet request answered "usefloat.near does not exist"
+    // about an account that does.
+    const rpc = rpcForNetwork(net, {
+        configuredNetwork: cfg.network,
+        override: process.env.NEAR_VAULT_RPC_URL,
+    });
     // Only ask the factory to derive an id when there IS an owner. With none,
     // the address is decided by whichever wallet signs, and inventing one here
     // would print a plausible address next to a real deposit figure.

package/package.json

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