@floatonnear/mcp 0.0.0-stage → 0.1.1

package/dist/sign.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The ONLY place in this server that touches a key.
+ *
+ * It signs exactly one method — `request_payment` — with the restricted key
+ * issued by `create_agent_account`. That key is cryptographically incapable of
+ * doing anything else: its `receiver_id` is the vault, its `method_names` is
+ * `["request_payment"]`, and a NEAR function-call key cannot attach a deposit
+ * at all. So the worst a compromised copy of this server can do is make
+ * payments the vault's on-chain policy already permits.
+ *
+ * Owner methods are deliberately NOT here. They are emitted as unsigned
+ * payloads (see payloads.ts) for the human to approve in their own wallet,
+ * which keeps this server out of the trust path for anything that changes
+ * policy — the property that distinguishes the design from a custodial agent
+ * wallet.
+ */
+/**
+ * Fee and ordering fields for a Base-routed payment. Decimal strings.
+ *
+ * There is no `nonce`. The CONTRACT allocates it, because it is part of the
+ * signed payload and a caller cannot choose one safely: two payments in the
+ * same block read the same chain state, sign for the same nonce, and one is
+ * rejected AFTER its NEAR reservation has been consumed. The contract is the
+ * only place that sees every Base signature in a serial order.
+ */
+/**
+ * The contract's `route` argument.
+ *
+ * Note what is NOT here: no payload, no destination, no amount. For a
+ * cross-chain payment the contract transfers to the quote's deposit address
+ * and checks the allowlist against the final payee; nothing a caller passes
+ * can redirect where value ends up. If this type ever grows a `payload`
+ * field, that property is gone.
+ *
+ * A cross-chain payment is an ordinary NEP-141 transfer to a solver's
+ * deposit address — no derived address, no ETH to fund, no nonce.
+ */
+export type RouteArg = "near_direct" | {
+    intents: {
+        deposit_address: string;
+        quote_deadline_ns: string;
+        signature: string;
+    };
+};
+export declare function buildRoute(rail: "near"): RouteArg;
+export declare function buildRoute(rail: "intents", intents: IntentsRouteFields): RouteArg;
+/** Fields of a cross-chain route, all produced by the quote signer. */
+export interface IntentsRouteFields {
+    depositAddress: string;
+    quoteDeadlineNs: string;
+    /** base64 ed25519 over borsh(QuoteBinding). See quote.ts. */
+    signature: string;
+}
+export interface PayArgs {
+    rpcUrl: string;
+    vault: string;
+    agentId: string;
+    agentKey: string;
+    requestId: string;
+    token: string;
+    /** Base units. Already scaled by amounts.toBaseUnits. */
+    amount: bigint;
+    recipient: string;
+    memo: string;
+    gasTgas: number;
+    /** Omitted means the NEAR rail, matching the contract's `Option<Route>`. */
+    route?: RouteArg;
+}
+export declare function sendRequestPayment(a: PayArgs): Promise<unknown>;

package/dist/sign.js

@@ -0,0 +1,72 @@
+/**
+ * The ONLY place in this server that touches a key.
+ *
+ * It signs exactly one method — `request_payment` — with the restricted key
+ * issued by `create_agent_account`. That key is cryptographically incapable of
+ * doing anything else: its `receiver_id` is the vault, its `method_names` is
+ * `["request_payment"]`, and a NEAR function-call key cannot attach a deposit
+ * at all. So the worst a compromised copy of this server can do is make
+ * payments the vault's on-chain policy already permits.
+ *
+ * Owner methods are deliberately NOT here. They are emitted as unsigned
+ * payloads (see payloads.ts) for the human to approve in their own wallet,
+ * which keeps this server out of the trust path for anything that changes
+ * policy — the property that distinguishes the design from a custodial agent
+ * wallet.
+ */
+import { Account, JsonRpcProvider, KeyPair, KeyPairSigner } from "near-api-js";
+/** Must match AGENT_ALLOWED_METHOD in the contract; pinned by constants.test.ts. */
+const ALLOWED_METHOD = "request_payment";
+export function buildRoute(rail, intents) {
+    if (rail === "near")
+        return "near_direct";
+    if (!intents) {
+        throw new Error("rail 'intents' requires depositAddress, quoteDeadlineNs and signature");
+    }
+    if (!/^[0-9]+$/.test(intents.quoteDeadlineNs)) {
+        // U64 crosses the ABI as a decimal string; a JSON number loses precision
+        // above 2^53 and a nanosecond deadline is far past that.
+        throw new Error(`quoteDeadlineNs must be a decimal string, got ${intents.quoteDeadlineNs}`);
+    }
+    if (!intents.depositAddress) {
+        // An empty deposit address is what a DRY quote returns. Sending one would
+        // transfer real funds to "", which the token contract rejects only after
+        // the vault has already reserved the budget.
+        throw new Error("depositAddress is empty — a dry quote cannot be paid");
+    }
+    return {
+        intents: {
+            deposit_address: intents.depositAddress,
+            quote_deadline_ns: intents.quoteDeadlineNs,
+            signature: intents.signature,
+        },
+    };
+}
+export async function sendRequestPayment(a) {
+    const provider = new JsonRpcProvider({ url: a.rpcUrl });
+    const signer = new KeyPairSigner(KeyPair.fromString(a.agentKey));
+    const account = new Account(a.agentId, provider, signer);
+    return account.callFunction({
+        contractId: a.vault,
+        methodName: ALLOWED_METHOD,
+        args: {
+            request_id: a.requestId,
+            token: a.token,
+            // U128 crosses the ABI as a decimal string; a JSON number would lose
+            // precision above 2^53.
+            amount: a.amount.toString(),
+            recipient: a.recipient,
+            memo: a.memo,
+            // Omitted entirely when undefined: the contract takes `Option<Route>`
+            // and a missing field deserialises to None, which is the NEAR rail.
+            ...(a.route === undefined ? {} : { route: a.route }),
+        },
+        gas: BigInt(a.gasTgas) * 10n ** 12n,
+        // Hardcoded zero, and not a parameter. A function-call key that attaches
+        // any deposit is rejected by the protocol with
+        // InvalidAccessKeyError(DepositWithFunctionCall) — so a non-zero value
+        // here would not be a security hole, it would simply make every payment
+        // fail. Keeping it a constant means that cannot be introduced by a caller.
+        deposit: 0n,
+    });
+}

package/package.json

@@ -1,6 +1,42 @@
-{
-  "name": "@floatonnear/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@floatonnear/mcp",
+  "version": "0.1.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",
+  "bin": {
+    "mcp": "dist/server.js",
+    "float-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "near-api-js": "^7.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^5.0.5"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./amounts": "./dist/amounts.js",
+    "./sign": "./dist/sign.js",
+    "./payloads": "./dist/payloads.js",
+    "./quote": {
+      "types": "./dist/quote.d.ts",
+      "import": "./dist/quote.js"
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.