@muhaven/mcp 0.2.0 → 0.2.1

package/dist/broker.cjs

@@ -1840,7 +1840,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.0";
+    return "0.2.1";
   }
 }
 function printVersion() {

package/dist/broker.js

@@ -1842,7 +1842,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.0";
+    return "0.2.1";
   }
 }
 function printVersion() {

package/dist/index.cjs

@@ -377,6 +377,23 @@ var BackendClient = class {
       false
     );
   }
+  /**
+   * GET variant that sends no Authorization header. Use for backend
+   * endpoints that are intentionally public (e.g. `/api/v1/tokens`
+   * which the marketplace + the 0.2.1 `positionBuy` NAV-conversion
+   * both read). Avoids triggering the AUTH_REQUIRED branch for the
+   * "not yet logged in" case on read paths that don't need auth.
+   */
+  async getUnauth(path, query) {
+    const url = this.buildUrl(path, query);
+    return this.exchange(
+      "GET",
+      url,
+      void 0,
+      /* withAuth */
+      false
+    );
+  }
   buildUrl(path, query) {
     if (!path.startsWith("/")) {
       throw new BackendError("bad_request", `path must start with "/": ${path}`);
@@ -500,16 +517,22 @@ var TOOL_DESCRIPTORS = [
     description: `Return the authenticated user's tiered-autonomy audit log entries. Cursor-paginated. Useful for forensic review ("why was I paused?") and grant-reviewer demos. Read-only \u2014 never exposes other users' data.`,
     sensitive: false
   },
+  {
+    name: "muhaven.read.activity",
+    group: "read",
+    description: "Return the authenticated investor's on-chain activity feed (buys / sells / wraps / unwraps / yield claims / transfers). Each row carries token address, tx hash, block timestamp, and event type \u2014 but NEVER cleartext amounts (encrypted handles only, decryptable client-side via permit). USE THIS to verify a Path C dashboard action settled: after position.buy / position.sell / cash.wrap, the user opens the deep-link, taps Authorize, the on-chain tx lands \u2192 a new row appears here. Far more reliable than re-calling read.portfolio (which only changes shape when a NEW token enters the catalog).",
+    sensitive: false
+  },
   {
     name: "muhaven.position.buy",
     group: "position",
-    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" \u2192 `amountUsdc: "5"`). Token accepts either a symbol ("TBILL1") or 0x-address. The `amountUsdc` field is HUMAN-DECIMAL mhUSDC ("5" = 5 mhUSDC, "0.5" = half a mhUSDC) \u2014 NOT base-6 integer. Max 6 fractional digits. Settlement is NOT observable from MCP \u2014 verify by calling muhaven.read.portfolio after the user confirms done.',
+    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" \u2192 `amountUsdc: "5"`). Token accepts either a symbol ("TBILL1") or 0x-address. The `amountUsdc` field is HUMAN-DECIMAL mhUSDC ("5" = 5 mhUSDC, "0.5" = half a mhUSDC) \u2014 NOT base-6 integer. Max 6 fractional digits. The tool fetches the current on-chain NAV for the token and converts the notional to integer shares (floor) before building the URL \u2014 so "Buy 3 mhUSDC of GOLD1" at NAV $0.01 becomes "Buy 300 GOLD1 shares (~3 mhUSDC)". Refuses with `amount_too_small_for_share` when the notional won\'t buy at least 1 share at current NAV; the error message tells the user the minimum mhUSDC needed. Settlement is NOT observable from MCP \u2014 verify by calling muhaven.read.activity after the user confirms done (a new "buy" row with the tx hash will appear).',
     sensitive: true
   },
   {
     name: "muhaven.position.sell",
     group: "position",
-    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 POSITIVE INTEGER share count, NOT mhUSDC notional) \u2014 fhERC-20 shares have no decimals so fractional inputs are rejected.",
+    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 POSITIVE INTEGER share count, NOT mhUSDC notional) \u2014 fhERC-20 shares have no decimals so fractional inputs are rejected. Verify settlement by calling muhaven.read.activity (look for a "sell" or "sell-queued" row with the tx hash).',
     sensitive: true
   },
   {
@@ -528,7 +551,7 @@ var TOOL_DESCRIPTORS = [
   {
     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.',
+    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). Verify settlement by calling muhaven.read.activity (a new "wrap" row will appear with the tx hash).',
     sensitive: true
   },
   {
@@ -696,6 +719,10 @@ var ReadAuditInputSchema = zod.z.object({
   cursor: zod.z.string().min(1).max(512).optional(),
   limit: zod.z.number().int().min(1).max(200).optional()
 }).strict();
+var ReadActivityInputSchema = zod.z.object({
+  limit: zod.z.number().int().min(1).max(50).optional(),
+  offset: zod.z.number().int().min(0).max(1e3).optional()
+}).strict();
 var decimalUsdcAmountSchema = zod.z.string().regex(
   /^(0|[1-9]\d*)(\.\d{1,6})?$/,
   'must be a positive decimal mhUSDC amount with at most 6 fractional digits (e.g. "5", "0.5", "1234.567")'
@@ -816,6 +843,37 @@ function authRequiredPayload() {
   };
 }
 
+// src/tools/decimal.ts
+function parseDecimalToUsd6(decimal) {
+  const m = /^(\d+)(?:\.(\d+))?$/.exec(decimal);
+  if (!m) {
+    throw new Error(`Invalid decimal price: ${JSON.stringify(decimal)}`);
+  }
+  const intPart = m[1];
+  const fracPart = m[2] ?? "";
+  const fracPadded = (fracPart + "000000").slice(0, 6);
+  return BigInt(intPart + fracPadded);
+}
+function computeSharesFromUsd6(notionalUsd6, navUsd6) {
+  if (navUsd6 <= 0n) {
+    throw new Error("navUsd6 must be positive");
+  }
+  if (notionalUsd6 < 0n) {
+    throw new Error("notionalUsd6 must be non-negative");
+  }
+  return notionalUsd6 / navUsd6;
+}
+function formatUsd6AsDecimal(usd6) {
+  if (usd6 < 0n) {
+    throw new Error("usd6 must be non-negative");
+  }
+  const whole = usd6 / 1000000n;
+  const frac = usd6 % 1000000n;
+  if (frac === 0n) return whole.toString();
+  const fracStr = frac.toString().padStart(6, "0").replace(/0+$/, "");
+  return `${whole.toString()}.${fracStr}`;
+}
+
 // src/tools/handlers.ts
 function ok(data) {
   return { ok: true, data };
@@ -884,6 +942,17 @@ async function readAudit(input, deps) {
     return mapBackendError(e);
   }
 }
+async function readActivity(input, deps) {
+  try {
+    const data = await deps.backend.get("/api/v1/activity", {
+      limit: input.limit,
+      offset: input.offset
+    });
+    return ok(data);
+  } catch (e) {
+    return mapBackendError(e);
+  }
+}
 function buildPositionDeeplink(dashboardBaseUrl, action, params) {
   const base = dashboardBaseUrl.replace(/\/+$/, "");
   const path = action === "buy" || action === "sell" ? "/trade" : action === "claim" ? "/yields" : "/cash";
@@ -896,17 +965,100 @@ function buildPositionDeeplink(dashboardBaseUrl, action, params) {
 function resolveDashboardBaseUrl(deps) {
   return deps.dashboardBaseUrl ?? "https://muhaven.app";
 }
+function resolveTokenInCatalog(identifier, catalog) {
+  const needle = identifier.toLowerCase();
+  return catalog.find(
+    (t) => t.address.toLowerCase() === needle || t.symbol.toLowerCase() === needle
+  ) ?? null;
+}
+function sanitizeSymbolForLlmContext(raw) {
+  const cleaned = raw.replace(/[^A-Za-z0-9_-]/g, "?");
+  return cleaned.length > 16 ? cleaned.slice(0, 16) : cleaned;
+}
 async function positionBuy(input, deps) {
+  let catalog;
+  try {
+    catalog = await deps.backend.getUnauth("/api/v1/tokens");
+  } catch (e) {
+    return mapBackendError(e);
+  }
+  const token = resolveTokenInCatalog(input.token, catalog.tokens ?? []);
+  if (!token) {
+    return err(
+      "token_not_found",
+      `Token "${sanitizeSymbolForLlmContext(input.token)}" is not in the MuHaven catalog. Call muhaven.read.tokens for the canonical symbol list.`
+    );
+  }
+  const safeSymbol = sanitizeSymbolForLlmContext(token.symbol);
+  if (!token.latest_nav || !token.latest_nav.nav) {
+    return err(
+      "nav_unavailable",
+      `No NAV snapshot available for ${safeSymbol} yet. The nav-worker may not have written one \u2014 retry shortly, or use the dashboard /trade page directly.`
+    );
+  }
+  let navUsd6;
+  try {
+    navUsd6 = parseDecimalToUsd6(token.latest_nav.nav);
+  } catch (e) {
+    return err(
+      "nav_malformed",
+      `NAV for ${safeSymbol} is not a valid decimal price. Open the dashboard /trade page directly.`
+    );
+  }
+  if (navUsd6 <= 0n) {
+    return err(
+      "nav_non_positive",
+      `NAV for ${safeSymbol} is non-positive. Cannot quote a buy.`
+    );
+  }
+  let notionalUsd6;
+  try {
+    notionalUsd6 = parseDecimalToUsd6(input.amountUsdc);
+  } catch (e) {
+    return err(
+      "invalid_amount",
+      `amountUsdc "${input.amountUsdc}" is not a valid decimal mhUSDC amount.`
+    );
+  }
+  if (notionalUsd6 <= 0n) {
+    return err(
+      "invalid_amount",
+      "amountUsdc must be greater than zero."
+    );
+  }
+  const shares = computeSharesFromUsd6(notionalUsd6, navUsd6);
+  if (shares <= 0n) {
+    const navDisplay2 = formatUsd6AsDecimal(navUsd6);
+    return err(
+      "amount_too_small_for_share",
+      `${input.amountUsdc} mhUSDC isn't enough to buy 1 share of ${safeSymbol} at the current NAV of $${navDisplay2}/share. Need at least ${navDisplay2} mhUSDC to buy 1 share. Ask the user for a larger amount, or chain muhaven.cash.wrap first if they're short on mhUSDC.`
+    );
+  }
+  const effectiveNotionalUsd6 = shares * navUsd6;
+  const effectiveNotionalDisplay = formatUsd6AsDecimal(effectiveNotionalUsd6);
+  const navDisplay = formatUsd6AsDecimal(navUsd6);
+  const sharesStr = shares.toString();
   const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "buy", {
-    token: input.token,
-    amount: input.amountUsdc
+    token: token.symbol,
+    amount: sharesStr
   });
   return ok({
     dashboardUrl,
     action: "buy",
-    instructions: `Open this link to review and authorize the buy of ${input.amountUsdc} mhUSDC of ${input.token}:
+    instructions: `Open this link to review and authorize the buy of ${sharesStr} ${safeSymbol} shares (~${effectiveNotionalDisplay} mhUSDC at current NAV $${navDisplay}/share):
 ${dashboardUrl}`,
-    echo: { action: "buy", token: input.token, amount: input.amountUsdc }
+    echo: {
+      action: "buy",
+      token: token.symbol,
+      amount: sharesStr,
+      shares: sharesStr,
+      // Carry the original request + the conversion math so the LLM
+      // (and a human auditor reading the trace) can see why the URL
+      // shows the share count instead of the user-stated notional.
+      amountUsdc: input.amountUsdc,
+      effectiveNotionalUsd6: effectiveNotionalUsd6.toString(),
+      navUsd6: navUsd6.toString()
+    }
   });
 }
 async function positionSell(input, deps) {
@@ -1148,6 +1300,10 @@ var HANDLERS = {
     schema: ReadAuditInputSchema,
     handler: readAudit
   },
+  "muhaven.read.activity": {
+    schema: ReadActivityInputSchema,
+    handler: readActivity
+  },
   "muhaven.position.buy": {
     schema: PositionBuyInputSchema,
     handler: positionBuy
@@ -1252,7 +1408,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.0";
+    return "0.2.1";
   }
 }
 function toJsonInputSchema(schema) {

package/dist/index.d.cts

@@ -263,6 +263,14 @@ declare class BackendClient {
      * Authorization header.
      */
     postUnauth<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * GET variant that sends no Authorization header. Use for backend
+     * endpoints that are intentionally public (e.g. `/api/v1/tokens`
+     * which the marketplace + the 0.2.1 `positionBuy` NAV-conversion
+     * both read). Avoids triggering the AUTH_REQUIRED branch for the
+     * "not yet logged in" case on read paths that don't need auth.
+     */
+    getUnauth<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
     private buildUrl;
     private exchangeWithRetry;
     private exchange;
@@ -305,14 +313,15 @@ interface ToolDescriptor {
     readonly sensitive: boolean;
 }
 /**
- * The 22 Wave 4 MCP tools across five groups:
- *   muhaven.read.*       (7 — incl. P11 protection_coverage + kyc_attestation)
+ * The 23 MCP tools across five groups:
+ *   muhaven.read.*       (8 — incl. P11 protection_coverage + kyc_attestation
+ *                            + 0.2.1 read.activity for Path C settle verify)
  *   muhaven.position.*   (4)
  *   muhaven.policy.*     (4)
  *   muhaven.issuer.*     (5 — P7)
  *   muhaven.governance.* (2 — P11; cast_vote frontend runner deferred to Wave 5)
  *
- * `MUHAVEN_READ_ONLY=true` exposes only the 7 `muhaven.read.*` tools.
+ * `MUHAVEN_READ_ONLY=true` exposes only the 8 `muhaven.read.*` tools.
  * P5's `muhaven.checkout.*` namespace was retired before Wave 4 close — the
  * hosted checkout surface ships as a separate Vite SPA (apps/checkout-pay/),
  * not as an MCP tool group.

package/dist/index.d.ts

@@ -263,6 +263,14 @@ declare class BackendClient {
      * Authorization header.
      */
     postUnauth<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * GET variant that sends no Authorization header. Use for backend
+     * endpoints that are intentionally public (e.g. `/api/v1/tokens`
+     * which the marketplace + the 0.2.1 `positionBuy` NAV-conversion
+     * both read). Avoids triggering the AUTH_REQUIRED branch for the
+     * "not yet logged in" case on read paths that don't need auth.
+     */
+    getUnauth<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
     private buildUrl;
     private exchangeWithRetry;
     private exchange;
@@ -305,14 +313,15 @@ interface ToolDescriptor {
     readonly sensitive: boolean;
 }
 /**
- * The 22 Wave 4 MCP tools across five groups:
- *   muhaven.read.*       (7 — incl. P11 protection_coverage + kyc_attestation)
+ * The 23 MCP tools across five groups:
+ *   muhaven.read.*       (8 — incl. P11 protection_coverage + kyc_attestation
+ *                            + 0.2.1 read.activity for Path C settle verify)
  *   muhaven.position.*   (4)
  *   muhaven.policy.*     (4)
  *   muhaven.issuer.*     (5 — P7)
  *   muhaven.governance.* (2 — P11; cast_vote frontend runner deferred to Wave 5)
  *
- * `MUHAVEN_READ_ONLY=true` exposes only the 7 `muhaven.read.*` tools.
+ * `MUHAVEN_READ_ONLY=true` exposes only the 8 `muhaven.read.*` tools.
  * P5's `muhaven.checkout.*` namespace was retired before Wave 4 close — the
  * hosted checkout surface ships as a separate Vite SPA (apps/checkout-pay/),
  * not as an MCP tool group.

package/dist/index.js

@@ -373,6 +373,23 @@ var BackendClient = class {
       false
     );
   }
+  /**
+   * GET variant that sends no Authorization header. Use for backend
+   * endpoints that are intentionally public (e.g. `/api/v1/tokens`
+   * which the marketplace + the 0.2.1 `positionBuy` NAV-conversion
+   * both read). Avoids triggering the AUTH_REQUIRED branch for the
+   * "not yet logged in" case on read paths that don't need auth.
+   */
+  async getUnauth(path, query) {
+    const url = this.buildUrl(path, query);
+    return this.exchange(
+      "GET",
+      url,
+      void 0,
+      /* withAuth */
+      false
+    );
+  }
   buildUrl(path, query) {
     if (!path.startsWith("/")) {
       throw new BackendError("bad_request", `path must start with "/": ${path}`);
@@ -496,16 +513,22 @@ var TOOL_DESCRIPTORS = [
     description: `Return the authenticated user's tiered-autonomy audit log entries. Cursor-paginated. Useful for forensic review ("why was I paused?") and grant-reviewer demos. Read-only \u2014 never exposes other users' data.`,
     sensitive: false
   },
+  {
+    name: "muhaven.read.activity",
+    group: "read",
+    description: "Return the authenticated investor's on-chain activity feed (buys / sells / wraps / unwraps / yield claims / transfers). Each row carries token address, tx hash, block timestamp, and event type \u2014 but NEVER cleartext amounts (encrypted handles only, decryptable client-side via permit). USE THIS to verify a Path C dashboard action settled: after position.buy / position.sell / cash.wrap, the user opens the deep-link, taps Authorize, the on-chain tx lands \u2192 a new row appears here. Far more reliable than re-calling read.portfolio (which only changes shape when a NEW token enters the catalog).",
+    sensitive: false
+  },
   {
     name: "muhaven.position.buy",
     group: "position",
-    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" \u2192 `amountUsdc: "5"`). Token accepts either a symbol ("TBILL1") or 0x-address. The `amountUsdc` field is HUMAN-DECIMAL mhUSDC ("5" = 5 mhUSDC, "0.5" = half a mhUSDC) \u2014 NOT base-6 integer. Max 6 fractional digits. Settlement is NOT observable from MCP \u2014 verify by calling muhaven.read.portfolio after the user confirms done.',
+    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" \u2192 `amountUsdc: "5"`). Token accepts either a symbol ("TBILL1") or 0x-address. The `amountUsdc` field is HUMAN-DECIMAL mhUSDC ("5" = 5 mhUSDC, "0.5" = half a mhUSDC) \u2014 NOT base-6 integer. Max 6 fractional digits. The tool fetches the current on-chain NAV for the token and converts the notional to integer shares (floor) before building the URL \u2014 so "Buy 3 mhUSDC of GOLD1" at NAV $0.01 becomes "Buy 300 GOLD1 shares (~3 mhUSDC)". Refuses with `amount_too_small_for_share` when the notional won\'t buy at least 1 share at current NAV; the error message tells the user the minimum mhUSDC needed. Settlement is NOT observable from MCP \u2014 verify by calling muhaven.read.activity after the user confirms done (a new "buy" row with the tx hash will appear).',
     sensitive: true
   },
   {
     name: "muhaven.position.sell",
     group: "position",
-    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 POSITIVE INTEGER share count, NOT mhUSDC notional) \u2014 fhERC-20 shares have no decimals so fractional inputs are rejected.",
+    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 POSITIVE INTEGER share count, NOT mhUSDC notional) \u2014 fhERC-20 shares have no decimals so fractional inputs are rejected. Verify settlement by calling muhaven.read.activity (look for a "sell" or "sell-queued" row with the tx hash).',
     sensitive: true
   },
   {
@@ -524,7 +547,7 @@ var TOOL_DESCRIPTORS = [
   {
     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.',
+    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). Verify settlement by calling muhaven.read.activity (a new "wrap" row will appear with the tx hash).',
     sensitive: true
   },
   {
@@ -692,6 +715,10 @@ var ReadAuditInputSchema = z.object({
   cursor: z.string().min(1).max(512).optional(),
   limit: z.number().int().min(1).max(200).optional()
 }).strict();
+var ReadActivityInputSchema = z.object({
+  limit: z.number().int().min(1).max(50).optional(),
+  offset: z.number().int().min(0).max(1e3).optional()
+}).strict();
 var decimalUsdcAmountSchema = z.string().regex(
   /^(0|[1-9]\d*)(\.\d{1,6})?$/,
   'must be a positive decimal mhUSDC amount with at most 6 fractional digits (e.g. "5", "0.5", "1234.567")'
@@ -812,6 +839,37 @@ function authRequiredPayload() {
   };
 }
 
+// src/tools/decimal.ts
+function parseDecimalToUsd6(decimal) {
+  const m = /^(\d+)(?:\.(\d+))?$/.exec(decimal);
+  if (!m) {
+    throw new Error(`Invalid decimal price: ${JSON.stringify(decimal)}`);
+  }
+  const intPart = m[1];
+  const fracPart = m[2] ?? "";
+  const fracPadded = (fracPart + "000000").slice(0, 6);
+  return BigInt(intPart + fracPadded);
+}
+function computeSharesFromUsd6(notionalUsd6, navUsd6) {
+  if (navUsd6 <= 0n) {
+    throw new Error("navUsd6 must be positive");
+  }
+  if (notionalUsd6 < 0n) {
+    throw new Error("notionalUsd6 must be non-negative");
+  }
+  return notionalUsd6 / navUsd6;
+}
+function formatUsd6AsDecimal(usd6) {
+  if (usd6 < 0n) {
+    throw new Error("usd6 must be non-negative");
+  }
+  const whole = usd6 / 1000000n;
+  const frac = usd6 % 1000000n;
+  if (frac === 0n) return whole.toString();
+  const fracStr = frac.toString().padStart(6, "0").replace(/0+$/, "");
+  return `${whole.toString()}.${fracStr}`;
+}
+
 // src/tools/handlers.ts
 function ok(data) {
   return { ok: true, data };
@@ -880,6 +938,17 @@ async function readAudit(input, deps) {
     return mapBackendError(e);
   }
 }
+async function readActivity(input, deps) {
+  try {
+    const data = await deps.backend.get("/api/v1/activity", {
+      limit: input.limit,
+      offset: input.offset
+    });
+    return ok(data);
+  } catch (e) {
+    return mapBackendError(e);
+  }
+}
 function buildPositionDeeplink(dashboardBaseUrl, action, params) {
   const base = dashboardBaseUrl.replace(/\/+$/, "");
   const path = action === "buy" || action === "sell" ? "/trade" : action === "claim" ? "/yields" : "/cash";
@@ -892,17 +961,100 @@ function buildPositionDeeplink(dashboardBaseUrl, action, params) {
 function resolveDashboardBaseUrl(deps) {
   return deps.dashboardBaseUrl ?? "https://muhaven.app";
 }
+function resolveTokenInCatalog(identifier, catalog) {
+  const needle = identifier.toLowerCase();
+  return catalog.find(
+    (t) => t.address.toLowerCase() === needle || t.symbol.toLowerCase() === needle
+  ) ?? null;
+}
+function sanitizeSymbolForLlmContext(raw) {
+  const cleaned = raw.replace(/[^A-Za-z0-9_-]/g, "?");
+  return cleaned.length > 16 ? cleaned.slice(0, 16) : cleaned;
+}
 async function positionBuy(input, deps) {
+  let catalog;
+  try {
+    catalog = await deps.backend.getUnauth("/api/v1/tokens");
+  } catch (e) {
+    return mapBackendError(e);
+  }
+  const token = resolveTokenInCatalog(input.token, catalog.tokens ?? []);
+  if (!token) {
+    return err(
+      "token_not_found",
+      `Token "${sanitizeSymbolForLlmContext(input.token)}" is not in the MuHaven catalog. Call muhaven.read.tokens for the canonical symbol list.`
+    );
+  }
+  const safeSymbol = sanitizeSymbolForLlmContext(token.symbol);
+  if (!token.latest_nav || !token.latest_nav.nav) {
+    return err(
+      "nav_unavailable",
+      `No NAV snapshot available for ${safeSymbol} yet. The nav-worker may not have written one \u2014 retry shortly, or use the dashboard /trade page directly.`
+    );
+  }
+  let navUsd6;
+  try {
+    navUsd6 = parseDecimalToUsd6(token.latest_nav.nav);
+  } catch (e) {
+    return err(
+      "nav_malformed",
+      `NAV for ${safeSymbol} is not a valid decimal price. Open the dashboard /trade page directly.`
+    );
+  }
+  if (navUsd6 <= 0n) {
+    return err(
+      "nav_non_positive",
+      `NAV for ${safeSymbol} is non-positive. Cannot quote a buy.`
+    );
+  }
+  let notionalUsd6;
+  try {
+    notionalUsd6 = parseDecimalToUsd6(input.amountUsdc);
+  } catch (e) {
+    return err(
+      "invalid_amount",
+      `amountUsdc "${input.amountUsdc}" is not a valid decimal mhUSDC amount.`
+    );
+  }
+  if (notionalUsd6 <= 0n) {
+    return err(
+      "invalid_amount",
+      "amountUsdc must be greater than zero."
+    );
+  }
+  const shares = computeSharesFromUsd6(notionalUsd6, navUsd6);
+  if (shares <= 0n) {
+    const navDisplay2 = formatUsd6AsDecimal(navUsd6);
+    return err(
+      "amount_too_small_for_share",
+      `${input.amountUsdc} mhUSDC isn't enough to buy 1 share of ${safeSymbol} at the current NAV of $${navDisplay2}/share. Need at least ${navDisplay2} mhUSDC to buy 1 share. Ask the user for a larger amount, or chain muhaven.cash.wrap first if they're short on mhUSDC.`
+    );
+  }
+  const effectiveNotionalUsd6 = shares * navUsd6;
+  const effectiveNotionalDisplay = formatUsd6AsDecimal(effectiveNotionalUsd6);
+  const navDisplay = formatUsd6AsDecimal(navUsd6);
+  const sharesStr = shares.toString();
   const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "buy", {
-    token: input.token,
-    amount: input.amountUsdc
+    token: token.symbol,
+    amount: sharesStr
   });
   return ok({
     dashboardUrl,
     action: "buy",
-    instructions: `Open this link to review and authorize the buy of ${input.amountUsdc} mhUSDC of ${input.token}:
+    instructions: `Open this link to review and authorize the buy of ${sharesStr} ${safeSymbol} shares (~${effectiveNotionalDisplay} mhUSDC at current NAV $${navDisplay}/share):
 ${dashboardUrl}`,
-    echo: { action: "buy", token: input.token, amount: input.amountUsdc }
+    echo: {
+      action: "buy",
+      token: token.symbol,
+      amount: sharesStr,
+      shares: sharesStr,
+      // Carry the original request + the conversion math so the LLM
+      // (and a human auditor reading the trace) can see why the URL
+      // shows the share count instead of the user-stated notional.
+      amountUsdc: input.amountUsdc,
+      effectiveNotionalUsd6: effectiveNotionalUsd6.toString(),
+      navUsd6: navUsd6.toString()
+    }
   });
 }
 async function positionSell(input, deps) {
@@ -1144,6 +1296,10 @@ var HANDLERS = {
     schema: ReadAuditInputSchema,
     handler: readAudit
   },
+  "muhaven.read.activity": {
+    schema: ReadActivityInputSchema,
+    handler: readActivity
+  },
   "muhaven.position.buy": {
     schema: PositionBuyInputSchema,
     handler: positionBuy
@@ -1248,7 +1404,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.0";
+    return "0.2.1";
   }
 }
 function toJsonInputSchema(schema) {

package/manifest.json

@@ -3,9 +3,9 @@
   "manifest_version": "0.2",
   "name": "muhaven-mcp",
   "display_name": "MuHaven (RWA portfolio)",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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.",
+  "long_description": "MuHaven MCP exposes 23 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 deep-link to the dashboard for passkey signing — 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": {
     "name": "MuHaven",
     "email": "hello@muhaven.app",
@@ -42,7 +42,8 @@
     { "name": "muhaven.read.distribution", "description": "Distribution status for a (token, epoch).", "sensitive": false },
     { "name": "muhaven.read.tokens", "description": "RWA tokens the user holds.", "sensitive": false },
     { "name": "muhaven.read.audit", "description": "User's tiered-autonomy audit log.", "sensitive": false },
-    { "name": "muhaven.position.buy", "description": "Propose a Subscription buy. Returns unsigned UserOp.", "sensitive": true },
+    { "name": "muhaven.read.activity", "description": "User's on-chain activity feed (buys / sells / wraps / yields) — verify Path C settles.", "sensitive": false },
+    { "name": "muhaven.position.buy", "description": "Prepare a Subscription buy (converts mhUSDC → integer shares at current NAV). Returns dashboard deep-link.", "sensitive": true },
     { "name": "muhaven.position.sell", "description": "Propose a redemption-queue sell. Returns unsigned UserOp.", "sensitive": true },
     { "name": "muhaven.position.claim", "description": "Propose a yield claim. Returns unsigned UserOp.", "sensitive": true },
     { "name": "muhaven.position.rebalance", "description": "Propose a multi-leg atomic rebalance.", "sensitive": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhaven/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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-17T19:03:52.417Z",
+  "generatedAt": "2026-05-18T03:07:17.347Z",
   "tools": [
     {
       "name": "muhaven.read.portfolio",
@@ -21,13 +21,17 @@
       "name": "muhaven.read.audit",
       "sha256": "a55b698911e8774b8022c98e86582368e76b12a7c8447afa57a4cfa9d3d6ae04"
     },
+    {
+      "name": "muhaven.read.activity",
+      "sha256": "43294a47fa629b5a009a4fa3860aef4764d7c67ce7f9349cf70c4a1614c42d29"
+    },
     {
       "name": "muhaven.position.buy",
-      "sha256": "4266f9d91df2086729709e3b1e76c34cb598fd90265aa24de90c256a3a6c217a"
+      "sha256": "3a26611be6f189d5c67d74e9db18f1c18888e2d9851222f94c320d975005b5c5"
     },
     {
       "name": "muhaven.position.sell",
-      "sha256": "58c5090b04ecf4068dafe1f6a62e60b0befc9e0ad1cbbaedbab57e623c0194ce"
+      "sha256": "2cd3cd7b542de0273b7314d82f8d8c811cff439d62c3f16fa38109a493bb9c7f"
     },
     {
       "name": "muhaven.position.claim",
@@ -39,7 +43,7 @@
     },
     {
       "name": "muhaven.cash.wrap",
-      "sha256": "1ae4cb949e0d09e7fb7e8957e51bfc63b43397c253849c217b835aaa9505b8c9"
+      "sha256": "e74607e49092bd7090b9ce6df92936713c01e2da4ad5a728f55064d5026bcaec"
     },
     {
       "name": "muhaven.policy.set_tier",