@solvapay/mcp 0.1.0 → 0.2.0

package/README.md

@@ -8,10 +8,10 @@ Framework-neutral contracts (tool names, descriptors, paywall meta,
 OAuth discovery JSON, JWT helpers) live in
 [`@solvapay/mcp-core`](../mcp-core) so alternative adapters
 (`fastmcp`, raw JSON-RPC) can reuse the same contract. Runtime-specific
-OAuth middleware lives alongside:
+OAuth middleware ships as two subpath exports of this package:
 
-- [`@solvapay/mcp-express`](../mcp-express) — Node `(req, res, next)`.
-- [`@solvapay/mcp-fetch`](../mcp-fetch) — Web standards `(req: Request) => Promise<Response>`.
+- [`@solvapay/mcp/express`](./src/express) — Node `(req, res, next)`.
+- [`@solvapay/mcp/fetch`](./src/fetch) — Web standards `(req: Request) => Promise<Response>` + the turnkey `createSolvaPayMcpFetch` factory for Deno / Supabase Edge / Cloudflare Workers / Bun / Next edge / Vercel Functions.
 
 ## Install
 
@@ -78,10 +78,16 @@ branded envelope produced by `ctx.respond(data, options?)`.
 ```ts
 handler: async ({ prompt }, ctx) => {
   const video = await generate(prompt)
-  // Attach an upsell nudge when the customer is low on credits.
+  // Append a text-only nudge when the customer is low on credits.
+  // The nudge message is appended to `content[0].text` as a plain
+  // suffix — no widget iframe, no `structuredContent` switch. Point
+  // the user at the recovery intent tool by name.
   if (ctx.customer.balance < 500) {
     return ctx.respond({ videoUrl: video.url }, {
-      nudge: { kind: 'low-balance', message: 'Running low on credits' },
+      nudge: {
+        kind: 'low-balance',
+        message: 'Running low on credits — call the `topup` tool to add more.',
+      },
     })
   }
   return ctx.respond({ videoUrl: video.url })
@@ -95,9 +101,10 @@ full surface. The TL;DR:
   `balance` / `remaining` / `plan` to branch on usage; call
   `ctx.customer.fresh()` for a fresh fetch when staleness matters.
 - `ctx.respond(data, options?)` — returns a branded envelope. `options`
-  carries `text` (override `content[0].text`), `nudge` (inline upsell
-  strip), and the reserved `units` (V1.1 variable-unit billing — V1
-  silently ignores).
+  carries `text` (override `content[0].text`), `nudge` (the nudge
+  message is appended to `content[0].text` as a plain-text suffix —
+  no widget surface, no `structuredContent` switch), and the reserved
+  `units` (V1.1 variable-unit billing — V1 silently ignores).
 - `ctx.gate(reason?)` — stops handler execution and routes a paywall
   response through the adapter's `formatGate` channel. Rare — the
   SDK normally fires the paywall automatically via `payable().mcp()`
@@ -106,12 +113,31 @@ full surface. The TL;DR:
   surface. V1 queues (emit) or no-ops (progress / signal); V1.1 wires
   them to SSE and transport cancellation without code changes.
 
+## How paywalls work
+
+Paywall responses from `registerPayable` tools are **text-only**:
+
+- `isError: false`, so hosts don't short-circuit on the error path.
+- `structuredContent = gate` for programmatic consumers.
+- `content[0].text` carries a state-engine-generated narration that
+  names the recovery intent tool (`upgrade` for no active plan,
+  `topup` for usage-based zero-balance, `activate_plan` for pending
+  activation) and inlines `gate.checkoutUrl` for terminal-first
+  hosts (Claude Code, CLI MCP clients).
+
+The LLM reads that narration, tells the user, and either (a) the
+user clicks the inline URL and completes checkout in the browser, or
+(b) the LLM calls the named intent tool which mounts the SolvaPay
+widget on `McpCheckoutView` / `McpTopupView`. Only those three
+intent tools advertise `_meta.ui.resourceUri` — merchant payable
+tools don't, so no uninvited iframe opens on a silent success.
+
 ## What's in the box
 
 | Export | Use when |
 |---|---|
 | `createSolvaPayMcpServer(opts)` | You want the batteries-included `McpServer` with every SolvaPay tool registered |
-| `registerPayableTool(server, name, opts)` | You want to add a paywall-protected tool to an existing `McpServer`. `_meta.ui` is attached per-result on paywall and nudge responses only, so the iframe opens only when there's something to show. |
+| `registerPayableTool(server, name, opts)` | You want to add a paywall-protected tool to an existing `McpServer`. Paywall / nudge responses are text-only narrations; the widget iframe stays reserved for the three intent tools. |
 
 ## Peer dependencies
 

package/dist/chunk-3VDAADZU.js

@@ -0,0 +1,211 @@
+// src/registerPayableTool.ts
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import {
+  buildPayableHandler
+} from "@solvapay/mcp-core";
+function registerPayableTool(server, name, options) {
+  const {
+    solvaPay,
+    schema,
+    product,
+    title,
+    description,
+    handler,
+    buildBootstrap,
+    getCustomerRef,
+    meta,
+    annotations,
+    icons
+  } = options;
+  const protectedHandler = buildPayableHandler(
+    solvaPay,
+    { product, buildBootstrap, getCustomerRef },
+    handler
+  );
+  const baseMeta = meta ?? {};
+  const baseUi = baseMeta.ui ?? {};
+  const hasIcons = icons !== void 0 && icons.length > 0;
+  const mergedUi = {
+    ...baseUi,
+    ...hasIcons ? { icons } : {}
+  };
+  const hasUi = Object.keys(mergedUi).length > 0;
+  const toolMeta = hasUi ? { ...baseMeta, ui: mergedUi } : { ...baseMeta };
+  const effectiveAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    ...annotations
+  };
+  const hasUiResource = hasUi && typeof mergedUi.resourceUri === "string";
+  const toolConfig = {
+    ...title !== void 0 ? { title } : {},
+    ...description !== void 0 ? { description } : {},
+    ...schema !== void 0 ? { inputSchema: schema } : {},
+    ...Object.keys(toolMeta).length > 0 ? { _meta: toolMeta } : {},
+    annotations: effectiveAnnotations,
+    ...icons !== void 0 && icons.length > 0 ? { icons } : {}
+  };
+  const toolCallback = async (args, extra) => await protectedHandler(args, extra);
+  if (hasUiResource) {
+    return registerAppTool(
+      server,
+      name,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      toolConfig,
+      toolCallback
+    );
+  }
+  return server.registerTool(
+    name,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toolConfig,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toolCallback
+  );
+}
+
+// src/internal/buildMcpServer.ts
+import {
+  registerAppResource,
+  registerAppTool as registerAppTool2,
+  RESOURCE_MIME_TYPE
+} from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  applyHideToolsByAudience,
+  buildSolvaPayDescriptors,
+  deriveIcons
+} from "@solvapay/mcp-core";
+function registerDescriptor(server, tool) {
+  const baseMeta = tool.meta ?? {};
+  const baseUi = baseMeta.ui ?? {};
+  const metaWithIcons = tool.icons && tool.icons.length > 0 ? { ...baseMeta, ui: { ...baseUi, icons: tool.icons } } : baseMeta;
+  registerAppTool2(
+    server,
+    tool.name,
+    {
+      ...tool.title !== void 0 ? { title: tool.title } : {},
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      _meta: metaWithIcons,
+      ...tool.annotations !== void 0 ? { annotations: tool.annotations } : {},
+      ...tool.icons !== void 0 ? { icons: tool.icons } : {}
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    },
+    // `SolvaPayCallToolResult` is a structural subset of the official
+    // SDK's `CallToolResult`; cast to erase the extra-narrow `resource`
+    // block typing the SDK expects on `{ type: 'resource' }` content.
+    async (args, extra) => await tool.handler(
+      args,
+      extra
+    )
+  );
+}
+function registerPromptDescriptor(server, prompt) {
+  const config = { description: prompt.description };
+  if (prompt.title !== void 0) config.title = prompt.title;
+  if (prompt.argsSchema !== void 0) config.argsSchema = prompt.argsSchema;
+  server.registerPrompt(
+    prompt.name,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    config,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async (args) => await prompt.handler(args ?? {})
+  );
+}
+function registerDocsResource(server, docs) {
+  server.registerResource(
+    docs.name,
+    docs.uri,
+    {
+      ...docs.title !== void 0 ? { title: docs.title } : {},
+      description: docs.description,
+      mimeType: docs.mimeType
+    },
+    async () => ({
+      contents: [
+        {
+          uri: docs.uri,
+          mimeType: docs.mimeType,
+          text: await docs.readBody()
+        }
+      ]
+    })
+  );
+}
+function buildSolvaPayMcpServer(options) {
+  const {
+    registerPrompts = true,
+    registerDocsResources = true,
+    serverName,
+    serverVersion = "1.0.0",
+    hideToolsByAudience: _hideToolsByAudience,
+    ...descriptorOptions
+  } = options;
+  const descriptors = buildSolvaPayDescriptors(descriptorOptions);
+  const effectiveServerName = serverName ?? descriptorOptions.branding?.brandName ?? "solvapay-mcp-server";
+  const serverIcons = deriveIcons(descriptorOptions.branding);
+  const server = new McpServer({
+    name: effectiveServerName,
+    version: serverVersion,
+    ...serverIcons ? { icons: serverIcons } : {}
+  });
+  for (const tool of descriptors.tools) {
+    registerDescriptor(server, tool);
+  }
+  if (registerPrompts) {
+    for (const prompt of descriptors.prompts) {
+      registerPromptDescriptor(server, prompt);
+    }
+  }
+  if (registerDocsResources) {
+    for (const docs of descriptors.docsResources) {
+      registerDocsResource(server, docs);
+    }
+  }
+  const resource = descriptors.resource;
+  registerAppResource(
+    server,
+    resource.uri,
+    resource.uri,
+    {
+      mimeType: RESOURCE_MIME_TYPE,
+      _meta: {
+        ui: {
+          csp: resource.csp,
+          // `false` asks the host to skip painting its own outer card /
+          // border around the iframe. The widget paints its own frame
+          // via `.solvapay-mcp-card`, and `<AppHeader>` renders the
+          // merchant mark at the top; a host-painted card on top of
+          // that produced a nested-container look (visible on MCP Jam
+          // with the earlier `true` default). Hosts that honour the
+          // preference (per the MCP Apps spec) now render us flush
+          // inside their conversation surface.
+          prefersBorder: false
+        }
+      }
+    },
+    async () => ({
+      contents: [
+        {
+          uri: resource.uri,
+          mimeType: RESOURCE_MIME_TYPE,
+          text: await resource.readHtml(),
+          _meta: {
+            ui: {
+              csp: resource.csp,
+              prefersBorder: false
+            }
+          }
+        }
+      ]
+    })
+  );
+  return { server, descriptors };
+}
+
+export {
+  applyHideToolsByAudience,
+  buildSolvaPayMcpServer,
+  registerPayableTool
+};