@muhaven/mcp 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] — 2026-05-18
+
+`position.*` tools can now drive real on-chain action via @muhaven/mcp
+— Path C of MCP Option A (dashboard URL elicitation → existing passkey
+ceremony). Pre-0.1.7, position tools returned a placeholder UserOp
+envelope + broker signature that no host could submit; the path was
+attestation-only despite implying buy/sell/claim. 0.1.7 swaps the
+envelope for a pre-filled dashboard deep-link URL the user opens to
+review + tap their passkey through the existing dashboard flow.
+
+### Added
+
+- **`muhaven.cash.wrap`** — new tool. Returns a `/cash?amount=` deep-
+  link for USDC → mhUSDC conversion. Common LLM chain: `read.portfolio`
+  → notice 0 mhUSDC → `cash.wrap` → then `position.buy` (each is its
+  own user-confirmed deep-link). Input is human-readable USDC ("100" =
+  $100). 23 tools total now (was 22).
+
+- **Token identifier accepts symbols OR addresses.** Every `position.*`
+  tool's `token` field used to require a 0x-address. Now accepts either
+  a symbol ("TBILL1") or a 0x-address. The dashboard pages resolve the
+  symbol via the marketplace store; unknown identifiers leave the form
+  blank for the user to fill in. Saves the LLM a round-trip through
+  `read.tokens` for the common "buy 5 of TBILL1" flow.
+
+- **Exported pure helpers** (`buildPositionDeeplink`,
+  `formatUsdc6ToDecimal`) so third-party MCP servers + tests can reason
+  about the URL shape without spawning anything.
+
+### Changed
+
+- **`position.buy/sell/claim` return shape** is now `{ dashboardUrl,
+  action, instructions, echo }` instead of `{ intentHash,
+  unsignedUserOp, brokerSignature, signerAddress }`. The `instructions`
+  field is a pre-formatted two-line string the LLM can show the user
+  verbatim ("Open this link to review and authorize..."). The `echo`
+  field mirrors input for LLM self-verification. **Breaking** for any
+  consumer that pinned the 0.1.6 response shape — the prior shape was
+  itself never end-to-end usable (placeholder envelope), so the
+  practical impact is "MCP buy now actually works" rather than
+  regression.
+
+- **`position.rebalance`** returns `not_implemented` with a clear
+  next-step hint pointing at single-leg `position.buy` / `position.sell`
+  or the dashboard. Multi-leg `execute_plan` (one URL, one passkey,
+  one batched UserOp) lands in Wave 5 with composite preview UI.
+
+- **Broker dep no longer required for position tools.** Previously, a
+  `position.buy` call without a running `muhaven-broker` daemon
+  returned `broker.unavailable`. Now position tools talk only to the
+  dashboard URL — the broker is still needed for `read.*` / governance
+  / issuer / policy tools (those use the JWT-authed path).
+
+### Removed
+
+- `signEnvelope` + `PositionEnvelopeData` + the per-process
+  `hasSessionKey` probe cache + `__resetSessionKeyProbeCacheForTests`'s
+  cache (the function is retained as a no-op for back-compat with any
+  test harness importing it). The whole broker-attestation path for
+  position tools is gone — they don't need a signing key at all.
+
+### Internal
+
+- 21 new vitest cases in `__tests__/position-deeplink.test.ts`,
+  replacing `session-key-required.test.ts` (deleted — covered a
+  removed code path). Total `@muhaven/mcp` suite: **262/262 passing**
+  (was 241). Tool-hash count: **23** (was 22).
+
+### Operator notes
+
+- Once installed, the fresh-install ritual is unchanged: `muhaven-broker
+  setup --register claude-code` still wires the MCP server into Claude
+  Code via `claude mcp add-json`.
+- Existing 0.1.6 installs: `npm install -g @muhaven/mcp@latest` picks up
+  the new bin; no setup re-run needed.
+- `MUHAVEN_DASHBOARD_URL` env var (defaults to `https://muhaven.app`)
+  now drives the deep-link URL prefix; staging operators set it to
+  `https://muhaven-staging.example` and the URLs flow through.
+
 ## [0.1.6] — 2026-05-17
 
 Adds `muhaven-broker setup --register HOST` so a fresh install no longer

package/dist/broker.cjs

@@ -1750,7 +1750,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.1.6";
+    return "0.1.7";
   }
 }
 function printVersion() {

package/dist/broker.js

@@ -1752,7 +1752,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.1.6";
+    return "0.1.7";
   }
 }
 function printVersion() {

package/dist/index.cjs

@@ -11,7 +11,7 @@ var zod = require('zod');
 var os = require('os');
 var net = require('net');
 var crypto = require('crypto');
-var viem = require('viem');
+require('viem');
 var accounts = require('viem/accounts');
 
 // ../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.14_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
@@ -467,25 +467,32 @@ var TOOL_DESCRIPTORS = [
   {
     name: "muhaven.position.buy",
     group: "position",
-    description: "PROPOSE a Subscription buy. Returns an unsigned UserOp envelope plus a broker-signed session-key signature. The host MUST present the unsigned envelope to the user for passkey confirmation before submission to the bundler \u2014 this tool NEVER auto-submits. Fails when the user is in Advisory or Paused tier.",
+    description: `Prepare a Subscription buy. Returns a dashboard deep-link URL (muhaven.app/trade?mode=buy&...) the user opens to review the pre-filled form, then taps Authorize. The user's passkey + ZeroDev kernel sign on the dashboard \u2014 this MCP tool never holds or submits a signing key. Use after the user names a clear amount + token (e.g. "Buy 5 mhUSDC of TBILL1"). Token accepts either a symbol ("TBILL1") or 0x-address. Settlement is NOT observable from MCP \u2014 verify by calling muhaven.read.portfolio after the user confirms done.`,
     sensitive: true
   },
   {
     name: "muhaven.position.sell",
     group: "position",
-    description: "PROPOSE a redemption-queue sell. Same envelope-plus-signature pattern as muhaven.position.buy. Requires the user to be in Confirm-per-action or Policy-bound tier on the MCP surface.",
+    description: "Prepare a Subscription sell. Returns a dashboard deep-link URL (muhaven.app/trade?mode=sell&...) with the form pre-filled. Same passkey + verify-after pattern as muhaven.position.buy. Input is amountShares (raw share count), NOT mhUSDC notional.",
     sensitive: true
   },
   {
     name: "muhaven.position.claim",
     group: "position",
-    description: "PROPOSE a yield claim from RedemptionQueue / YieldSnapshot for a given token. Returns an unsigned UserOp + broker signature. Idempotent \u2014 proposing twice produces the same intent hash.",
+    description: "Prepare a yield claim. Returns a dashboard deep-link URL (muhaven.app/yields?...) pointing at the YieldsPage. When escrowId is set, the matching epoch row is highlighted + scrolled into view; when omitted, the page renders the user's full claimable list and they pick. User passkey-signs on the dashboard.",
     sensitive: true
   },
   {
     name: "muhaven.position.rebalance",
     group: "position",
-    description: "PROPOSE a multi-leg atomic rebalance bundling buy + sell legs into a single UserOp. Each leg is constrained by the user's installed @zerodev/permissions CallPolicy.",
+    description: "NOT IMPLEMENTED in this release \u2014 returns an error pointing the user at single-leg position.buy / position.sell or the dashboard /trade page. Multi-leg execute_plan lands in Wave 5 with a composite preview UI + executeBatch on the kernel.",
+    sensitive: true
+  },
+  // ── Path C cash group (2026-05-18) ────────────────────────────────
+  {
+    name: "muhaven.cash.wrap",
+    group: "cash",
+    description: 'Prepare a USDC \u2192 mhUSDC wrap (the encrypted-balance conversion that funds buys). Returns a dashboard deep-link URL (muhaven.app/cash?action=wrap&...) with the amount pre-filled. Input amountUsdc is human-readable USDC ("100" = $100). Common LLM chain: read.portfolio \u2192 notice 0 mhUSDC \u2192 cash.wrap \u2192 then position.buy (each is its own user-confirmed deep-link). Settlement not observable from MCP \u2014 re-call read.portfolio to verify.',
     sensitive: true
   },
   {
@@ -611,6 +618,13 @@ function verifyDescriptorAgainstPin(descriptor, pinnedSha256) {
 }
 var HEX_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 var addressSchema = zod.z.string().regex(HEX_ADDRESS_RE, "must be a 0x-prefixed 20-byte hex address");
+var TOKEN_SYMBOL_RE = /^[A-Za-z][A-Za-z0-9]{0,11}$/;
+var tokenIdentifierSchema = zod.z.string().refine(
+  (v) => HEX_ADDRESS_RE.test(v) || TOKEN_SYMBOL_RE.test(v),
+  {
+    message: "must be a 0x-prefixed 20-byte hex address OR a token symbol (1-12 alphanumeric chars, starting with a letter)"
+  }
+);
 var tierSchema = zod.z.enum(["advisory", "confirm-per-action", "policy-bound", "paused"]);
 var surfaceSchema = zod.z.enum(["havenbot", "mcp", "openclaw", "checkout"]);
 zod.z.union([zod.z.literal(1), zod.z.literal(2), zod.z.literal(3), zod.z.literal(4)]);
@@ -647,29 +661,38 @@ var ReadAuditInputSchema = zod.z.object({
   limit: zod.z.number().int().min(1).max(200).optional()
 }).strict();
 var PositionBuyInputSchema = zod.z.object({
-  token: addressSchema,
+  /** Symbol (e.g. "TBILL1") or 0x-address. Path C dashboard resolves either. */
+  token: tokenIdentifierSchema,
   /** Investor candidate spend, denominated in USDC base units (uint64). */
   amountUsdc6: zod.z.string().regex(/^\d+$/, "must be a base-10 integer string")
 }).strict();
 var PositionSellInputSchema = zod.z.object({
-  token: addressSchema,
+  token: tokenIdentifierSchema,
   /** Encrypted-balance share count to redeem, denominated in fhERC-20 base units. */
   amountShares: zod.z.string().regex(/^\d+$/, "must be a base-10 integer string")
 }).strict();
 var PositionClaimInputSchema = zod.z.object({
-  token: addressSchema,
-  /** When set, claim only the named escrow id; else claim-all. */
+  token: tokenIdentifierSchema,
+  /** When set, deep-link highlights the specific epoch row; else /yields renders the full claimable list. */
   escrowId: zod.z.string().regex(/^\d+$/).optional()
 }).strict();
 var PositionRebalanceInputSchema = zod.z.object({
   legs: zod.z.array(
     zod.z.object({
-      token: addressSchema,
+      token: tokenIdentifierSchema,
       side: zod.z.enum(["buy", "sell"]),
       amount: zod.z.string().regex(/^\d+$/)
     }).strict()
   ).min(2).max(8)
 }).strict();
+var CashWrapInputSchema = zod.z.object({
+  /**
+   * USDC amount in human-readable units ("100" for $100, "1.5" for
+   * $1.50). Forwarded verbatim to `/cash?amount=`. Decimal optional
+   * — CashPage parses both `\d+` and `\d+\.\d+`.
+   */
+  amountUsdc: zod.z.string().regex(/^\d+(\.\d+)?$/, "must be a positive decimal number string")
+}).strict();
 var PolicySetTierInputSchema = zod.z.object({
   targetTier: tierSchema,
   /** Returned by an earlier `request` call. Omit for step-down or first-call. */
@@ -740,15 +763,6 @@ function authRequiredPayload() {
     loginCommand: "muhaven-broker login"
   };
 }
-function sessionKeyRequiredPayload(dashboardBaseUrl = "https://muhaven.app") {
-  const mintUrl = `${trimTrailingSlash(dashboardBaseUrl)}/agent/policy/transition`;
-  return {
-    ok: false,
-    code: "SESSION_KEY_REQUIRED",
-    message: `No session key loaded in broker (read-only posture). Mint one via the dashboard at ${mintUrl}, copy the 0x-prefixed hex into MUHAVEN_BROKER_SESSION_KEY, and restart the daemon. Do NOT run \`muhaven-broker login\` for this \u2014 that mints a JWT, not a session key.`,
-    mintUrl
-  };
-}
 
 // src/tools/handlers.ts
 function ok(data) {
@@ -765,11 +779,6 @@ function mapBackendError(e) {
   if (e instanceof Error) return err("backend.network", e.message);
   return err("backend.network", "unknown backend error");
 }
-function mapBrokerError(e) {
-  if (e instanceof BrokerClientError) return err(`broker.${e.code}`, e.message);
-  if (e instanceof Error) return err("broker.network", e.message);
-  return err("broker.network", "unknown broker error");
-}
 async function readPortfolio(_input, deps) {
   try {
     const data = await deps.backend.get("/api/v1/portfolio");
@@ -823,103 +832,95 @@ async function readAudit(input, deps) {
     return mapBackendError(e);
   }
 }
-var PLACEHOLDER_INTENT_DOMAIN = "muhaven.placeholder.intent.v0:";
-function computeIntentHash(intent) {
-  const canonical = JSON.stringify(sortKeys(intent));
-  return viem.keccak256(viem.toBytes(PLACEHOLDER_INTENT_DOMAIN + canonical));
+function buildPositionDeeplink(dashboardBaseUrl, action, params) {
+  const base = dashboardBaseUrl.replace(/\/+$/, "");
+  const path = action === "buy" || action === "sell" ? "/trade" : action === "claim" ? "/yields" : "/cash";
+  const search = new URLSearchParams();
+  if (action === "buy" || action === "sell") search.set("mode", action);
+  for (const [k, v] of Object.entries(params)) search.set(k, v);
+  search.set("from", "mcp");
+  return `${base}${path}?${search.toString()}`;
 }
-function sortKeys(value) {
-  if (Array.isArray(value)) return value.map(sortKeys);
-  if (value && typeof value === "object") {
-    const obj = value;
-    const sorted = {};
-    for (const k of Object.keys(obj).sort()) sorted[k] = sortKeys(obj[k]);
-    return sorted;
+function formatUsdc6ToDecimal(amountUsdc6) {
+  if (!/^\d+$/.test(amountUsdc6)) {
+    throw new Error(`amountUsdc6 must be a non-negative integer string: ${amountUsdc6}`);
   }
-  return value;
+  const padded = amountUsdc6.padStart(7, "0");
+  const intPart = padded.slice(0, -6).replace(/^0+(?=\d)/, "");
+  const fracPart = padded.slice(-6).replace(/0+$/, "");
+  return fracPart === "" ? intPart : `${intPart}.${fracPart}`;
 }
-var cachedHasSessionKeyProbe = null;
-async function signEnvelope(intent, toolName, summary, deps) {
-  const intentHash = computeIntentHash(intent);
-  if (!deps.broker) {
-    return err(
-      "broker.unavailable",
-      "position tools require a running muhaven-broker daemon \u2014 see README \xA7Broker setup"
-    );
-  }
-  const broker = deps.broker;
-  if (cachedHasSessionKeyProbe === null) {
-    cachedHasSessionKeyProbe = (async () => {
-      try {
-        const hello = await broker.hello();
-        return hello.hasSessionKey ?? true;
-      } catch (err2) {
-        cachedHasSessionKeyProbe = null;
-        throw err2;
-      }
-    })();
-  }
-  let hasSessionKey;
-  try {
-    hasSessionKey = await cachedHasSessionKeyProbe;
-  } catch (e) {
-    return mapBrokerError(e);
-  }
-  if (hasSessionKey === false) {
-    return sessionKeyRequiredPayload(deps.dashboardBaseUrl);
-  }
-  try {
-    const sig = await broker.signHash(intentHash, { tool: toolName, summary });
-    return ok({
-      intentHash,
-      unsignedUserOp: {
-        target: "see backend",
-        data: "see backend",
-        note: "P3 returns a placeholder envelope; P6 wires the canonical UserOp shape."
-      },
-      brokerSignature: sig.signature,
-      signerAddress: sig.signerAddress
-    });
-  } catch (e) {
-    if (e instanceof BrokerClientError && e.code === "broker_error" && /session_key_unavailable/.test(e.message)) {
-      cachedHasSessionKeyProbe = Promise.resolve(false);
-      return sessionKeyRequiredPayload(deps.dashboardBaseUrl);
-    }
-    return mapBrokerError(e);
-  }
+function resolveDashboardBaseUrl(deps) {
+  return deps.dashboardBaseUrl ?? "https://muhaven.app";
 }
 async function positionBuy(input, deps) {
-  return signEnvelope(
-    { kind: "buy", token: input.token, amountUsdc6: input.amountUsdc6 },
-    "muhaven.position.buy",
-    `buy ${input.amountUsdc6} USDC of ${input.token}`,
-    deps
-  );
+  const amount = formatUsdc6ToDecimal(input.amountUsdc6);
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "buy", {
+    token: input.token,
+    amount
+  });
+  return ok({
+    dashboardUrl,
+    action: "buy",
+    instructions: `Open this link to review and authorize the buy of ${amount} mhUSDC of ${input.token}:
+${dashboardUrl}`,
+    echo: { action: "buy", token: input.token, amount }
+  });
 }
 async function positionSell(input, deps) {
-  return signEnvelope(
-    { kind: "sell", token: input.token, amountShares: input.amountShares },
-    "muhaven.position.sell",
-    `sell ${input.amountShares} shares of ${input.token}`,
-    deps
-  );
+  if (!/^\d+(\.\d+)?$/.test(input.amountShares)) {
+    return err(
+      "invalid_input",
+      `amountShares must be a non-negative number string: ${JSON.stringify(input.amountShares)}`
+    );
+  }
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "sell", {
+    token: input.token,
+    shares: input.amountShares
+  });
+  return ok({
+    dashboardUrl,
+    action: "sell",
+    instructions: `Open this link to review and authorize the sale of ${input.amountShares} shares of ${input.token}:
+${dashboardUrl}`,
+    echo: { action: "sell", token: input.token, shares: input.amountShares }
+  });
 }
 async function positionClaim(input, deps) {
-  return signEnvelope(
-    { kind: "claim", token: input.token, escrowId: input.escrowId ?? null },
-    "muhaven.position.claim",
-    `claim ${input.token}${input.escrowId ? ` escrow#${input.escrowId}` : " (all)"}`,
-    deps
-  );
+  const params = { token: input.token };
+  if (input.escrowId) params.epoch = input.escrowId;
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "claim", params);
+  const claimDescriptor = input.escrowId ? `the claim for epoch #${input.escrowId} of ${input.token}` : `your claimable epochs for ${input.token}`;
+  return ok({
+    dashboardUrl,
+    action: "claim",
+    instructions: `Open this link to review and authorize ${claimDescriptor}:
+${dashboardUrl}`,
+    echo: {
+      action: "claim",
+      token: input.token,
+      ...input.escrowId ? { epoch: input.escrowId } : {}
+    }
+  });
 }
-async function positionRebalance(input, deps) {
-  return signEnvelope(
-    { kind: "rebalance", legs: input.legs },
-    "muhaven.position.rebalance",
-    `rebalance ${input.legs.length} legs`,
-    deps
+async function positionRebalance(_input, _deps) {
+  return err(
+    "not_implemented",
+    "position.rebalance is deferred to Wave 5. Today, ask the user to execute legs one at a time via position.buy / position.sell, or use the dashboard /trade page directly."
   );
 }
+async function cashWrap(input, deps) {
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "wrap", {
+    amount: input.amountUsdc
+  });
+  return ok({
+    dashboardUrl,
+    action: "wrap",
+    instructions: `Open this link to review and authorize the conversion of ${input.amountUsdc} USDC into mhUSDC:
+${dashboardUrl}`,
+    echo: { action: "wrap", amount: input.amountUsdc }
+  });
+}
 async function policySetTier(input, deps) {
   try {
     const data = await deps.backend.post("/api/v1/agent/policy/transition", {
@@ -1127,6 +1128,11 @@ var HANDLERS = {
     schema: PositionRebalanceInputSchema,
     handler: positionRebalance
   },
+  // ── Path C cash group (2026-05-18) ────────────────────────────────
+  "muhaven.cash.wrap": {
+    schema: CashWrapInputSchema,
+    handler: cashWrap
+  },
   "muhaven.policy.set_tier": {
     schema: PolicySetTierInputSchema,
     handler: policySetTier
@@ -1210,7 +1216,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.1.6";
+    return "0.1.7";
   }
 }
 function toJsonInputSchema(schema) {

package/dist/index.d.cts

@@ -298,7 +298,7 @@ interface ToolDescriptor {
      *  `read` so `--read-only` keeps them available; the two propose
      *  tools (`muhaven.governance.propose`, `muhaven.governance.cast_vote`)
      *  are filtered off in read-only mode. */
-    readonly group: 'read' | 'position' | 'policy' | 'issuer' | 'governance';
+    readonly group: 'read' | 'position' | 'policy' | 'issuer' | 'governance' | 'cash';
     /** Human-readable description shown in the host UI. */
     readonly description: string;
     /** When true, the host SHOULD render a confirmation cue before invoking. */
@@ -384,26 +384,6 @@ interface SessionKeyRequiredPayload {
     readonly mintUrl: string;
 }
 
-/**
- * Tool handlers — pure functions of `(input, deps)` returning a structured
- * tool result. The MCP server transport layer (`src/server.ts`) wires
- * these to the host LLM via `@modelcontextprotocol/sdk`.
- *
- * Design notes:
- *  - Handlers NEVER throw. They translate every error into a structured
- *    `{ ok: false, code, message }` payload so the host LLM can decide
- *    how to surface it without crashing the MCP server. This matches the
- *    MCPB error-presentation convention.
- *  - Position handlers DO NOT submit UserOps. They return an unsigned
- *    envelope plus a broker signature; the host (or the MuHaven
- *    dashboard via deep-link) is responsible for bundler submission.
- *    Splitting submission from signing is the lethal-trifecta defense.
- *  - Backend errors with status >= 500 are surfaced as `server_error`
- *    so the host can retry; client errors (4xx) bubble up as the
- *    discriminating code (`unauthorized`, `forbidden`, etc.). The host
- *    MUST NOT auto-retry 4xx.
- */
-
 interface ToolDeps {
     backend: BackendClient;
     broker?: BrokerClient;

package/dist/index.d.ts

@@ -298,7 +298,7 @@ interface ToolDescriptor {
      *  `read` so `--read-only` keeps them available; the two propose
      *  tools (`muhaven.governance.propose`, `muhaven.governance.cast_vote`)
      *  are filtered off in read-only mode. */
-    readonly group: 'read' | 'position' | 'policy' | 'issuer' | 'governance';
+    readonly group: 'read' | 'position' | 'policy' | 'issuer' | 'governance' | 'cash';
     /** Human-readable description shown in the host UI. */
     readonly description: string;
     /** When true, the host SHOULD render a confirmation cue before invoking. */
@@ -384,26 +384,6 @@ interface SessionKeyRequiredPayload {
     readonly mintUrl: string;
 }
 
-/**
- * Tool handlers — pure functions of `(input, deps)` returning a structured
- * tool result. The MCP server transport layer (`src/server.ts`) wires
- * these to the host LLM via `@modelcontextprotocol/sdk`.
- *
- * Design notes:
- *  - Handlers NEVER throw. They translate every error into a structured
- *    `{ ok: false, code, message }` payload so the host LLM can decide
- *    how to surface it without crashing the MCP server. This matches the
- *    MCPB error-presentation convention.
- *  - Position handlers DO NOT submit UserOps. They return an unsigned
- *    envelope plus a broker signature; the host (or the MuHaven
- *    dashboard via deep-link) is responsible for bundler submission.
- *    Splitting submission from signing is the lethal-trifecta defense.
- *  - Backend errors with status >= 500 are surfaced as `server_error`
- *    so the host can retry; client errors (4xx) bubble up as the
- *    discriminating code (`unauthorized`, `forbidden`, etc.). The host
- *    MUST NOT auto-retry 4xx.
- */
-
 interface ToolDeps {
     backend: BackendClient;
     broker?: BrokerClient;

package/dist/index.js

@@ -9,7 +9,7 @@ import { z, ZodError } from 'zod';
 import { platform, homedir } from 'os';
 import { connect, createServer } from 'net';
 import { createHash } from 'crypto';
-import { keccak256, toBytes } from 'viem';
+import 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 
 // src/server.ts
@@ -463,25 +463,32 @@ var TOOL_DESCRIPTORS = [
   {
     name: "muhaven.position.buy",
     group: "position",
-    description: "PROPOSE a Subscription buy. Returns an unsigned UserOp envelope plus a broker-signed session-key signature. The host MUST present the unsigned envelope to the user for passkey confirmation before submission to the bundler \u2014 this tool NEVER auto-submits. Fails when the user is in Advisory or Paused tier.",
+    description: `Prepare a Subscription buy. Returns a dashboard deep-link URL (muhaven.app/trade?mode=buy&...) the user opens to review the pre-filled form, then taps Authorize. The user's passkey + ZeroDev kernel sign on the dashboard \u2014 this MCP tool never holds or submits a signing key. Use after the user names a clear amount + token (e.g. "Buy 5 mhUSDC of TBILL1"). Token accepts either a symbol ("TBILL1") or 0x-address. Settlement is NOT observable from MCP \u2014 verify by calling muhaven.read.portfolio after the user confirms done.`,
     sensitive: true
   },
   {
     name: "muhaven.position.sell",
     group: "position",
-    description: "PROPOSE a redemption-queue sell. Same envelope-plus-signature pattern as muhaven.position.buy. Requires the user to be in Confirm-per-action or Policy-bound tier on the MCP surface.",
+    description: "Prepare a Subscription sell. Returns a dashboard deep-link URL (muhaven.app/trade?mode=sell&...) with the form pre-filled. Same passkey + verify-after pattern as muhaven.position.buy. Input is amountShares (raw share count), NOT mhUSDC notional.",
     sensitive: true
   },
   {
     name: "muhaven.position.claim",
     group: "position",
-    description: "PROPOSE a yield claim from RedemptionQueue / YieldSnapshot for a given token. Returns an unsigned UserOp + broker signature. Idempotent \u2014 proposing twice produces the same intent hash.",
+    description: "Prepare a yield claim. Returns a dashboard deep-link URL (muhaven.app/yields?...) pointing at the YieldsPage. When escrowId is set, the matching epoch row is highlighted + scrolled into view; when omitted, the page renders the user's full claimable list and they pick. User passkey-signs on the dashboard.",
     sensitive: true
   },
   {
     name: "muhaven.position.rebalance",
     group: "position",
-    description: "PROPOSE a multi-leg atomic rebalance bundling buy + sell legs into a single UserOp. Each leg is constrained by the user's installed @zerodev/permissions CallPolicy.",
+    description: "NOT IMPLEMENTED in this release \u2014 returns an error pointing the user at single-leg position.buy / position.sell or the dashboard /trade page. Multi-leg execute_plan lands in Wave 5 with a composite preview UI + executeBatch on the kernel.",
+    sensitive: true
+  },
+  // ── Path C cash group (2026-05-18) ────────────────────────────────
+  {
+    name: "muhaven.cash.wrap",
+    group: "cash",
+    description: 'Prepare a USDC \u2192 mhUSDC wrap (the encrypted-balance conversion that funds buys). Returns a dashboard deep-link URL (muhaven.app/cash?action=wrap&...) with the amount pre-filled. Input amountUsdc is human-readable USDC ("100" = $100). Common LLM chain: read.portfolio \u2192 notice 0 mhUSDC \u2192 cash.wrap \u2192 then position.buy (each is its own user-confirmed deep-link). Settlement not observable from MCP \u2014 re-call read.portfolio to verify.',
     sensitive: true
   },
   {
@@ -607,6 +614,13 @@ function verifyDescriptorAgainstPin(descriptor, pinnedSha256) {
 }
 var HEX_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 var addressSchema = z.string().regex(HEX_ADDRESS_RE, "must be a 0x-prefixed 20-byte hex address");
+var TOKEN_SYMBOL_RE = /^[A-Za-z][A-Za-z0-9]{0,11}$/;
+var tokenIdentifierSchema = z.string().refine(
+  (v) => HEX_ADDRESS_RE.test(v) || TOKEN_SYMBOL_RE.test(v),
+  {
+    message: "must be a 0x-prefixed 20-byte hex address OR a token symbol (1-12 alphanumeric chars, starting with a letter)"
+  }
+);
 var tierSchema = z.enum(["advisory", "confirm-per-action", "policy-bound", "paused"]);
 var surfaceSchema = z.enum(["havenbot", "mcp", "openclaw", "checkout"]);
 z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]);
@@ -643,29 +657,38 @@ var ReadAuditInputSchema = z.object({
   limit: z.number().int().min(1).max(200).optional()
 }).strict();
 var PositionBuyInputSchema = z.object({
-  token: addressSchema,
+  /** Symbol (e.g. "TBILL1") or 0x-address. Path C dashboard resolves either. */
+  token: tokenIdentifierSchema,
   /** Investor candidate spend, denominated in USDC base units (uint64). */
   amountUsdc6: z.string().regex(/^\d+$/, "must be a base-10 integer string")
 }).strict();
 var PositionSellInputSchema = z.object({
-  token: addressSchema,
+  token: tokenIdentifierSchema,
   /** Encrypted-balance share count to redeem, denominated in fhERC-20 base units. */
   amountShares: z.string().regex(/^\d+$/, "must be a base-10 integer string")
 }).strict();
 var PositionClaimInputSchema = z.object({
-  token: addressSchema,
-  /** When set, claim only the named escrow id; else claim-all. */
+  token: tokenIdentifierSchema,
+  /** When set, deep-link highlights the specific epoch row; else /yields renders the full claimable list. */
   escrowId: z.string().regex(/^\d+$/).optional()
 }).strict();
 var PositionRebalanceInputSchema = z.object({
   legs: z.array(
     z.object({
-      token: addressSchema,
+      token: tokenIdentifierSchema,
       side: z.enum(["buy", "sell"]),
       amount: z.string().regex(/^\d+$/)
     }).strict()
   ).min(2).max(8)
 }).strict();
+var CashWrapInputSchema = z.object({
+  /**
+   * USDC amount in human-readable units ("100" for $100, "1.5" for
+   * $1.50). Forwarded verbatim to `/cash?amount=`. Decimal optional
+   * — CashPage parses both `\d+` and `\d+\.\d+`.
+   */
+  amountUsdc: z.string().regex(/^\d+(\.\d+)?$/, "must be a positive decimal number string")
+}).strict();
 var PolicySetTierInputSchema = z.object({
   targetTier: tierSchema,
   /** Returned by an earlier `request` call. Omit for step-down or first-call. */
@@ -736,15 +759,6 @@ function authRequiredPayload() {
     loginCommand: "muhaven-broker login"
   };
 }
-function sessionKeyRequiredPayload(dashboardBaseUrl = "https://muhaven.app") {
-  const mintUrl = `${trimTrailingSlash(dashboardBaseUrl)}/agent/policy/transition`;
-  return {
-    ok: false,
-    code: "SESSION_KEY_REQUIRED",
-    message: `No session key loaded in broker (read-only posture). Mint one via the dashboard at ${mintUrl}, copy the 0x-prefixed hex into MUHAVEN_BROKER_SESSION_KEY, and restart the daemon. Do NOT run \`muhaven-broker login\` for this \u2014 that mints a JWT, not a session key.`,
-    mintUrl
-  };
-}
 
 // src/tools/handlers.ts
 function ok(data) {
@@ -761,11 +775,6 @@ function mapBackendError(e) {
   if (e instanceof Error) return err("backend.network", e.message);
   return err("backend.network", "unknown backend error");
 }
-function mapBrokerError(e) {
-  if (e instanceof BrokerClientError) return err(`broker.${e.code}`, e.message);
-  if (e instanceof Error) return err("broker.network", e.message);
-  return err("broker.network", "unknown broker error");
-}
 async function readPortfolio(_input, deps) {
   try {
     const data = await deps.backend.get("/api/v1/portfolio");
@@ -819,103 +828,95 @@ async function readAudit(input, deps) {
     return mapBackendError(e);
   }
 }
-var PLACEHOLDER_INTENT_DOMAIN = "muhaven.placeholder.intent.v0:";
-function computeIntentHash(intent) {
-  const canonical = JSON.stringify(sortKeys(intent));
-  return keccak256(toBytes(PLACEHOLDER_INTENT_DOMAIN + canonical));
+function buildPositionDeeplink(dashboardBaseUrl, action, params) {
+  const base = dashboardBaseUrl.replace(/\/+$/, "");
+  const path = action === "buy" || action === "sell" ? "/trade" : action === "claim" ? "/yields" : "/cash";
+  const search = new URLSearchParams();
+  if (action === "buy" || action === "sell") search.set("mode", action);
+  for (const [k, v] of Object.entries(params)) search.set(k, v);
+  search.set("from", "mcp");
+  return `${base}${path}?${search.toString()}`;
 }
-function sortKeys(value) {
-  if (Array.isArray(value)) return value.map(sortKeys);
-  if (value && typeof value === "object") {
-    const obj = value;
-    const sorted = {};
-    for (const k of Object.keys(obj).sort()) sorted[k] = sortKeys(obj[k]);
-    return sorted;
+function formatUsdc6ToDecimal(amountUsdc6) {
+  if (!/^\d+$/.test(amountUsdc6)) {
+    throw new Error(`amountUsdc6 must be a non-negative integer string: ${amountUsdc6}`);
   }
-  return value;
+  const padded = amountUsdc6.padStart(7, "0");
+  const intPart = padded.slice(0, -6).replace(/^0+(?=\d)/, "");
+  const fracPart = padded.slice(-6).replace(/0+$/, "");
+  return fracPart === "" ? intPart : `${intPart}.${fracPart}`;
 }
-var cachedHasSessionKeyProbe = null;
-async function signEnvelope(intent, toolName, summary, deps) {
-  const intentHash = computeIntentHash(intent);
-  if (!deps.broker) {
-    return err(
-      "broker.unavailable",
-      "position tools require a running muhaven-broker daemon \u2014 see README \xA7Broker setup"
-    );
-  }
-  const broker = deps.broker;
-  if (cachedHasSessionKeyProbe === null) {
-    cachedHasSessionKeyProbe = (async () => {
-      try {
-        const hello = await broker.hello();
-        return hello.hasSessionKey ?? true;
-      } catch (err2) {
-        cachedHasSessionKeyProbe = null;
-        throw err2;
-      }
-    })();
-  }
-  let hasSessionKey;
-  try {
-    hasSessionKey = await cachedHasSessionKeyProbe;
-  } catch (e) {
-    return mapBrokerError(e);
-  }
-  if (hasSessionKey === false) {
-    return sessionKeyRequiredPayload(deps.dashboardBaseUrl);
-  }
-  try {
-    const sig = await broker.signHash(intentHash, { tool: toolName, summary });
-    return ok({
-      intentHash,
-      unsignedUserOp: {
-        target: "see backend",
-        data: "see backend",
-        note: "P3 returns a placeholder envelope; P6 wires the canonical UserOp shape."
-      },
-      brokerSignature: sig.signature,
-      signerAddress: sig.signerAddress
-    });
-  } catch (e) {
-    if (e instanceof BrokerClientError && e.code === "broker_error" && /session_key_unavailable/.test(e.message)) {
-      cachedHasSessionKeyProbe = Promise.resolve(false);
-      return sessionKeyRequiredPayload(deps.dashboardBaseUrl);
-    }
-    return mapBrokerError(e);
-  }
+function resolveDashboardBaseUrl(deps) {
+  return deps.dashboardBaseUrl ?? "https://muhaven.app";
 }
 async function positionBuy(input, deps) {
-  return signEnvelope(
-    { kind: "buy", token: input.token, amountUsdc6: input.amountUsdc6 },
-    "muhaven.position.buy",
-    `buy ${input.amountUsdc6} USDC of ${input.token}`,
-    deps
-  );
+  const amount = formatUsdc6ToDecimal(input.amountUsdc6);
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "buy", {
+    token: input.token,
+    amount
+  });
+  return ok({
+    dashboardUrl,
+    action: "buy",
+    instructions: `Open this link to review and authorize the buy of ${amount} mhUSDC of ${input.token}:
+${dashboardUrl}`,
+    echo: { action: "buy", token: input.token, amount }
+  });
 }
 async function positionSell(input, deps) {
-  return signEnvelope(
-    { kind: "sell", token: input.token, amountShares: input.amountShares },
-    "muhaven.position.sell",
-    `sell ${input.amountShares} shares of ${input.token}`,
-    deps
-  );
+  if (!/^\d+(\.\d+)?$/.test(input.amountShares)) {
+    return err(
+      "invalid_input",
+      `amountShares must be a non-negative number string: ${JSON.stringify(input.amountShares)}`
+    );
+  }
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "sell", {
+    token: input.token,
+    shares: input.amountShares
+  });
+  return ok({
+    dashboardUrl,
+    action: "sell",
+    instructions: `Open this link to review and authorize the sale of ${input.amountShares} shares of ${input.token}:
+${dashboardUrl}`,
+    echo: { action: "sell", token: input.token, shares: input.amountShares }
+  });
 }
 async function positionClaim(input, deps) {
-  return signEnvelope(
-    { kind: "claim", token: input.token, escrowId: input.escrowId ?? null },
-    "muhaven.position.claim",
-    `claim ${input.token}${input.escrowId ? ` escrow#${input.escrowId}` : " (all)"}`,
-    deps
-  );
+  const params = { token: input.token };
+  if (input.escrowId) params.epoch = input.escrowId;
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "claim", params);
+  const claimDescriptor = input.escrowId ? `the claim for epoch #${input.escrowId} of ${input.token}` : `your claimable epochs for ${input.token}`;
+  return ok({
+    dashboardUrl,
+    action: "claim",
+    instructions: `Open this link to review and authorize ${claimDescriptor}:
+${dashboardUrl}`,
+    echo: {
+      action: "claim",
+      token: input.token,
+      ...input.escrowId ? { epoch: input.escrowId } : {}
+    }
+  });
 }
-async function positionRebalance(input, deps) {
-  return signEnvelope(
-    { kind: "rebalance", legs: input.legs },
-    "muhaven.position.rebalance",
-    `rebalance ${input.legs.length} legs`,
-    deps
+async function positionRebalance(_input, _deps) {
+  return err(
+    "not_implemented",
+    "position.rebalance is deferred to Wave 5. Today, ask the user to execute legs one at a time via position.buy / position.sell, or use the dashboard /trade page directly."
   );
 }
+async function cashWrap(input, deps) {
+  const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "wrap", {
+    amount: input.amountUsdc
+  });
+  return ok({
+    dashboardUrl,
+    action: "wrap",
+    instructions: `Open this link to review and authorize the conversion of ${input.amountUsdc} USDC into mhUSDC:
+${dashboardUrl}`,
+    echo: { action: "wrap", amount: input.amountUsdc }
+  });
+}
 async function policySetTier(input, deps) {
   try {
     const data = await deps.backend.post("/api/v1/agent/policy/transition", {
@@ -1123,6 +1124,11 @@ var HANDLERS = {
     schema: PositionRebalanceInputSchema,
     handler: positionRebalance
   },
+  // ── Path C cash group (2026-05-18) ────────────────────────────────
+  "muhaven.cash.wrap": {
+    schema: CashWrapInputSchema,
+    handler: cashWrap
+  },
   "muhaven.policy.set_tier": {
     schema: PolicySetTierInputSchema,
     handler: policySetTier
@@ -1206,7 +1212,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.1.6";
+    return "0.1.7";
   }
 }
 function toJsonInputSchema(schema) {

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.2",
   "name": "muhaven-mcp",
   "display_name": "MuHaven (RWA portfolio)",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Confidential RWA portfolio management on Fhenix CoFHE. Read your encrypted balances, propose yield claims and policy changes — all signing happens in a sibling broker daemon, the LLM never sees your private key.",
   "long_description": "MuHaven MCP exposes 22 tools across read.* / position.* / policy.* / issuer.* / governance.* groups for managing real-world asset (RWA) tokens with FHE-encrypted balances. Authentication uses a one-time device-code ceremony (run `muhaven-broker login`); subsequent tool calls fetch the JWT from the broker over a Unix socket. Position / governance tools return unsigned UserOps + broker signatures — they NEVER auto-submit to a bundler. The companion `muhaven-broker` daemon must be running before tools can be invoked. See README for setup.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhaven/mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "MuHaven MCP server — read/position/policy toolsets bridging Claude Desktop / Cursor / Claude Code to the MuHaven backend, with a sibling muhaven-broker daemon holding the session-key private half over a local IPC socket",
   "type": "module",
   "repository": {

package/tool-hashes.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-07T07:40:21.258Z",
+  "generatedAt": "2026-05-17T18:17:06.859Z",
   "tools": [
     {
       "name": "muhaven.read.portfolio",
@@ -23,19 +23,23 @@
     },
     {
       "name": "muhaven.position.buy",
-      "sha256": "638c905c66d8eea6dcfebb412ebf7020d768fb3e023b3b7ec5783718592e99d0"
+      "sha256": "f24c9628249e91ed485031f9114053fa6b174a5d55aedfb4109392eb5795c9e4"
     },
     {
       "name": "muhaven.position.sell",
-      "sha256": "20eb118ca994c2a1d4fd688c4832ecdfebb3f350e94dc6c4756a683d181f51c4"
+      "sha256": "707545106fdd505d7d942153bcb34d7ead53c2539b9699e0733159a57c72177d"
     },
     {
       "name": "muhaven.position.claim",
-      "sha256": "daa1c23ce6cf1a113f73ff1326e807e4a18c07c06db0f05c15e5ac01c8c15e86"
+      "sha256": "31a6b9472f8b34e69ca28b888e60178dafd01b8644e2a61e6f36515660b68838"
     },
     {
       "name": "muhaven.position.rebalance",
-      "sha256": "750bfe5524ac611354d692b8f48d9d3ed41858a89340d2553e2260b34986a0d7"
+      "sha256": "ad32f2e9c2b6aafb6bd3acd33079dc7541035f0f405045178f95489f80cc922e"
+    },
+    {
+      "name": "muhaven.cash.wrap",
+      "sha256": "1ae4cb949e0d09e7fb7e8957e51bfc63b43397c253849c217b835aaa9505b8c9"
     },
     {
       "name": "muhaven.policy.set_tier",