@solvapay/mcp 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SolvaPay Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @solvapay/mcp
+
+Official `@modelcontextprotocol/sdk` + `@modelcontextprotocol/ext-apps`
+adapter for the SolvaPay MCP toolbox.
+
+This is the only SolvaPay package that imports `@modelcontextprotocol/*`.
+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:
+
+- [`@solvapay/mcp-express`](../mcp-express) — Node `(req, res, next)`.
+- [`@solvapay/mcp-fetch`](../mcp-fetch) — Web standards `(req: Request) => Promise<Response>`.
+
+## Install
+
+```bash
+pnpm add @solvapay/mcp @solvapay/server \
+  @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod
+```
+
+## Importing
+
+Everything you need for a paywalled tool lives in this package:
+
+```ts
+import {
+  createSolvaPayMcpServer,
+  registerPayableTool,
+  type ResponseContext,
+  type NudgeSpec,
+} from '@solvapay/mcp'
+```
+
+Reach into `@solvapay/mcp-core` directly only if you're writing a
+framework adapter (`fastmcp`, raw JSON-RPC).
+
+## Quick start
+
+```ts
+import { createSolvaPayMcpServer } from '@solvapay/mcp'
+import { createSolvaPay } from '@solvapay/server'
+import { z } from 'zod'
+
+const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY! })
+
+const server = createSolvaPayMcpServer({
+  solvaPay,
+  productRef: 'prd_video',
+  resourceUri: 'ui://my-app/mcp-app.html',
+  htmlPath: './dist/mcp-app.html',
+  publicBaseUrl: 'https://my-app.example.com',
+  additionalTools: ({ registerPayable }) => {
+    registerPayable('create_video', {
+      schema: { prompt: z.string() },
+      description: 'Generate a short video from a text prompt.',
+      handler: async ({ prompt }, ctx) => {
+        const videoUrl = await generateVideo(prompt)
+        return ctx.respond({ videoUrl })
+      },
+    })
+  },
+})
+```
+
+One call wires the full SolvaPay transport surface (`check_purchase`,
+`create_payment_intent`, `process_payment`, `open_checkout`, etc.), the
+UI resource with the Stripe CSP baseline, and any integrator-defined
+tools via `additionalTools`.
+
+## Handler contract
+
+`registerPayable` handlers receive parsed `args` (inferred from
+`schema` when provided) and a `ResponseContext`. They must return the
+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.
+  if (ctx.customer.balance < 500) {
+    return ctx.respond({ videoUrl: video.url }, {
+      nudge: { kind: 'low-balance', message: 'Running low on credits' },
+    })
+  }
+  return ctx.respond({ videoUrl: video.url })
+}
+```
+
+The [`ctx.respond()` V1 spec](../../docs/spec/ctx-respond-v1.md) has the
+full surface. The TL;DR:
+
+- `ctx.customer` — cached customer snapshot (≤10s stale). Read
+  `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).
+- `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()`
+  pre-check.
+- `ctx.emit(block)` / `ctx.progress(...)` / `ctx.signal` — reserved
+  surface. V1 queues (emit) or no-ops (progress / signal); V1.1 wires
+  them to SSE and transport cancellation without code changes.
+
+## 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. |
+
+## Peer dependencies
+
+| Peer | Why |
+|---|---|
+| `@modelcontextprotocol/sdk` | The `McpServer` this package builds and returns |
+| `@modelcontextprotocol/ext-apps` | `registerAppTool`, `registerAppResource`, the `RESOURCE_MIME_TYPE` constant |
+| `@solvapay/mcp-core` | Neutral contracts and descriptor builder |
+| `@solvapay/server` | `SolvaPay` factory + `PaywallError` runtime |
+| `zod` | Tool `inputSchema` shape (required by the ext-apps helpers) |
+
+## Want to adapt another framework?
+
+Use [`@solvapay/mcp-core`](../mcp-core) directly. `buildSolvaPayDescriptors`
+returns a framework-neutral bundle; map it onto your framework's
+`registerTool` / `registerResource` API in ~60 lines. This package is
+itself that mapper for the official SDK.

package/dist/index.cjs

@@ -0,0 +1,221 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSolvaPayMcpServer: () => createSolvaPayMcpServer,
+  registerPayableTool: () => registerPayableTool
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/server.ts
+var import_server2 = require("@modelcontextprotocol/ext-apps/server");
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_mcp_core2 = require("@solvapay/mcp-core");
+
+// src/registerPayableTool.ts
+var import_server = require("@modelcontextprotocol/ext-apps/server");
+var import_mcp_core = require("@solvapay/mcp-core");
+function registerPayableTool(server, name, options) {
+  const {
+    solvaPay,
+    resourceUri,
+    schema,
+    product,
+    title,
+    description,
+    handler,
+    buildBootstrap,
+    getCustomerRef,
+    meta,
+    annotations,
+    icons
+  } = options;
+  const protectedHandler = (0, import_mcp_core.buildPayableHandler)(
+    solvaPay,
+    { product, resourceUri, buildBootstrap, getCustomerRef },
+    handler
+  );
+  const baseMeta = meta ?? {};
+  const baseUi = baseMeta.ui ?? {};
+  const hasIcons = icons !== void 0 && icons.length > 0;
+  const mergedUi = {
+    resourceUri,
+    ...baseUi,
+    ...hasIcons ? { icons } : {}
+  };
+  const toolMeta = { ...baseMeta, ui: mergedUi };
+  const effectiveAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    ...annotations
+  };
+  return (0, import_server.registerAppTool)(
+    server,
+    name,
+    // Note: `registerAppTool`'s config type is stricter than ours —
+    // casting so `title` / `description` stay optional and the input
+    // schema flows through correctly at the registration layer.
+    {
+      ...title !== void 0 ? { title } : {},
+      ...description !== void 0 ? { description } : {},
+      ...schema !== void 0 ? { inputSchema: schema } : {},
+      _meta: toolMeta,
+      annotations: effectiveAnnotations,
+      ...icons !== void 0 && icons.length > 0 ? { icons } : {}
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    },
+    async (args, extra) => await protectedHandler(args, extra)
+  );
+}
+
+// src/server.ts
+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;
+  (0, import_server2.registerAppTool)(
+    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 createSolvaPayMcpServer(options) {
+  const {
+    additionalTools,
+    registerPrompts = true,
+    registerDocsResources = true,
+    serverName,
+    serverVersion = "1.0.0",
+    ...descriptorOptions
+  } = options;
+  const { tools, resource, prompts, docsResources, buildBootstrapPayload } = (0, import_mcp_core2.buildSolvaPayDescriptors)(descriptorOptions);
+  const effectiveServerName = serverName ?? descriptorOptions.branding?.brandName ?? "solvapay-mcp-server";
+  const server = new import_mcp.McpServer({ name: effectiveServerName, version: serverVersion });
+  for (const tool of tools) {
+    registerDescriptor(server, tool);
+  }
+  if (registerPrompts) {
+    for (const prompt of prompts) {
+      registerPromptDescriptor(server, prompt);
+    }
+  }
+  if (registerDocsResources) {
+    for (const docs of docsResources) {
+      registerDocsResource(server, docs);
+    }
+  }
+  (0, import_server2.registerAppResource)(
+    server,
+    resource.uri,
+    resource.uri,
+    {
+      mimeType: import_server2.RESOURCE_MIME_TYPE,
+      _meta: {
+        ui: {
+          csp: resource.csp,
+          prefersBorder: true
+        }
+      }
+    },
+    async () => ({
+      contents: [
+        {
+          uri: resource.uri,
+          mimeType: import_server2.RESOURCE_MIME_TYPE,
+          text: await resource.readHtml(),
+          _meta: {
+            ui: {
+              csp: resource.csp,
+              prefersBorder: true
+            }
+          }
+        }
+      ]
+    })
+  );
+  if (additionalTools) {
+    const { solvaPay, productRef, resourceUri } = descriptorOptions;
+    const registerPayable = (name, opts) => {
+      registerPayableTool(server, name, {
+        solvaPay,
+        resourceUri,
+        ...opts,
+        product: opts.product ?? productRef,
+        buildBootstrap: opts.buildBootstrap ?? buildBootstrapPayload
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      });
+    };
+    additionalTools({ server, solvaPay, resourceUri, productRef, registerPayable });
+  }
+  return server;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSolvaPayMcpServer,
+  registerPayableTool
+});

package/dist/index.d.cts

@@ -0,0 +1,180 @@
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodRawShapeCompat, AnySchema, ShapeOutput, SchemaOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { PayableHandler, BuildBootstrapPayloadFn, McpToolExtra, SolvaPayToolAnnotations, SolvaPayToolIcon, BuildSolvaPayDescriptorsOptions } from '@solvapay/mcp-core';
+export { ContentBlock, CustomerSnapshot, NudgeSpec, PayableHandler, ResponseContext, ResponseOptions, ResponseResult } from '@solvapay/mcp-core';
+import { SolvaPay } from '@solvapay/server';
+
+/**
+ * `registerPayableTool(server, name, options)` — one-liner for registering
+ * a paywall-protected MCP tool on the official `@modelcontextprotocol/sdk`
+ * `McpServer`.
+ *
+ * Always advertises `_meta.ui.resourceUri` at the descriptor level so
+ * descriptor-reading hosts (MCPJam's `ResultsPanel`, MCP App inspector)
+ * learn the widget exists and open the MCP App iframe when a paywall or
+ * nudge response lands. `buildPayableHandler` stamps the same metadata
+ * on the result envelope as a secondary signal for hosts that key off
+ * tool-call results (Claude Desktop, mcp-ui, ChatGPT Apps).
+ *
+ * Mirrors the positional-`name` shape of `registerAppTool` to keep the
+ * convention consistent across the ecosystem.
+ */
+
+/**
+ * Projects the tool's `schema` (raw shape or already-constructed
+ * schema) into the `args` type the handler receives. When no schema
+ * is provided, falls back to `Record<string, unknown>` so handlers
+ * can still destructure without losing type-check.
+ */
+type InferHandlerArgs<InputSchema> = [InputSchema] extends [undefined] ? Record<string, unknown> : InputSchema extends ZodRawShapeCompat ? ShapeOutput<InputSchema> : InputSchema extends AnySchema ? SchemaOutput<InputSchema> : Record<string, unknown>;
+interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown> {
+    /** The initialised SolvaPay instance used to build `payable({ product }).mcp(handler)`. */
+    solvaPay: SolvaPay;
+    /**
+     * UI resource URI the MCP host should open to render the paywall view.
+     * Typically `'ui://<app>/<resource>.html'`.
+     */
+    resourceUri: string;
+    /** Zod-compatible input schema (raw shape or discriminated schema). */
+    schema?: InputSchema;
+    /** SolvaPay product ref to protect this tool against. */
+    product: string;
+    /** Optional human-readable tool title for MCP listings. */
+    title?: string;
+    /** Optional tool description surfaced to the model. */
+    description?: string;
+    /**
+     * Business logic that runs once the caller is within limits. Receives
+     * parsed `args` (inferred from `schema` when provided) and a
+     * `ResponseContext`; must return the branded envelope produced by
+     * `ctx.respond(data, options?)`.
+     *
+     * `ctx` surfaces:
+     *  - `ctx.customer` — cached snapshot (`balance`, `remaining`, `plan`,
+     *    `.fresh()` for a round-trip).
+     *  - `ctx.product` — bootstrap product projection.
+     *  - `ctx.respond(data, options?)` — return an envelope. `options`
+     *    carries `text` (override `content[0].text`), `nudge` (inline
+     *    upsell strip), and the reserved `units` (V1.1 variable billing —
+     *    V1 silently ignores).
+     *  - `ctx.gate(reason?)` — stops handler execution and emits a
+     *    paywall response through the adapter's `formatGate` channel.
+     *    Rare — the SDK normally fires the paywall automatically via
+     *    `payable().mcp()` pre-check.
+     *  - `ctx.emit(block)` / `ctx.progress(...)` / `ctx.signal` — reserved
+     *    streaming surface. V1 queues (emit) or no-ops (progress / signal);
+     *    V1.1 wires them to SSE and transport cancellation.
+     *
+     * Throwing anything other than `PaywallError` surfaces as a tool-level
+     * error via `formatError`.
+     */
+    handler: PayableHandler<InferHandlerArgs<InputSchema>, TData>;
+    /**
+     * Builds the full `BootstrapPayload` embedded on paywall results so
+     * the React shell renders the paywall view directly from the gate
+     * response. Wire from
+     * `buildSolvaPayDescriptors(...).buildBootstrapPayload`.
+     */
+    buildBootstrap?: BuildBootstrapPayloadFn;
+    /**
+     * Override customer-ref extraction. Defaults to the MCP adapter's
+     * behavior (reads `extra.authInfo.extra.customer_ref`).
+     */
+    getCustomerRef?: (args: Record<string, unknown>, extra?: McpToolExtra) => string | Promise<string>;
+    /**
+     * Additional `_meta` merged onto the tool **descriptor** (the tool
+     * advertisement returned by `tools/list`).
+     *
+     * `registerPayableTool` always injects `ui.resourceUri` at the
+     * descriptor level so hosts that read widget metadata from
+     * `tools/list` (MCPJam's `ResultsPanel` reads
+     * `toolMeta.ui.resourceUri` from the tool definition) can open the
+     * MCP App iframe when a paywall/nudge response lands. Merchant
+     * `meta.ui.resourceUri` overrides the default if supplied.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Portable MCP tool annotations. Defaults to
+     * `{ readOnlyHint: true, openWorldHint: true }` — sensible for a
+     * paywalled *data* tool that reads from the merchant's backend.
+     * Override for tools that mutate state (e.g. `submit_order`) with
+     * `annotations: { readOnlyHint: false, destructiveHint: true }`.
+     */
+    annotations?: SolvaPayToolAnnotations;
+    /**
+     * Brand icons surfaced on `tools/list`. Hosts that read tool
+     * metadata for the chrome strip (ChatGPT, Claude Desktop) swap the
+     * default placeholder for this asset. Pass a square logomark for
+     * best results. Merchants typically share one `icons[]` across
+     * every tool — consider a single branding source at the server
+     * level.
+     */
+    icons?: SolvaPayToolIcon[];
+}
+/**
+ * Register a paywall-protected tool on an MCP server.
+ */
+declare function registerPayableTool<InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(server: McpServer, name: string, options: RegisterPayableToolOptions<InputSchema, TData>): RegisteredTool;
+
+/**
+ * `createSolvaPayMcpServer` — batteries-included factory that
+ * registers the full SolvaPay transport + bootstrap tool surface on a
+ * fresh `McpServer` from the official `@modelcontextprotocol/sdk`,
+ * plus the UI resource the `open_*` tools reference.
+ *
+ * Internals are a thin mapper over `buildSolvaPayDescriptors` from
+ * `@solvapay/mcp-core` — this package is the only one importing
+ * `@modelcontextprotocol/*`.
+ */
+
+/**
+ * Callback fired from the `additionalTools` hook with helpers bound for
+ * the current server + `solvaPay` instance.
+ */
+interface AdditionalToolsContext {
+    server: McpServer;
+    solvaPay: SolvaPay;
+    resourceUri: string;
+    productRef: string;
+    /**
+     * `registerPayableTool` bound with `solvaPay` + `resourceUri` already
+     * provided, and `product` defaulting to the server's `productRef`.
+     *
+     * Zod `schema` flows through to the handler's `args` parameter so
+     * merchants get inferred arg types without a second declaration.
+     */
+    registerPayable: <InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(name: string, options: Omit<RegisterPayableToolOptions<InputSchema, TData>, 'solvaPay' | 'resourceUri' | 'product'> & {
+        product?: string;
+    }) => void;
+}
+interface CreateSolvaPayMcpServerOptions extends BuildSolvaPayDescriptorsOptions {
+    /**
+     * Integrator hook to register non-SolvaPay tools. The callback receives
+     * the built server plus a `registerPayable` helper bound for this
+     * instance.
+     */
+    additionalTools?: (ctx: AdditionalToolsContext) => void;
+    /**
+     * Register the slash-command prompts (`/upgrade`, `/manage_account`,
+     * `/topup`, `/activate_plan`) built from the descriptor bundle.
+     * Defaults to `true` — the prompts are additive and silently ignored
+     * by hosts without prompt support.
+     */
+    registerPrompts?: boolean;
+    /**
+     * Register the narrated `docs://solvapay/overview.md` resource so
+     * agents can `resources/read` before trying a tool. Defaults to
+     * `true` — pure narration, no side-effects.
+     */
+    registerDocsResources?: boolean;
+    /** Overrides the default `McpServer` name. */
+    serverName?: string;
+    /** Overrides the default `McpServer` version. */
+    serverVersion?: string;
+}
+/**
+ * Build the MCP server and register the full SolvaPay tool surface.
+ */
+declare function createSolvaPayMcpServer(options: CreateSolvaPayMcpServerOptions): McpServer;
+
+export { type AdditionalToolsContext, type CreateSolvaPayMcpServerOptions, type RegisterPayableToolOptions, createSolvaPayMcpServer, registerPayableTool };

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodRawShapeCompat, AnySchema, ShapeOutput, SchemaOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { PayableHandler, BuildBootstrapPayloadFn, McpToolExtra, SolvaPayToolAnnotations, SolvaPayToolIcon, BuildSolvaPayDescriptorsOptions } from '@solvapay/mcp-core';
+export { ContentBlock, CustomerSnapshot, NudgeSpec, PayableHandler, ResponseContext, ResponseOptions, ResponseResult } from '@solvapay/mcp-core';
+import { SolvaPay } from '@solvapay/server';
+
+/**
+ * `registerPayableTool(server, name, options)` — one-liner for registering
+ * a paywall-protected MCP tool on the official `@modelcontextprotocol/sdk`
+ * `McpServer`.
+ *
+ * Always advertises `_meta.ui.resourceUri` at the descriptor level so
+ * descriptor-reading hosts (MCPJam's `ResultsPanel`, MCP App inspector)
+ * learn the widget exists and open the MCP App iframe when a paywall or
+ * nudge response lands. `buildPayableHandler` stamps the same metadata
+ * on the result envelope as a secondary signal for hosts that key off
+ * tool-call results (Claude Desktop, mcp-ui, ChatGPT Apps).
+ *
+ * Mirrors the positional-`name` shape of `registerAppTool` to keep the
+ * convention consistent across the ecosystem.
+ */
+
+/**
+ * Projects the tool's `schema` (raw shape or already-constructed
+ * schema) into the `args` type the handler receives. When no schema
+ * is provided, falls back to `Record<string, unknown>` so handlers
+ * can still destructure without losing type-check.
+ */
+type InferHandlerArgs<InputSchema> = [InputSchema] extends [undefined] ? Record<string, unknown> : InputSchema extends ZodRawShapeCompat ? ShapeOutput<InputSchema> : InputSchema extends AnySchema ? SchemaOutput<InputSchema> : Record<string, unknown>;
+interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown> {
+    /** The initialised SolvaPay instance used to build `payable({ product }).mcp(handler)`. */
+    solvaPay: SolvaPay;
+    /**
+     * UI resource URI the MCP host should open to render the paywall view.
+     * Typically `'ui://<app>/<resource>.html'`.
+     */
+    resourceUri: string;
+    /** Zod-compatible input schema (raw shape or discriminated schema). */
+    schema?: InputSchema;
+    /** SolvaPay product ref to protect this tool against. */
+    product: string;
+    /** Optional human-readable tool title for MCP listings. */
+    title?: string;
+    /** Optional tool description surfaced to the model. */
+    description?: string;
+    /**
+     * Business logic that runs once the caller is within limits. Receives
+     * parsed `args` (inferred from `schema` when provided) and a
+     * `ResponseContext`; must return the branded envelope produced by
+     * `ctx.respond(data, options?)`.
+     *
+     * `ctx` surfaces:
+     *  - `ctx.customer` — cached snapshot (`balance`, `remaining`, `plan`,
+     *    `.fresh()` for a round-trip).
+     *  - `ctx.product` — bootstrap product projection.
+     *  - `ctx.respond(data, options?)` — return an envelope. `options`
+     *    carries `text` (override `content[0].text`), `nudge` (inline
+     *    upsell strip), and the reserved `units` (V1.1 variable billing —
+     *    V1 silently ignores).
+     *  - `ctx.gate(reason?)` — stops handler execution and emits a
+     *    paywall response through the adapter's `formatGate` channel.
+     *    Rare — the SDK normally fires the paywall automatically via
+     *    `payable().mcp()` pre-check.
+     *  - `ctx.emit(block)` / `ctx.progress(...)` / `ctx.signal` — reserved
+     *    streaming surface. V1 queues (emit) or no-ops (progress / signal);
+     *    V1.1 wires them to SSE and transport cancellation.
+     *
+     * Throwing anything other than `PaywallError` surfaces as a tool-level
+     * error via `formatError`.
+     */
+    handler: PayableHandler<InferHandlerArgs<InputSchema>, TData>;
+    /**
+     * Builds the full `BootstrapPayload` embedded on paywall results so
+     * the React shell renders the paywall view directly from the gate
+     * response. Wire from
+     * `buildSolvaPayDescriptors(...).buildBootstrapPayload`.
+     */
+    buildBootstrap?: BuildBootstrapPayloadFn;
+    /**
+     * Override customer-ref extraction. Defaults to the MCP adapter's
+     * behavior (reads `extra.authInfo.extra.customer_ref`).
+     */
+    getCustomerRef?: (args: Record<string, unknown>, extra?: McpToolExtra) => string | Promise<string>;
+    /**
+     * Additional `_meta` merged onto the tool **descriptor** (the tool
+     * advertisement returned by `tools/list`).
+     *
+     * `registerPayableTool` always injects `ui.resourceUri` at the
+     * descriptor level so hosts that read widget metadata from
+     * `tools/list` (MCPJam's `ResultsPanel` reads
+     * `toolMeta.ui.resourceUri` from the tool definition) can open the
+     * MCP App iframe when a paywall/nudge response lands. Merchant
+     * `meta.ui.resourceUri` overrides the default if supplied.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Portable MCP tool annotations. Defaults to
+     * `{ readOnlyHint: true, openWorldHint: true }` — sensible for a
+     * paywalled *data* tool that reads from the merchant's backend.
+     * Override for tools that mutate state (e.g. `submit_order`) with
+     * `annotations: { readOnlyHint: false, destructiveHint: true }`.
+     */
+    annotations?: SolvaPayToolAnnotations;
+    /**
+     * Brand icons surfaced on `tools/list`. Hosts that read tool
+     * metadata for the chrome strip (ChatGPT, Claude Desktop) swap the
+     * default placeholder for this asset. Pass a square logomark for
+     * best results. Merchants typically share one `icons[]` across
+     * every tool — consider a single branding source at the server
+     * level.
+     */
+    icons?: SolvaPayToolIcon[];
+}
+/**
+ * Register a paywall-protected tool on an MCP server.
+ */
+declare function registerPayableTool<InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(server: McpServer, name: string, options: RegisterPayableToolOptions<InputSchema, TData>): RegisteredTool;
+
+/**
+ * `createSolvaPayMcpServer` — batteries-included factory that
+ * registers the full SolvaPay transport + bootstrap tool surface on a
+ * fresh `McpServer` from the official `@modelcontextprotocol/sdk`,
+ * plus the UI resource the `open_*` tools reference.
+ *
+ * Internals are a thin mapper over `buildSolvaPayDescriptors` from
+ * `@solvapay/mcp-core` — this package is the only one importing
+ * `@modelcontextprotocol/*`.
+ */
+
+/**
+ * Callback fired from the `additionalTools` hook with helpers bound for
+ * the current server + `solvaPay` instance.
+ */
+interface AdditionalToolsContext {
+    server: McpServer;
+    solvaPay: SolvaPay;
+    resourceUri: string;
+    productRef: string;
+    /**
+     * `registerPayableTool` bound with `solvaPay` + `resourceUri` already
+     * provided, and `product` defaulting to the server's `productRef`.
+     *
+     * Zod `schema` flows through to the handler's `args` parameter so
+     * merchants get inferred arg types without a second declaration.
+     */
+    registerPayable: <InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(name: string, options: Omit<RegisterPayableToolOptions<InputSchema, TData>, 'solvaPay' | 'resourceUri' | 'product'> & {
+        product?: string;
+    }) => void;
+}
+interface CreateSolvaPayMcpServerOptions extends BuildSolvaPayDescriptorsOptions {
+    /**
+     * Integrator hook to register non-SolvaPay tools. The callback receives
+     * the built server plus a `registerPayable` helper bound for this
+     * instance.
+     */
+    additionalTools?: (ctx: AdditionalToolsContext) => void;
+    /**
+     * Register the slash-command prompts (`/upgrade`, `/manage_account`,
+     * `/topup`, `/activate_plan`) built from the descriptor bundle.
+     * Defaults to `true` — the prompts are additive and silently ignored
+     * by hosts without prompt support.
+     */
+    registerPrompts?: boolean;
+    /**
+     * Register the narrated `docs://solvapay/overview.md` resource so
+     * agents can `resources/read` before trying a tool. Defaults to
+     * `true` — pure narration, no side-effects.
+     */
+    registerDocsResources?: boolean;
+    /** Overrides the default `McpServer` name. */
+    serverName?: string;
+    /** Overrides the default `McpServer` version. */
+    serverVersion?: string;
+}
+/**
+ * Build the MCP server and register the full SolvaPay tool surface.
+ */
+declare function createSolvaPayMcpServer(options: CreateSolvaPayMcpServerOptions): McpServer;
+
+export { type AdditionalToolsContext, type CreateSolvaPayMcpServerOptions, type RegisterPayableToolOptions, createSolvaPayMcpServer, registerPayableTool };

package/dist/index.js

@@ -0,0 +1,201 @@
+// src/server.ts
+import {
+  registerAppResource,
+  registerAppTool as registerAppTool2,
+  RESOURCE_MIME_TYPE
+} from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  buildSolvaPayDescriptors
+} from "@solvapay/mcp-core";
+
+// src/registerPayableTool.ts
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import {
+  buildPayableHandler
+} from "@solvapay/mcp-core";
+function registerPayableTool(server, name, options) {
+  const {
+    solvaPay,
+    resourceUri,
+    schema,
+    product,
+    title,
+    description,
+    handler,
+    buildBootstrap,
+    getCustomerRef,
+    meta,
+    annotations,
+    icons
+  } = options;
+  const protectedHandler = buildPayableHandler(
+    solvaPay,
+    { product, resourceUri, buildBootstrap, getCustomerRef },
+    handler
+  );
+  const baseMeta = meta ?? {};
+  const baseUi = baseMeta.ui ?? {};
+  const hasIcons = icons !== void 0 && icons.length > 0;
+  const mergedUi = {
+    resourceUri,
+    ...baseUi,
+    ...hasIcons ? { icons } : {}
+  };
+  const toolMeta = { ...baseMeta, ui: mergedUi };
+  const effectiveAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    ...annotations
+  };
+  return registerAppTool(
+    server,
+    name,
+    // Note: `registerAppTool`'s config type is stricter than ours —
+    // casting so `title` / `description` stay optional and the input
+    // schema flows through correctly at the registration layer.
+    {
+      ...title !== void 0 ? { title } : {},
+      ...description !== void 0 ? { description } : {},
+      ...schema !== void 0 ? { inputSchema: schema } : {},
+      _meta: toolMeta,
+      annotations: effectiveAnnotations,
+      ...icons !== void 0 && icons.length > 0 ? { icons } : {}
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    },
+    async (args, extra) => await protectedHandler(args, extra)
+  );
+}
+
+// src/server.ts
+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 createSolvaPayMcpServer(options) {
+  const {
+    additionalTools,
+    registerPrompts = true,
+    registerDocsResources = true,
+    serverName,
+    serverVersion = "1.0.0",
+    ...descriptorOptions
+  } = options;
+  const { tools, resource, prompts, docsResources, buildBootstrapPayload } = buildSolvaPayDescriptors(descriptorOptions);
+  const effectiveServerName = serverName ?? descriptorOptions.branding?.brandName ?? "solvapay-mcp-server";
+  const server = new McpServer({ name: effectiveServerName, version: serverVersion });
+  for (const tool of tools) {
+    registerDescriptor(server, tool);
+  }
+  if (registerPrompts) {
+    for (const prompt of prompts) {
+      registerPromptDescriptor(server, prompt);
+    }
+  }
+  if (registerDocsResources) {
+    for (const docs of docsResources) {
+      registerDocsResource(server, docs);
+    }
+  }
+  registerAppResource(
+    server,
+    resource.uri,
+    resource.uri,
+    {
+      mimeType: RESOURCE_MIME_TYPE,
+      _meta: {
+        ui: {
+          csp: resource.csp,
+          prefersBorder: true
+        }
+      }
+    },
+    async () => ({
+      contents: [
+        {
+          uri: resource.uri,
+          mimeType: RESOURCE_MIME_TYPE,
+          text: await resource.readHtml(),
+          _meta: {
+            ui: {
+              csp: resource.csp,
+              prefersBorder: true
+            }
+          }
+        }
+      ]
+    })
+  );
+  if (additionalTools) {
+    const { solvaPay, productRef, resourceUri } = descriptorOptions;
+    const registerPayable = (name, opts) => {
+      registerPayableTool(server, name, {
+        solvaPay,
+        resourceUri,
+        ...opts,
+        product: opts.product ?? productRef,
+        buildBootstrap: opts.buildBootstrap ?? buildBootstrapPayload
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      });
+    };
+    additionalTools({ server, solvaPay, resourceUri, productRef, registerPayable });
+  }
+  return server;
+}
+export {
+  createSolvaPayMcpServer,
+  registerPayableTool
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@solvapay/mcp",
+  "version": "0.1.0",
+  "description": "Official @modelcontextprotocol/sdk + @modelcontextprotocol/ext-apps adapter for the SolvaPay MCP toolbox (createSolvaPayMcpServer, registerPayableTool).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solvapay/solvapay-sdk.git",
+    "directory": "packages/mcp"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@solvapay/mcp-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.5.0",
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^3.25.0 || ^4.0.0",
+    "@solvapay/server": "1.0.8-preview.10"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.5.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "zod": "^4.3.6",
+    "@solvapay/server": "1.0.8-preview.10",
+    "@solvapay/test-utils": "^0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix"
+  }
+}