@solvapay/mcp-core 0.1.0 → 0.2.0

package/dist/index.js

@@ -17,9 +17,7 @@ var MCP_TOOL_NAMES = {
 var SOLVAPAY_MCP_VIEW_KINDS = [
   "checkout",
   "account",
-  "topup",
-  "paywall",
-  "nudge"
+  "topup"
 ];
 var TOOL_FOR_VIEW = {
   checkout: "upgrade",
@@ -365,41 +363,19 @@ function previewJson(value, max = 400) {
   }
 }
 
-// src/paywall-meta.ts
-function buildPaywallUiMeta(input) {
-  return {
-    ui: {
-      resourceUri: input.resourceUri
-    }
-  };
-}
-
 // src/paywallToolResult.ts
 import { PaywallError } from "@solvapay/server";
-async function paywallToolResult(errOrGate, ctx) {
+async function paywallToolResult(errOrGate, _ctx = {}) {
   const paywallContent = errOrGate instanceof PaywallError ? errOrGate.structuredContent : errOrGate;
   const narrationText = errOrGate instanceof PaywallError ? errOrGate.message : paywallContent.message;
-  let structuredContent;
-  if (ctx.buildBootstrap) {
-    const bootstrap = await ctx.buildBootstrap("paywall", ctx.extra, {
-      paywall: paywallContent
-    });
-    structuredContent = bootstrap;
-  } else {
-    structuredContent = paywallContent;
-  }
   return {
     // Deliberately `false`: paywall is a user-actionable gate, not a
-    // tool failure. Hosts short-circuit on `isError: true` and render
-    // the error text instead of opening the UI resource advertised by
-    // `_meta.ui`, which meant the paywall widget never appeared on
-    // MCPJam / Claude Desktop / ChatGPT Apps. The `structuredContent`
-    // and `content[0].text` still carry the gate reason so the LLM
-    // can narrate it, while `_meta.ui` triggers the widget.
+    // tool failure. The LLM narrates the recovery from
+    // `content[0].text` and the structured gate content on
+    // `structuredContent` is available for programmatic consumers.
     isError: false,
     content: [{ type: "text", text: narrationText }],
-    structuredContent,
-    _meta: buildPaywallUiMeta({ resourceUri: ctx.resourceUri })
+    structuredContent: paywallContent
   };
 }
 
@@ -429,6 +405,30 @@ function mergeCsp(overrides) {
   };
 }
 
+// src/hideToolsByAudience.ts
+function applyHideToolsByAudience(server, audiences) {
+  if (!audiences || audiences.length === 0) return;
+  const hidden = new Set(audiences);
+  const inner = server.server;
+  if (!inner || typeof inner !== "object" || !(inner._requestHandlers instanceof Map)) {
+    return;
+  }
+  const handlers = inner._requestHandlers;
+  const original = handlers.get("tools/list");
+  if (!original) return;
+  handlers.set("tools/list", async (req, extra) => {
+    const res = await original(req, extra);
+    const tools = Array.isArray(res?.tools) ? res.tools : [];
+    return {
+      ...res,
+      tools: tools.filter((t) => {
+        const audience = t?._meta?.audience;
+        return !hidden.has(typeof audience === "string" ? audience : "");
+      })
+    };
+  });
+}
+
 // src/descriptors.ts
 import {
   activatePlanCore,
@@ -472,7 +472,7 @@ function createBuildBootstrapPayload(options) {
   };
   const buildRequest = (extra) => buildSolvaPayRequest(extra, { getCustomerRef });
   const productQueryRequest = () => buildSolvaPayRequest(void 0, { query: { productRef }, getCustomerRef: () => null });
-  return async (view, extra, extras = {}) => {
+  return async (view, extra) => {
     const customerRef = getCustomerRef(extra);
     const wrapError = (promise) => promise.catch((err) => ({
       error: err instanceof Error ? err.message : String(err),
@@ -519,7 +519,7 @@ function createBuildBootstrapPayload(options) {
       balance: okOrNull(balanceResult),
       usage: okOrNull(usageResult)
     } : null;
-    const payload = {
+    return {
       view,
       productRef,
       stripePublishableKey,
@@ -529,8 +529,6 @@ function createBuildBootstrapPayload(options) {
       plans,
       customer
     };
-    if (extras.paywall) payload.paywall = extras.paywall;
-    return payload;
   };
 }
 
@@ -564,9 +562,13 @@ with clickable URLs for text-only hosts.
 
 Each intent tool returns a full \`BootstrapPayload\` (merchant + product + plans
 + customer snapshot) so the embedded UI never fires per-view read calls. When
-a paywalled data tool hits the usage limit, its response carries the same
-payload with \`view: "paywall"\`, letting the host open the UI directly on the
-paywall screen \u2014 no second tool call required.
+a paywalled data tool hits the usage limit, its response is plain text: the
+\`content[0].text\` narration names the recovery intent tool
+(\`upgrade\` / \`topup\` / \`activate_plan\`) and inlines \`gate.checkoutUrl\` for
+terminal-first hosts. The structured gate rides on \`structuredContent\` for
+programmatic consumers. No widget iframe opens for a gate \u2014 the LLM reads the
+narration and, if the user agrees, calls the named intent tool which mounts
+the checkout / topup / account surface.
 
 Auth is handled by the SolvaPay OAuth bridge (see \`createMcpOAuthBridge\`). The
 bridge injects \`customer_ref\` onto every authenticated request; tools that
@@ -974,7 +976,7 @@ function buildSolvaPayPrompts(options = {}) {
 }
 
 // src/payable-handler.ts
-import { isPaywallStructuredContent } from "@solvapay/server";
+import { buildNudgeMessage, isPaywallStructuredContent } from "@solvapay/server";
 
 // src/response-context.ts
 import { PaywallError as PaywallError2 } from "@solvapay/server";
@@ -1079,7 +1081,7 @@ function buildResponseContext(params) {
 
 // src/payable-handler.ts
 function buildPayableHandler(solvaPay, ctx, handler) {
-  const { product, resourceUri, buildBootstrap, getCustomerRef } = ctx;
+  const { product, getCustomerRef } = ctx;
   const wrappedBusinessLogic = async (args, handlerContext) => {
     const limits = handlerContext?.limits ?? null;
     const customerRef = handlerContext?.customerRef ?? "";
@@ -1095,60 +1097,44 @@ function buildPayableHandler(solvaPay, ctx, handler) {
   return async (args, extra) => {
     const result = await protectedHandler(args, extra);
     if (isPaywallStructuredContent(result.structuredContent)) {
-      const existingMeta = typeof result._meta === "object" && result._meta !== null ? result._meta : {};
-      const gateContent = result.structuredContent;
-      const structuredContent = buildBootstrap ? await buildBootstrap("paywall", extra, {
-        paywall: gateContent
-      }) : result.structuredContent;
       return {
         ...result,
         isError: false,
-        structuredContent,
-        _meta: {
-          ...existingMeta,
-          ...buildPaywallUiMeta({ resourceUri })
-        }
+        structuredContent: result.structuredContent
       };
     }
     if (result.isError) {
       return result;
     }
     const envelope = assertResponseResult(result.structuredContent);
-    return unwrapResponseEnvelope(
-      result,
-      envelope,
-      resourceUri,
-      buildBootstrap,
-      extra
-    );
+    return unwrapResponseEnvelope(result, envelope, extra);
   };
 }
-async function unwrapResponseEnvelope(adapterResult, envelope, resourceUri, buildBootstrap, extra) {
+async function unwrapResponseEnvelope(adapterResult, envelope, _extra) {
   const { data, options, emittedBlocks } = envelope;
   const textOverride = options?.text;
   const nudge = options?.nudge;
-  const primaryText = typeof textOverride === "string" ? textOverride : JSON.stringify(data);
+  const baseText = typeof textOverride === "string" ? textOverride : JSON.stringify(data);
+  let primaryText = baseText;
+  if (nudge) {
+    const nudgeText = nudge.message && nudge.message.length > 0 ? nudge.message : buildNudgeMessage(
+      // `buildNudgeMessage` only reads the state kind to pick
+      // copy; for merchant-supplied nudges we don't have a
+      // `LimitResponseWithPlan` in hand here, so we defer to
+      // the nudge's own kind → state mapping. `low-balance` →
+      // topup, everything else → upgrade.
+      nudge.kind === "low-balance" ? { kind: "topup_required" } : { kind: "upgrade_required" },
+      null
+    );
+    primaryText = baseText.length > 0 ? `${baseText}
+
+${nudgeText}` : nudgeText;
+  }
   const content = [
     ...emittedBlocks ?? [],
     { type: "text", text: primaryText }
   ];
   const existingMeta = typeof adapterResult._meta === "object" && adapterResult._meta !== null ? adapterResult._meta : {};
-  if (nudge) {
-    const structuredContent = buildBootstrap ? {
-      ...await buildBootstrap("nudge", extra),
-      nudge,
-      data
-    } : data;
-    return {
-      ...adapterResult,
-      content,
-      structuredContent,
-      _meta: {
-        ...existingMeta,
-        ...buildNudgeUiMeta({ resourceUri, nudge })
-      }
-    };
-  }
   return {
     ...adapterResult,
     content,
@@ -1156,9 +1142,6 @@ async function unwrapResponseEnvelope(adapterResult, envelope, resourceUri, buil
     ...Object.keys(existingMeta).length > 0 ? { _meta: existingMeta } : {}
   };
 }
-function buildNudgeUiMeta(input) {
-  return { ui: { resourceUri: input.resourceUri, nudge: input.nudge } };
-}
 
 // src/oauth-discovery.ts
 var DEFAULT_OAUTH_PATHS = {
@@ -1304,16 +1287,17 @@ export {
   TOOL_FOR_VIEW,
   VIEW_FOR_OPEN_TOOL,
   VIEW_FOR_TOOL,
+  applyHideToolsByAudience,
   balanceSummary,
   buildAuthInfoFromBearer,
   buildPayableHandler,
-  buildPaywallUiMeta,
   buildSolvaPayDescriptors,
   buildSolvaPayPrompts,
   buildSolvaPayRequest,
   createBuildBootstrapPayload,
   decodeJwtPayload,
   defaultGetCustomerRef,
+  deriveIcons,
   enrichPurchase,
   extractBearerToken,
   getCustomerRefFromBearerAuthHeader,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/mcp-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-neutral MCP contracts for the SolvaPay SDK (tool names, descriptors, payable handler, paywall meta, CSP, bootstrap payload, OAuth discovery JSON builders, bearer/JWT helpers).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,14 +34,14 @@
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0",
-    "@solvapay/server": "1.0.8-preview.10"
+    "@solvapay/server": "^1.0.8"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.2",
     "zod": "^4.3.6",
-    "@solvapay/server": "1.0.8-preview.10",
+    "@solvapay/server": "1.0.8",
     "@solvapay/test-utils": "^0.0.0"
   },
   "scripts": {