@solvapay/mcp-core 0.1.0 → 0.2.0

package/README.md

@@ -3,16 +3,19 @@
 Framework-neutral MCP (Model Context Protocol) contracts for the SolvaPay SDK.
 
 This package owns the shapes that cross the SolvaPay server ↔ client ↔
-adapter boundary: tool names, descriptor builder, paywall `_meta.ui`
-envelope, Stripe CSP baseline, bootstrap payload, pure OAuth discovery
-JSON builders, JWT bearer helpers.
+adapter boundary: tool names, descriptor builder (for SolvaPay intent
+tools, which advertise `_meta.ui.resourceUri` on `tools/list` per
+SEP-1865; merchant payable tools do NOT), the `BootstrapPayload`
+shape carried on `structuredContent`, Stripe CSP baseline, pure OAuth
+discovery JSON builders, and JWT bearer helpers.
 
 It does **not** depend on `@modelcontextprotocol/sdk`,
 `@modelcontextprotocol/ext-apps`, or any runtime-specific HTTP plumbing.
 The official `@modelcontextprotocol/*` adapter lives in
-[`@solvapay/mcp`](../mcp); Node `(req, res, next)` OAuth middleware lives
-in [`@solvapay/mcp-express`](../mcp-express); fetch-first OAuth + the
-turnkey handler lives in [`@solvapay/mcp-fetch`](../mcp-fetch).
+[`@solvapay/mcp`](../mcp); Node `(req, res, next)` OAuth middleware ships
+as the [`@solvapay/mcp/express`](../mcp/src/express) subpath export;
+fetch-first OAuth + the turnkey handler ships as the
+[`@solvapay/mcp/fetch`](../mcp/src/fetch) subpath export.
 
 ## Install
 
@@ -26,14 +29,30 @@ pnpm add @solvapay/mcp-core @solvapay/server
 |---|---|
 | `MCP_TOOL_NAMES`, `McpToolName` | You're implementing a SolvaPay MCP transport tool on any framework and need the canonical tool names |
 | `buildSolvaPayDescriptors(opts)` | You're writing an MCP adapter (`fastmcp`, raw JSON-RPC) and want the full SolvaPay tool surface as descriptor objects |
-| `buildPayableHandler(solvaPay, ctx, handler)` | You're hand-rolling a paywall-protected tool and need the `_meta.ui` envelope auto-attached on paywall results |
-| `paywallToolResult(errOrGate, ctx)` | You have a `PaywallError` (legacy `try/catch`) or a `PaywallStructuredContent` gate from `paywall.decide()` and want to return it with the right `_meta.ui` + `BootstrapPayload` |
-| `buildPaywallUiMeta({ resourceUri, toolName })` | You're building the `_meta.ui` envelope yourself |
+| `buildPayableHandler(solvaPay, ctx, handler)` | You're hand-rolling a paywall-protected tool and want the pre-check paywall to return a clean text-only narration on `content[0].text` + the gate on `structuredContent` |
+| `paywallToolResult(errOrGate)` | You have a `PaywallError` (legacy `try/catch`) or a `PaywallStructuredContent` gate from `paywall.decide()` and want a text-only tool result |
 | `SOLVAPAY_DEFAULT_CSP`, `mergeCsp(overrides)` | You're registering the SolvaPay UI resource and want the Stripe allow-list baked in |
 | `getOAuthAuthorizationServerResponse(opts)`, `getOAuthProtectedResourceResponse(url)` | You're serving the `.well-known/*` discovery JSON from any runtime |
 | `buildAuthInfoFromBearer(header, opts)` | You're plugging a raw `Authorization: Bearer …` header into an MCP `authInfo` envelope |
 | `McpBearerAuthError`, `extractBearerToken`, `decodeJwtPayload`, `getCustomerRefFromJwtPayload`, `getCustomerRefFromBearerAuthHeader` | Low-level JWT bearer parsing — no signature verification (validate upstream first) |
 
+## How paywalls work
+
+Paywall responses from `buildPayableHandler` / `paywallToolResult` are
+**text-only**. `content[0].text` carries a human narration that names
+the recovery intent tool (`upgrade` / `topup` / `activate_plan`) and
+inlines `gate.checkoutUrl` for terminal-first hosts. `isError` is
+always `false` — a gate is a user-actionable signal, not a tool
+failure. `structuredContent = gate` is still emitted for programmatic
+consumers.
+
+The widget iframe is reserved for the three deliberate intent tools
+(`upgrade` / `manage_account` / `topup`), which advertise
+`_meta.ui.resourceUri` on their descriptors. Merchant payable tools
+don't, so hosts don't open an uninvited iframe on a successful data
+call or on a paywall — the LLM narrates the recovery and calls the
+intent tool, which mounts the widget.
+
 ## Typical usage
 
 If you're starting a new SolvaPay MCP server on the official
@@ -41,9 +60,9 @@ If you're starting a new SolvaPay MCP server on the official
 [`@solvapay/mcp`](../mcp), which wraps it with one-call ergonomics.
 
 If you need HTTP-level OAuth handlers, pair this package with either
-[`@solvapay/mcp-express`](../mcp-express) (Node) or
-[`@solvapay/mcp-fetch`](../mcp-fetch) (Deno / Supabase Edge / Cloudflare
-Workers / Bun / Next edge).
+[`@solvapay/mcp/express`](../mcp/src/express) (Node) or
+[`@solvapay/mcp/fetch`](../mcp/src/fetch) (Deno / Supabase Edge /
+Cloudflare Workers / Bun / Next edge).
 
 If you're writing a new adapter (fastmcp, custom JSON-RPC):
 
@@ -74,7 +93,7 @@ myAdapter.registerResource(resource)
 ## See also
 
 - [`@solvapay/mcp`](../mcp) — official `@modelcontextprotocol/sdk` + `ext-apps` adapter (`createSolvaPayMcpServer`)
-- [`@solvapay/mcp-express`](../mcp-express) — Node `(req, res, next)` OAuth middleware stack
-- [`@solvapay/mcp-fetch`](../mcp-fetch) — fetch-first OAuth handlers + turnkey `createSolvaPayMcpFetchHandler`
+- [`@solvapay/mcp/express`](../mcp/src/express) — Node `(req, res, next)` OAuth middleware stack
+- [`@solvapay/mcp/fetch`](../mcp/src/fetch) — fetch-first OAuth handlers + turnkey `createSolvaPayMcpFetchHandler` / `createSolvaPayMcpFetch`
 - [`@solvapay/server`](../server) — core SDK (paywall, webhooks, `*Core` helpers)
 - [`@solvapay/react/mcp`](../react) — React provider + views for the MCP App UI shell

package/dist/index.cjs

@@ -43,16 +43,17 @@ __export(index_exports, {
   TOOL_FOR_VIEW: () => TOOL_FOR_VIEW,
   VIEW_FOR_OPEN_TOOL: () => VIEW_FOR_OPEN_TOOL,
   VIEW_FOR_TOOL: () => VIEW_FOR_TOOL,
+  applyHideToolsByAudience: () => applyHideToolsByAudience,
   balanceSummary: () => balanceSummary,
   buildAuthInfoFromBearer: () => buildAuthInfoFromBearer,
   buildPayableHandler: () => buildPayableHandler,
-  buildPaywallUiMeta: () => buildPaywallUiMeta,
   buildSolvaPayDescriptors: () => buildSolvaPayDescriptors,
   buildSolvaPayPrompts: () => buildSolvaPayPrompts,
   buildSolvaPayRequest: () => buildSolvaPayRequest,
   createBuildBootstrapPayload: () => createBuildBootstrapPayload,
   decodeJwtPayload: () => decodeJwtPayload,
   defaultGetCustomerRef: () => defaultGetCustomerRef,
+  deriveIcons: () => deriveIcons,
   enrichPurchase: () => enrichPurchase,
   extractBearerToken: () => extractBearerToken,
   getCustomerRefFromBearerAuthHeader: () => getCustomerRefFromBearerAuthHeader,
@@ -95,9 +96,7 @@ var MCP_TOOL_NAMES = {
 var SOLVAPAY_MCP_VIEW_KINDS = [
   "checkout",
   "account",
-  "topup",
-  "paywall",
-  "nudge"
+  "topup"
 ];
 var TOOL_FOR_VIEW = {
   checkout: "upgrade",
@@ -443,41 +442,19 @@ function previewJson(value, max = 400) {
   }
 }
 
-// src/paywall-meta.ts
-function buildPaywallUiMeta(input) {
-  return {
-    ui: {
-      resourceUri: input.resourceUri
-    }
-  };
-}
-
 // src/paywallToolResult.ts
 var import_server = require("@solvapay/server");
-async function paywallToolResult(errOrGate, ctx) {
+async function paywallToolResult(errOrGate, _ctx = {}) {
   const paywallContent = errOrGate instanceof import_server.PaywallError ? errOrGate.structuredContent : errOrGate;
   const narrationText = errOrGate instanceof import_server.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
   };
 }
 
@@ -507,6 +484,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
 var import_server3 = require("@solvapay/server");
 var import_zod = require("zod");
@@ -531,7 +532,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),
@@ -578,7 +579,7 @@ function createBuildBootstrapPayload(options) {
       balance: okOrNull(balanceResult),
       usage: okOrNull(usageResult)
     } : null;
-    const payload = {
+    return {
       view,
       productRef,
       stripePublishableKey,
@@ -588,8 +589,6 @@ function createBuildBootstrapPayload(options) {
       plans,
       customer
     };
-    if (extras.paywall) payload.paywall = extras.paywall;
-    return payload;
   };
 }
 
@@ -623,9 +622,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
@@ -1138,7 +1141,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 ?? "";
@@ -1154,60 +1157,44 @@ function buildPayableHandler(solvaPay, ctx, handler) {
   return async (args, extra) => {
     const result = await protectedHandler(args, extra);
     if ((0, import_server5.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 : (0, import_server5.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,
@@ -1215,9 +1202,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 = {
@@ -1364,16 +1348,17 @@ function buildAuthInfoFromBearer(authorization, options = {}) {
   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,