@floatonnear/mcp 0.3.0 → 0.4.0

package/dist/roles.js

@@ -0,0 +1,61 @@
+/**
+ * Picking which agent in a fleet signs a payment.
+ *
+ * WHICH KEY SIGNS *IS* WHICH BUDGET IS CHARGED — the contract resolves the
+ * spending node from the signer (`pubkey_to_node`), never from the request
+ * body. So a wrong choice here does not fail; it succeeds against another
+ * agent's budget and shows up later as a balance nobody can explain.
+ *
+ * This reads the SAME file the adapter reads, and accepts the same entry
+ * shape, because two readers of one keyring that disagree about what counts
+ * as a credential is how an agent ends up "configured" and unreachable.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** Entries that `loadKeyring` would accept, nothing else. */
+function loadable(path) {
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    // THE SAME PREDICATE THE ADAPTER USES. An entry failing it is skipped there
+    // in total silence, so listing it here would advertise an agent that can
+    // never be selected.
+    return parsed.filter((e) => e && typeof e.agentId === "string" && typeof e.secret === "string");
+}
+export class RoleSelectionError extends Error {
+}
+export function selectRole(cfg, role) {
+    const path = cfg.agentKeysPath ?? ".float/agent-keys.json";
+    const entries = loadable(path);
+    const known = entries
+        .map((e) => (typeof e.role === "string" ? e.role : null))
+        .filter(Boolean);
+    const hit = entries.find((e) => e.role === role);
+    if (!hit) {
+        throw new RoleSelectionError(`no agent with role '${role}' in ${path}. ` +
+            `Known roles: ${known.length ? known.join(", ") : "none"}. ` +
+            (entries.length && !known.length
+                ? `${entries.length} credential(s) are loaded but none carries a role — ` +
+                    `they predate roles, so select them by nodeId or add a "role" field.`
+                : `Add one with vault_add_role.`));
+    }
+    return { agentId: hit.agentId, agentKey: hit.secret };
+}
+/** Every role that could actually sign, for listing back to a caller. */
+export function listRoles(cfg) {
+    return loadable(cfg.agentKeysPath ?? ".float/agent-keys.json")
+        .filter((e) => typeof e.role === "string")
+        .map((e) => ({
+        agentId: e.agentId,
+        agentKey: e.secret,
+        role: e.role,
+        nodeId: typeof e.nodeId === "number" ? e.nodeId : undefined,
+    }));
+}

package/dist/rpc.d.ts

@@ -32,6 +32,19 @@ interface RawViewResponse {
  */
 export declare function decodeViewResult<T = unknown>(res: RawViewResponse): T;
 export declare function viewFunction<T = unknown>(rpcUrl: string, contractId: string, methodName: string, args?: unknown): Promise<T>;
+/**
+ * Does this account exist on chain?
+ *
+ * Used before offering to CREATE a vault at a derived address. Getting this
+ * wrong is not cosmetic: the create batch's first action is `CreateAccount`,
+ * so offering an address that is already taken sends the user to a wallet,
+ * takes their signature, and fails only after they have committed.
+ *
+ * Distinguishes "does not exist" from "could not tell". An RPC timeout that
+ * returned `false` would read as a free address, so ONLY the specific
+ * UNKNOWN_ACCOUNT answer counts as absent and anything else throws.
+ */
+export declare function accountExists(rpcUrl: string, accountId: string): Promise<boolean>;
 /** One access key as NEAR reports it. */
 export interface AccessKeyInfo {
     public_key: string;
@@ -43,6 +56,14 @@ export interface AccessKeyInfo {
                 receiver_id: string;
                 method_names: string[];
             };
+        } | {
+            GasKeyFunctionCall: {
+                allowance: string | null;
+                balance: string;
+                receiver_id: string;
+                method_names: string[];
+                num_nonces?: number;
+            };
         };
     };
 }
@@ -56,6 +77,20 @@ export interface AccessKeyInfo {
  * be true.
  */
 export declare function viewAccessKeys(rpcUrl: string, accountId: string): Promise<AccessKeyInfo[]>;
+/** An account's balance and storage, as the chain reports them. */
+export interface AccountView {
+    amount: string;
+    storage_usage: number;
+}
+/**
+ * Read an account's balance and storage.
+ *
+ * Both as the chain reports them: `amount` is the TOTAL, and the storage
+ * stake (`storage_usage * 1e19`) is locked inside it rather than held
+ * separately. Subtracting is the caller's job, and getting that backwards is
+ * how a vault with 0.02 spendable looks like it has 0.12.
+ */
+export declare function viewAccount(rpcUrl: string, accountId: string): Promise<AccountView>;
 export interface AgentCreds {
     agentId: string;
     agentKey: string;
@@ -68,6 +103,22 @@ export interface AgentCreds {
 export declare function requireAgentKey(env: {
     agentId?: string;
     agentKey?: string;
+    /**
+     * Why `NEAR_VAULT_AGENT_KEY_FILE` produced no key, when one was named.
+     *
+     * SEPARATE FROM `agentKey` BEING ABSENT, and it must stay that way. "The
+     * variable is not set" and "the file you pointed it at is broken" are
+     * different problems with different fixes; reporting the second as the first
+     * sends the operator to set something they have already set — and the
+     * quickest way out of that dead end is pasting the key inline, which undoes
+     * the reason the file option exists.
+     */
+    agentKeyError?: string;
+    /**
+     * `account_id` from a `~/.near-credentials`-shaped key file, when the key
+     * came from one. Absent for an inline key or a bare key file.
+     */
+    agentKeyAccountId?: string;
 }): AgentCreds;
 /**
  * A request id the contract will accept.

package/dist/rpc.js

@@ -71,6 +71,39 @@ export async function viewFunction(rpcUrl, contractId, methodName, args = {}) {
         return decodeViewResult({ error: json.error });
     return decodeViewResult(json.result ?? {});
 }
+/**
+ * Does this account exist on chain?
+ *
+ * Used before offering to CREATE a vault at a derived address. Getting this
+ * wrong is not cosmetic: the create batch's first action is `CreateAccount`,
+ * so offering an address that is already taken sends the user to a wallet,
+ * takes their signature, and fails only after they have committed.
+ *
+ * Distinguishes "does not exist" from "could not tell". An RPC timeout that
+ * returned `false` would read as a free address, so ONLY the specific
+ * UNKNOWN_ACCOUNT answer counts as absent and anything else throws.
+ */
+export async function accountExists(rpcUrl, accountId) {
+    const r = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "near-vault-mcp",
+            method: "query",
+            params: { request_type: "view_account", finality: "final", account_id: accountId },
+        }),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${r.status} checking whether ${accountId} exists`);
+    const j = (await r.json());
+    if (j.result)
+        return true;
+    const name = j.error?.cause?.name;
+    if (name === "UNKNOWN_ACCOUNT")
+        return false;
+    throw new Error(`could not determine whether ${accountId} exists: ${name ?? j.error?.message ?? "unknown error"}`);
+}
 /**
  * Every access key on an account, read from the chain.
  *
@@ -98,28 +131,91 @@ export async function viewAccessKeys(rpcUrl, accountId) {
         throw new Error(`access key list failed: ${json.error.message ?? "unknown"}`);
     return json.result?.keys ?? [];
 }
+/**
+ * Read an account's balance and storage.
+ *
+ * Both as the chain reports them: `amount` is the TOTAL, and the storage
+ * stake (`storage_usage * 1e19`) is locked inside it rather than held
+ * separately. Subtracting is the caller's job, and getting that backwards is
+ * how a vault with 0.02 spendable looks like it has 0.12.
+ */
+export async function viewAccount(rpcUrl, accountId) {
+    const r = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "near-vault-mcp",
+            method: "query",
+            params: { request_type: "view_account", finality: "final", account_id: accountId },
+        }),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${rpcUrl} returned HTTP ${r.status}`);
+    const json = (await r.json());
+    if (json.error)
+        throw new Error(`view_account failed: ${json.error.message ?? "unknown"}`);
+    if (!json.result)
+        throw new Error(`view_account returned no result for ${accountId}`);
+    return json.result;
+}
 /**
  * Both halves or neither. Failing here with the variable NAMES beats throwing a
  * TypeError three frames deeper, and beats silently signing with the wrong
  * account.
  */
 export function requireAgentKey(env) {
+    // THE FILE'S OWN FAILURE OUTRANKS EVERY "not set" MESSAGE BELOW. It is the
+    // only one of them that names a cause, and once a path is involved the
+    // missing-variable advice is actively misleading.
+    if (!env.agentKey && env.agentKeyError) {
+        throw new Error(`Paying needs the agent key, and the key file could not be read. ` +
+            `${env.agentKeyError} Fix the path or the file — or unset the _FILE variable ` +
+            `to fall back to an inline NEAR_VAULT_AGENT_KEY.`);
+    }
     // Name EVERY missing variable, not just the first. A message that reports
     // half the problem buys a second failed attempt.
     if (!env.agentId && !env.agentKey) {
-        throw new Error("Paying requires NEAR_VAULT_AGENT_ID and NEAR_VAULT_AGENT_KEY, and neither is set. " +
+        throw new Error("Paying requires NEAR_VAULT_AGENT_ID and a key, and neither is set. " +
+            "The key can be NEAR_VAULT_AGENT_KEY (inline) or NEAR_VAULT_AGENT_KEY_FILE " +
+            "(a path to a ~/.near-credentials-shaped JSON file, or a bare key file) — " +
+            "prefer the file, since an inline key is printed by any read of the config. " +
             "Reads and payload planning work without them; only paying needs them. " +
-            "The key must be the restricted one issued by create_agent_account — never a " +
+            "The key must be a RESTRICTED one, from a VIRTUAL AGENT — never a " +
             "full-access key.");
     }
     if (!env.agentId) {
         throw new Error("NEAR_VAULT_AGENT_ID is not set, so there is no agent account to pay from.");
     }
     if (!env.agentKey) {
-        throw new Error("NEAR_VAULT_AGENT_KEY is not set. This must be the restricted key issued by " +
-            "create_agent_account — it can call only request_payment on the vault, cannot " +
+        throw new Error("No agent key is set: use NEAR_VAULT_AGENT_KEY_FILE (a path — preferred, since " +
+            "an inline key is printed by any read of the config) or NEAR_VAULT_AGENT_KEY. " +
+            "This must be a VIRTUAL AGENT's key, bound " +
+            "with bind_virtual_agent and installed as a NEP-611 gas key on the vault — it can call only request_payment on the vault, cannot " +
             "call other contracts, and cannot attach a deposit. Never put a full-access key here.");
     }
+    /**
+     * THE KEY FILE AND NEAR_VAULT_AGENT_ID MUST NAME THE SAME ACCOUNT.
+     *
+     * Which key signs *is* which budget is charged — the contract resolves the
+     * spending node from the signer, never from the request body. So a key used
+     * under the wrong account id does not get rejected locally; it goes to chain
+     * and fails with NOT_VIRTUAL_AGENT, which reads as a binding bug and sends
+     * the reader to the contract rather than to their config.
+     *
+     * No mismatch is legitimate. A virtual agent's key is a NEP-611 gas key ON
+     * the vault, so it signs AS the vault, and a credentials file for it names
+     * the vault. A file naming some other account holds some other account's key
+     * — most often the owner's full-access one, which must never be used here.
+     */
+    if (env.agentKeyAccountId && env.agentKeyAccountId !== env.agentId) {
+        throw new Error(`the key file belongs to ${env.agentKeyAccountId}, but NEAR_VAULT_AGENT_ID is ` +
+            `${env.agentId}. A key signs as the account it was issued for, and the vault ` +
+            `resolves the spending budget from the signer — so this pairing cannot pay. ` +
+            `Point NEAR_VAULT_AGENT_ID at ${env.agentKeyAccountId}, or use the key file ` +
+            `for ${env.agentId}. A virtual agent's key is a gas key ON the vault, so for ` +
+            `one it is the vault's own id.`);
+    }
     return { agentId: env.agentId, agentKey: env.agentKey };
 }
 /**

package/dist/server.d.ts

@@ -10,12 +10,38 @@
  *   PLAN tools      emit UNSIGNED payloads for the human's wallet; this
  *                   server never signs anything that changes policy
  *
+ *   CREATE tool     needs no key and no vault. It reads the factory, works out
+ *                   the address and the cost, and hands back a URL the user
+ *                   approves in their own wallet.
+ *
  * Configure with:
- *   NEAR_VAULT_CONTRACT        required
+ *   NEAR_VAULT_CONTRACT        required by every tool EXCEPT vault_create
  *   NEAR_VAULT_RPC_URL         default https://test.rpc.fastnear.com
  *   NEAR_VAULT_TOKEN           default token for pay/budget calls
  *   NEAR_VAULT_TOKEN_DECIMALS  default 6
- *   NEAR_VAULT_AGENT_ID        only needed to PAY
- *   NEAR_VAULT_AGENT_KEY       only needed to PAY. The restricted key.
+ *   NEAR_VAULT_AGENT_ID        only needed to PAY. Taken from the key file's
+ *                              `account_id` when one is given.
+ *   NEAR_VAULT_AGENT_KEY       only needed to PAY. The restricted key, inline.
+ *   NEAR_VAULT_AGENT_KEY_FILE  PREFERRED over the inline value above: a PATH to
+ *                              a ~/.near-credentials-shaped JSON file
+ *                              ({"account_id","public_key","private_key"}) or a
+ *                              bare key file. A path is not a secret, so the
+ *                              routine act of reading this config to see which
+ *                              vault is wired up stops printing a live private
+ *                              key into a terminal and an agent transcript.
+ *                              Same reason NEAR CLI signing in this repo uses
+ *                              `sign-with-access-key-file`. If both are set the
+ *                              FILE wins and the inline one is reported as
+ *                              ignored on stderr.
+ *   NEAR_VAULT_NETWORK         mainnet | testnet, default testnet
+ *   NEAR_VAULT_FACTORY         only needed to CREATE. No mainnet default
+ *                              exists on purpose — guessing it wrong would
+ *                              send a real deposit somewhere unverified.
+ *   NEAR_VAULT_APP_URL         only needed to CREATE, default
+ *                              https://app.usefloat.xyz
+ *
+ * A user with NO vault can therefore run this server with nothing configured,
+ * call `vault_create`, and be onboarded — which is the point. Every other tool
+ * reports that NEAR_VAULT_CONTRACT is unset rather than guessing one.
  */
 export {};