@solvapay/mcp 0.1.0 → 0.2.0

package/dist/fetch/index.d.cts

@@ -0,0 +1,238 @@
+import { OAuthBridgePaths, BuildAuthInfoFromBearerOptions, BuildSolvaPayDescriptorsOptions } from '@solvapay/mcp-core';
+export { BuildAuthInfoFromBearerOptions, McpBearerAuthError, OAuthAuthorizationServerOptions, OAuthBridgePaths, buildAuthInfoFromBearer, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse } from '@solvapay/mcp-core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { AdditionalToolsContext } from '../index.cjs';
+import '@modelcontextprotocol/sdk/server/zod-compat.js';
+import '@solvapay/server';
+
+/**
+ * Fetch-first OAuth bridge handlers.
+ *
+ * Each handler has the signature `(req: Request) => Promise<Response | null>`:
+ * it returns `Response` when the request matches the route, `null` when the
+ * handler doesn't want to claim the request (so the host can route
+ * elsewhere, e.g. to the MCP transport).
+ *
+ * Pure Web-standards: runs on Deno, Cloudflare Workers, Bun, Next edge,
+ * Supabase Edge, Node via the `undici`/`node:http` Web interop bridge —
+ * wherever `Request`, `Response`, and global `fetch` exist.
+ */
+
+interface FetchOAuthOptions {
+    publicBaseUrl: string;
+    apiBaseUrl: string;
+    productRef: string;
+    protectedResourcePath?: string;
+    authorizationServerPath?: string;
+    oauthPaths?: OAuthBridgePaths;
+}
+type FetchHandler = (req: Request) => Promise<Response | null>;
+declare function createProtectedResourceHandler(options: {
+    publicBaseUrl: string;
+    protectedResourcePath?: string;
+}): FetchHandler;
+declare function createAuthorizationServerHandler(options: {
+    publicBaseUrl: string;
+    authorizationServerPath?: string;
+    paths?: OAuthBridgePaths;
+    productRef: string;
+}): FetchHandler;
+declare function createOpenidNotFoundHandler(): FetchHandler;
+declare function createOAuthRegisterHandler(options: {
+    apiBaseUrl: string;
+    productRef: string;
+    path?: string;
+}): FetchHandler;
+declare function createOAuthAuthorizeHandler(options: {
+    apiBaseUrl: string;
+    path?: string;
+}): FetchHandler;
+declare function createOAuthTokenHandler(options: {
+    apiBaseUrl: string;
+    path?: string;
+}): FetchHandler;
+declare function createOAuthRevokeHandler(options: {
+    apiBaseUrl: string;
+    path?: string;
+}): FetchHandler;
+/**
+ * Compose every OAuth handler into a single `(req) => Response | null`
+ * chain. Returns `null` when no handler matches so the caller can route
+ * to the MCP transport.
+ */
+declare function createOAuthFetchRouter(options: FetchOAuthOptions): FetchHandler;
+
+/**
+ * Native-scheme CORS preflight + 401 `WWW-Authenticate` helpers for MCP
+ * clients on Web-standards runtimes.
+ *
+ * MCP clients like Cursor, VS Code, and Claude Desktop attach native
+ * schemes to their DCR / OAuth flows (`cursor://…`, `vscode://…`,
+ * `vscode-webview://…`, `claude://…`). These origins don't carry
+ * credentials — mirroring them back in `Access-Control-Allow-Origin` is
+ * safer than a bare `*`.
+ */
+/** Returns `true` when `origin` is a native MCP-client scheme we mirror. */
+declare function isNativeClientOrigin(origin: string | null | undefined): boolean;
+/** Adds CORS mirror headers to `headers` when the request origin is a native client scheme. */
+declare function applyNativeCors(reqHeaders: Headers, resHeaders: Headers): void;
+/** 204 preflight response with CORS mirror for native-scheme origins. */
+declare function corsPreflight(req: Request): Response;
+/**
+ * Produce a 401 JSON-RPC response + `WWW-Authenticate: Bearer
+ * resource_metadata="…"` pointing at the protected-resource discovery
+ * endpoint so MCP clients know where to discover the authorization
+ * server.
+ */
+declare function authChallenge(req: Request, options: {
+    publicBaseUrl: string;
+    protectedResourcePath?: string;
+    jsonRpcId?: string | number | null;
+}): Response;
+/** Extract the raw bearer token from an `Authorization: Bearer <token>` header, or `null`. */
+declare function resolveBearer(req: Request): string | null;
+
+/**
+ * Turnkey fetch-first MCP handler: composes OAuth routing +
+ * `WebStandardStreamableHTTPServerTransport` + an `McpServer` into a
+ * single `(req: Request) => Promise<Response>`. Runs on any
+ * Web-standards runtime (Deno, Supabase Edge, Cloudflare Workers, Bun,
+ * Next edge, Vercel Functions, Node via undici/polyfilled Web APIs).
+ */
+
+/**
+ * Transport wiring preset.
+ *
+ * - `'sse-stateful'` — default. SSE streaming + UUID `mcp-session-id`
+ *   on initialize. Matches the original helper behaviour and is what
+ *   Node / Express / Bun deployments expect.
+ * - `'json-stateless'` — `{ sessionIdGenerator: undefined,
+ *   enableJsonResponse: true }`. Required on stateless fetch runtimes
+ *   (Supabase Edge, Cloudflare Workers, Vercel Edge, Deno Deploy) that
+ *   can't keep per-session state across invocations and need a
+ *   single-JSON-response wire shape so the response body is assembled
+ *   before the per-request transport is closed.
+ * - `'sse-stateless'` — SSE streaming without session IDs. Advanced /
+ *   hypothetical; provided for symmetry. Most stateless runtimes want
+ *   `'json-stateless'` instead (a cut SSE stream drops the response
+ *   frame).
+ */
+type McpHandlerMode = 'sse-stateful' | 'json-stateless' | 'sse-stateless';
+interface CreateSolvaPayMcpFetchHandlerOptions {
+    server: McpServer;
+    publicBaseUrl: string;
+    apiBaseUrl: string;
+    productRef: string;
+    mcpPath?: string;
+    requireAuth?: boolean;
+    authInfo?: BuildAuthInfoFromBearerOptions;
+    protectedResourcePath?: string;
+    authorizationServerPath?: string;
+    oauthPaths?: OAuthBridgePaths;
+    /**
+     * Transport wiring preset. Defaults to `'sse-stateful'` to preserve
+     * the Node / Express / Bun behaviour of earlier versions. Stateless
+     * fetch runtimes (Supabase Edge, Cloudflare Workers, Vercel Edge)
+     * should pass `'json-stateless'`.
+     *
+     * Ignored when `buildTransport` is provided.
+     */
+    mode?: McpHandlerMode;
+    /**
+     * Escape hatch: bring your own transport builder. When provided,
+     * `mode` and `sessionIdGenerator` are ignored — the caller owns the
+     * transport's configuration. The handler still manages
+     * `server.connect(transport)` + `transport.close()` per request and
+     * serialises concurrent requests through the shared-server mutex.
+     */
+    buildTransport?: () => WebStandardStreamableHTTPServerTransport;
+    /**
+     * Optional session-id generator for the underlying
+     * `WebStandardStreamableHTTPServerTransport`. Only honoured in the
+     * default `'sse-stateful'` mode; ignored in stateless modes (which
+     * pass `sessionIdGenerator: undefined` to disable session tracking)
+     * and when `buildTransport` is provided.
+     *
+     * Defaults to `crypto.randomUUID`.
+     */
+    sessionIdGenerator?: () => string;
+}
+/**
+ * Build a `(req: Request) => Promise<Response>` that:
+ *
+ * 1. Serves `OPTIONS` preflight for native-scheme origins.
+ * 2. Serves every `.well-known/*` + `/oauth/*` route via
+ *    {@link createOAuthFetchRouter}.
+ * 3. Enforces bearer-token auth on the MCP path (default `/mcp`) and
+ *    returns `401 + WWW-Authenticate: Bearer resource_metadata="…"`
+ *    when auth is missing.
+ * 4. Forwards the request to a fresh
+ *    `WebStandardStreamableHTTPServerTransport` wired to the provided
+ *    `McpServer`. The transport's `close()` runs in a `finally` block
+ *    so the server's `_transport` slot is released for the next
+ *    request; concurrent requests serialise through a shared mutex so
+ *    two overlapping calls never double-connect the same `McpServer`.
+ *
+ * A fresh transport is created per request — that's the recommended
+ * pattern for stateless fetch runtimes (Workers, Deno, Supabase Edge).
+ * For long-lived session reuse, consume the low-level
+ * {@link createOAuthFetchRouter} + instantiate the transport yourself.
+ */
+declare function createSolvaPayMcpFetchHandler(options: CreateSolvaPayMcpFetchHandlerOptions): (req: Request) => Promise<Response>;
+
+/**
+ * `createSolvaPayMcpFetch` — descriptor-accepting unified factory for
+ * Web-standards runtimes. Collapses the two-step dance (build
+ * `McpServer` via `createSolvaPayMcpServer`, wrap in
+ * `createSolvaPayMcpFetchHandler`) into a single call so edge
+ * consumers (Supabase Edge, Cloudflare Workers, Vercel Edge, Deno,
+ * Bun) can import ONLY from `@solvapay/mcp/fetch`.
+ *
+ * The registration loop is shared with the root `.` entry via
+ * `../internal/buildMcpServer`. `AdditionalToolsContext` is
+ * re-exported from the root `@solvapay/mcp` entry so merchants can
+ * move the same `additionalTools` callback between
+ * `createSolvaPayMcpServer` and `createSolvaPayMcpFetch` without
+ * touching the handler's signature — including the bound
+ * `registerPayable` helper.
+ */
+
+interface CreateSolvaPayMcpFetchOptions extends BuildSolvaPayDescriptorsOptions, Omit<CreateSolvaPayMcpFetchHandlerOptions, 'server'> {
+    /**
+     * Register non-SolvaPay tools on the freshly-built server. Receives
+     * `{ server, solvaPay, resourceUri, productRef, registerPayable }`
+     * — same shape as `createSolvaPayMcpServer`'s hook so merchant tool
+     * callbacks are portable between the two factories.
+     */
+    additionalTools?: (ctx: AdditionalToolsContext) => void;
+    /**
+     * Hide tools whose `_meta.audience` matches one of these values from
+     * `tools/list`. See `CreateSolvaPayMcpServerOptions` for the full
+     * rationale.
+     */
+    hideToolsByAudience?: string[];
+    /**
+     * Register the slash-command prompts built from the descriptor
+     * bundle. Defaults to `true`.
+     */
+    registerPrompts?: boolean;
+    /**
+     * Register the narrated `docs://solvapay/overview.md` resource so
+     * agents can `resources/read` before trying a tool. Defaults to `true`.
+     */
+    registerDocsResources?: boolean;
+    /** Overrides the default `McpServer` name. */
+    serverName?: string;
+    /** Overrides the default `McpServer` version. */
+    serverVersion?: string;
+}
+/**
+ * Build a fetch-first MCP handler with the full SolvaPay tool surface
+ * registered in-place. Returns a `(req: Request) => Promise<Response>`
+ * suitable for `Deno.serve`, `addEventListener('fetch', …)`, Cloudflare
+ * Workers' `fetch` export, or any other Web-standards runtime.
+ */
+declare function createSolvaPayMcpFetch(options: CreateSolvaPayMcpFetchOptions): (req: Request) => Promise<Response>;
+
+export { AdditionalToolsContext, type CreateSolvaPayMcpFetchHandlerOptions, type CreateSolvaPayMcpFetchOptions, type FetchOAuthOptions, type McpHandlerMode, applyNativeCors, authChallenge, corsPreflight, createAuthorizationServerHandler, createOAuthAuthorizeHandler, createOAuthFetchRouter, createOAuthRegisterHandler, createOAuthRevokeHandler, createOAuthTokenHandler, createOpenidNotFoundHandler, createProtectedResourceHandler, createSolvaPayMcpFetch, createSolvaPayMcpFetchHandler, isNativeClientOrigin, resolveBearer };

package/dist/fetch/index.d.ts

@@ -0,0 +1,238 @@
+import { OAuthBridgePaths, BuildAuthInfoFromBearerOptions, BuildSolvaPayDescriptorsOptions } from '@solvapay/mcp-core';
+export { BuildAuthInfoFromBearerOptions, McpBearerAuthError, OAuthAuthorizationServerOptions, OAuthBridgePaths, buildAuthInfoFromBearer, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse } from '@solvapay/mcp-core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { AdditionalToolsContext } from '../index.js';
+import '@modelcontextprotocol/sdk/server/zod-compat.js';
+import '@solvapay/server';
+
+/**
+ * Fetch-first OAuth bridge handlers.
+ *
+ * Each handler has the signature `(req: Request) => Promise<Response | null>`:
+ * it returns `Response` when the request matches the route, `null` when the
+ * handler doesn't want to claim the request (so the host can route
+ * elsewhere, e.g. to the MCP transport).
+ *
+ * Pure Web-standards: runs on Deno, Cloudflare Workers, Bun, Next edge,
+ * Supabase Edge, Node via the `undici`/`node:http` Web interop bridge —
+ * wherever `Request`, `Response`, and global `fetch` exist.
+ */
+
+interface FetchOAuthOptions {
+    publicBaseUrl: string;
+    apiBaseUrl: string;
+    productRef: string;
+    protectedResourcePath?: string;
+    authorizationServerPath?: string;
+    oauthPaths?: OAuthBridgePaths;
+}
+type FetchHandler = (req: Request) => Promise<Response | null>;
+declare function createProtectedResourceHandler(options: {
+    publicBaseUrl: string;
+    protectedResourcePath?: string;
+}): FetchHandler;
+declare function createAuthorizationServerHandler(options: {
+    publicBaseUrl: string;
+    authorizationServerPath?: string;
+    paths?: OAuthBridgePaths;
+    productRef: string;
+}): FetchHandler;
+declare function createOpenidNotFoundHandler(): FetchHandler;
+declare function createOAuthRegisterHandler(options: {
+    apiBaseUrl: string;
+    productRef: string;
+    path?: string;
+}): FetchHandler;
+declare function createOAuthAuthorizeHandler(options: {
+    apiBaseUrl: string;
+    path?: string;
+}): FetchHandler;
+declare function createOAuthTokenHandler(options: {
+    apiBaseUrl: string;
+    path?: string;
+}): FetchHandler;
+declare function createOAuthRevokeHandler(options: {
+    apiBaseUrl: string;
+    path?: string;
+}): FetchHandler;
+/**
+ * Compose every OAuth handler into a single `(req) => Response | null`
+ * chain. Returns `null` when no handler matches so the caller can route
+ * to the MCP transport.
+ */
+declare function createOAuthFetchRouter(options: FetchOAuthOptions): FetchHandler;
+
+/**
+ * Native-scheme CORS preflight + 401 `WWW-Authenticate` helpers for MCP
+ * clients on Web-standards runtimes.
+ *
+ * MCP clients like Cursor, VS Code, and Claude Desktop attach native
+ * schemes to their DCR / OAuth flows (`cursor://…`, `vscode://…`,
+ * `vscode-webview://…`, `claude://…`). These origins don't carry
+ * credentials — mirroring them back in `Access-Control-Allow-Origin` is
+ * safer than a bare `*`.
+ */
+/** Returns `true` when `origin` is a native MCP-client scheme we mirror. */
+declare function isNativeClientOrigin(origin: string | null | undefined): boolean;
+/** Adds CORS mirror headers to `headers` when the request origin is a native client scheme. */
+declare function applyNativeCors(reqHeaders: Headers, resHeaders: Headers): void;
+/** 204 preflight response with CORS mirror for native-scheme origins. */
+declare function corsPreflight(req: Request): Response;
+/**
+ * Produce a 401 JSON-RPC response + `WWW-Authenticate: Bearer
+ * resource_metadata="…"` pointing at the protected-resource discovery
+ * endpoint so MCP clients know where to discover the authorization
+ * server.
+ */
+declare function authChallenge(req: Request, options: {
+    publicBaseUrl: string;
+    protectedResourcePath?: string;
+    jsonRpcId?: string | number | null;
+}): Response;
+/** Extract the raw bearer token from an `Authorization: Bearer <token>` header, or `null`. */
+declare function resolveBearer(req: Request): string | null;
+
+/**
+ * Turnkey fetch-first MCP handler: composes OAuth routing +
+ * `WebStandardStreamableHTTPServerTransport` + an `McpServer` into a
+ * single `(req: Request) => Promise<Response>`. Runs on any
+ * Web-standards runtime (Deno, Supabase Edge, Cloudflare Workers, Bun,
+ * Next edge, Vercel Functions, Node via undici/polyfilled Web APIs).
+ */
+
+/**
+ * Transport wiring preset.
+ *
+ * - `'sse-stateful'` — default. SSE streaming + UUID `mcp-session-id`
+ *   on initialize. Matches the original helper behaviour and is what
+ *   Node / Express / Bun deployments expect.
+ * - `'json-stateless'` — `{ sessionIdGenerator: undefined,
+ *   enableJsonResponse: true }`. Required on stateless fetch runtimes
+ *   (Supabase Edge, Cloudflare Workers, Vercel Edge, Deno Deploy) that
+ *   can't keep per-session state across invocations and need a
+ *   single-JSON-response wire shape so the response body is assembled
+ *   before the per-request transport is closed.
+ * - `'sse-stateless'` — SSE streaming without session IDs. Advanced /
+ *   hypothetical; provided for symmetry. Most stateless runtimes want
+ *   `'json-stateless'` instead (a cut SSE stream drops the response
+ *   frame).
+ */
+type McpHandlerMode = 'sse-stateful' | 'json-stateless' | 'sse-stateless';
+interface CreateSolvaPayMcpFetchHandlerOptions {
+    server: McpServer;
+    publicBaseUrl: string;
+    apiBaseUrl: string;
+    productRef: string;
+    mcpPath?: string;
+    requireAuth?: boolean;
+    authInfo?: BuildAuthInfoFromBearerOptions;
+    protectedResourcePath?: string;
+    authorizationServerPath?: string;
+    oauthPaths?: OAuthBridgePaths;
+    /**
+     * Transport wiring preset. Defaults to `'sse-stateful'` to preserve
+     * the Node / Express / Bun behaviour of earlier versions. Stateless
+     * fetch runtimes (Supabase Edge, Cloudflare Workers, Vercel Edge)
+     * should pass `'json-stateless'`.
+     *
+     * Ignored when `buildTransport` is provided.
+     */
+    mode?: McpHandlerMode;
+    /**
+     * Escape hatch: bring your own transport builder. When provided,
+     * `mode` and `sessionIdGenerator` are ignored — the caller owns the
+     * transport's configuration. The handler still manages
+     * `server.connect(transport)` + `transport.close()` per request and
+     * serialises concurrent requests through the shared-server mutex.
+     */
+    buildTransport?: () => WebStandardStreamableHTTPServerTransport;
+    /**
+     * Optional session-id generator for the underlying
+     * `WebStandardStreamableHTTPServerTransport`. Only honoured in the
+     * default `'sse-stateful'` mode; ignored in stateless modes (which
+     * pass `sessionIdGenerator: undefined` to disable session tracking)
+     * and when `buildTransport` is provided.
+     *
+     * Defaults to `crypto.randomUUID`.
+     */
+    sessionIdGenerator?: () => string;
+}
+/**
+ * Build a `(req: Request) => Promise<Response>` that:
+ *
+ * 1. Serves `OPTIONS` preflight for native-scheme origins.
+ * 2. Serves every `.well-known/*` + `/oauth/*` route via
+ *    {@link createOAuthFetchRouter}.
+ * 3. Enforces bearer-token auth on the MCP path (default `/mcp`) and
+ *    returns `401 + WWW-Authenticate: Bearer resource_metadata="…"`
+ *    when auth is missing.
+ * 4. Forwards the request to a fresh
+ *    `WebStandardStreamableHTTPServerTransport` wired to the provided
+ *    `McpServer`. The transport's `close()` runs in a `finally` block
+ *    so the server's `_transport` slot is released for the next
+ *    request; concurrent requests serialise through a shared mutex so
+ *    two overlapping calls never double-connect the same `McpServer`.
+ *
+ * A fresh transport is created per request — that's the recommended
+ * pattern for stateless fetch runtimes (Workers, Deno, Supabase Edge).
+ * For long-lived session reuse, consume the low-level
+ * {@link createOAuthFetchRouter} + instantiate the transport yourself.
+ */
+declare function createSolvaPayMcpFetchHandler(options: CreateSolvaPayMcpFetchHandlerOptions): (req: Request) => Promise<Response>;
+
+/**
+ * `createSolvaPayMcpFetch` — descriptor-accepting unified factory for
+ * Web-standards runtimes. Collapses the two-step dance (build
+ * `McpServer` via `createSolvaPayMcpServer`, wrap in
+ * `createSolvaPayMcpFetchHandler`) into a single call so edge
+ * consumers (Supabase Edge, Cloudflare Workers, Vercel Edge, Deno,
+ * Bun) can import ONLY from `@solvapay/mcp/fetch`.
+ *
+ * The registration loop is shared with the root `.` entry via
+ * `../internal/buildMcpServer`. `AdditionalToolsContext` is
+ * re-exported from the root `@solvapay/mcp` entry so merchants can
+ * move the same `additionalTools` callback between
+ * `createSolvaPayMcpServer` and `createSolvaPayMcpFetch` without
+ * touching the handler's signature — including the bound
+ * `registerPayable` helper.
+ */
+
+interface CreateSolvaPayMcpFetchOptions extends BuildSolvaPayDescriptorsOptions, Omit<CreateSolvaPayMcpFetchHandlerOptions, 'server'> {
+    /**
+     * Register non-SolvaPay tools on the freshly-built server. Receives
+     * `{ server, solvaPay, resourceUri, productRef, registerPayable }`
+     * — same shape as `createSolvaPayMcpServer`'s hook so merchant tool
+     * callbacks are portable between the two factories.
+     */
+    additionalTools?: (ctx: AdditionalToolsContext) => void;
+    /**
+     * Hide tools whose `_meta.audience` matches one of these values from
+     * `tools/list`. See `CreateSolvaPayMcpServerOptions` for the full
+     * rationale.
+     */
+    hideToolsByAudience?: string[];
+    /**
+     * Register the slash-command prompts built from the descriptor
+     * bundle. Defaults to `true`.
+     */
+    registerPrompts?: boolean;
+    /**
+     * Register the narrated `docs://solvapay/overview.md` resource so
+     * agents can `resources/read` before trying a tool. Defaults to `true`.
+     */
+    registerDocsResources?: boolean;
+    /** Overrides the default `McpServer` name. */
+    serverName?: string;
+    /** Overrides the default `McpServer` version. */
+    serverVersion?: string;
+}
+/**
+ * Build a fetch-first MCP handler with the full SolvaPay tool surface
+ * registered in-place. Returns a `(req: Request) => Promise<Response>`
+ * suitable for `Deno.serve`, `addEventListener('fetch', …)`, Cloudflare
+ * Workers' `fetch` export, or any other Web-standards runtime.
+ */
+declare function createSolvaPayMcpFetch(options: CreateSolvaPayMcpFetchOptions): (req: Request) => Promise<Response>;
+
+export { AdditionalToolsContext, type CreateSolvaPayMcpFetchHandlerOptions, type CreateSolvaPayMcpFetchOptions, type FetchOAuthOptions, type McpHandlerMode, applyNativeCors, authChallenge, corsPreflight, createAuthorizationServerHandler, createOAuthAuthorizeHandler, createOAuthFetchRouter, createOAuthRegisterHandler, createOAuthRevokeHandler, createOAuthTokenHandler, createOpenidNotFoundHandler, createProtectedResourceHandler, createSolvaPayMcpFetch, createSolvaPayMcpFetchHandler, isNativeClientOrigin, resolveBearer };