@oobe-protocol-labs/sap-mcp-server 0.2.1 → 0.7.0

package/dist/remote/server.js

@@ -4,22 +4,34 @@
  * @description Streamable HTTP entrypoint for remote SAP MCP deployments.
  */
 import { randomUUID } from 'crypto';
-import { readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import * as http from 'http';
-import { dirname, join } from 'path';
+import { dirname, join, posix } from 'path';
 import { fileURLToPath } from 'url';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { loadConfig } from '../config/env.js';
+import { getDataDir, loadConfig } from '../config/env.js';
 import { MCP_SERVER_VERSION } from '../core/constants.js';
 import { logger, initLogger } from '../core/logger.js';
 import { createSapMcpServer } from '../server/create-server.js';
 import { AuthManager } from './auth/index.js';
-import { McpMonetizationGate } from '../payments/index.js';
+import { McpMonetizationGate, resolvePaymentNetwork } from '../payments/index.js';
+import { generatePayShProviderYaml } from '../payments/pay-sh-spec.js';
 import { RemoteRateLimiter, buildRemoteRateLimitConfigFromEnv } from './rate-limiter.js';
 const PUBLIC_SERVER_TITLE = 'SAP MCP Server | OOBE Protocol';
 const PUBLIC_SERVER_DESCRIPTION = 'Hosted Solana-native MCP gateway for Synapse Agent Protocol tools, x402/pay.sh monetization, SNS identity, and agent operations.';
 const LOGO_ASSET_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'assets', 'explorer_logo.png');
+const DOCS_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'docs');
+const USER_DOCS_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'USER_DOCS');
+const PAYMENT_STATS_CACHE_MS = 15_000;
+const RELEASE_DOWNLOAD_BASE_URL = `https://github.com/OOBE-PROTOCOL/sap-mcp/releases/download/${MCP_SERVER_VERSION}`;
+const WIZARD_NPM_COMMAND = 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard';
+const X402_PAID_CALL_NPX_COMMAND = 'npx --yes --package @oobe-protocol-labs/sap-mcp-server sap-mcp-x402-paid-call --tool sap_list_all_agents --arguments \'{"limit":5}\' --max-usd 0.02 --confirm';
+const X402_PAID_CALL_ADDON_PATH = '~/.config/mcp-sap/addons/x402-paid-call';
+const SOLANA_DEVNET_CAIP2 = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
+const USDC_MAINNET_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const USDC_DEVNET_MINT = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
 let logoAssetCache;
+let paymentStatsCache;
 /**
  * @name parseApiKeys
  * @description Parses comma-separated `apiKey=userId` entries from environment configuration.
@@ -51,8 +63,13 @@ export function defaultRemoteConfig(appConfig) {
         port,
         host,
         corsOrigins: appConfig.httpCorsOrigins,
-        stateless: parseRemoteBoolean(process.env.SAP_MCP_HTTP_STATELESS, appConfig.mode === 'hosted-api'),
+        stateless: parseRemoteBoolean(process.env.SAP_MCP_HTTP_STATELESS, false),
         rateLimit: buildRemoteRateLimitConfigFromEnv(appConfig.rateLimitPerMinute),
+        paymentDiscovery: buildPublicPaymentDiscovery(appConfig),
+        paymentPriceRange: {
+            minUsd: appConfig.monetization.prices.minUsd,
+            maxUsd: appConfig.monetization.prices.maxUsd,
+        },
     };
     if (authType === 'none') {
         return {
@@ -84,6 +101,56 @@ export function defaultRemoteConfig(appConfig) {
         },
     };
 }
+/**
+ * @name buildPublicPaymentDiscovery
+ * @description Builds public x402 seller/facilitator coordinates without exposing facilitator URL or auth tokens.
+ */
+function buildPublicPaymentDiscovery(appConfig) {
+    if (!appConfig.monetization.enabled || !appConfig.monetization.payTo) {
+        return undefined;
+    }
+    const network = resolvePaymentNetwork(appConfig);
+    const facilitatorPublicKey = (process.env.SAP_MCP_X402_FACILITATOR_PUBLIC_KEY
+        ?? process.env.SAP_MCP_X402_FACILITATOR_FEE_PAYER
+        ?? '').trim();
+    return {
+        provider: appConfig.monetization.provider,
+        network,
+        asset: resolvePublicPaymentAsset(network),
+        assetSymbol: 'USDC',
+        payTo: appConfig.monetization.payTo,
+        seller: {
+            name: 'OOBE Protocol',
+            payTo: appConfig.monetization.payTo,
+        },
+        ...(facilitatorPublicKey
+            ? {
+                facilitator: {
+                    role: 'x402-svm-fee-payer',
+                    publicKey: facilitatorPublicKey,
+                },
+            }
+            : {}),
+        headers: {
+            paymentRequired: 'PAYMENT-REQUIRED',
+            paymentSignature: 'PAYMENT-SIGNATURE',
+            paymentResponse: 'PAYMENT-RESPONSE',
+        },
+    };
+}
+/**
+ * @name resolvePublicPaymentAsset
+ * @description Resolves the public USDC mint advertised in x402 discovery metadata.
+ */
+function resolvePublicPaymentAsset(network) {
+    if (network === SOLANA_DEVNET_CAIP2) {
+        return USDC_DEVNET_MINT;
+    }
+    return USDC_MAINNET_MINT;
+}
+function formatOpenApiUsd(value) {
+    return value.toFixed(6).replace(/0+$/, '').replace(/\.$/, '');
+}
 function parseRemoteBoolean(raw, fallback) {
     if (raw === undefined) {
         return fallback;
@@ -94,38 +161,208 @@ function parseRemoteBoolean(raw, fallback) {
  * @name writeJson
  * @description Writes a JSON response with optional additional headers.
  */
-function writeJson(res, status, body, headers = {}) {
+function writeJson(res, status, body, headers = {}, omitBody = false) {
+    const serialized = JSON.stringify(body);
     res.writeHead(status, {
         'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(serialized),
+        ...headers,
+    });
+    res.end(omitBody ? undefined : serialized);
+}
+/**
+ * @name writeText
+ * @description Writes a cacheable text response with an explicit content type.
+ */
+function writeText(res, status, body, contentType, headers = {}, omitBody = false) {
+    res.writeHead(status, {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=300',
+        'Content-Length': Buffer.byteLength(body),
+        'X-Content-Type-Options': 'nosniff',
         ...headers,
     });
-    res.end(JSON.stringify(body));
+    res.end(omitBody ? undefined : body);
+}
+/**
+ * @name writeMcpJsonRpcError
+ * @description Writes an MCP-compatible JSON-RPC error response with HTTP status semantics.
+ */
+function writeMcpJsonRpcError(res, status, code, id, message, data) {
+    writeJson(res, status, {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code,
+            message,
+            ...(data === undefined ? {} : { data }),
+        },
+    });
+}
+/**
+ * @name readSingleHeader
+ * @description Reads one normalized HTTP header value without accepting ambiguous arrays.
+ */
+function readSingleHeader(value) {
+    if (Array.isArray(value)) {
+        return value[0]?.trim() || undefined;
+    }
+    return value?.trim() || undefined;
+}
+/**
+ * @name extractJsonRpcId
+ * @description Extracts a JSON-RPC id for error correlation.
+ */
+function extractJsonRpcId(body) {
+    if (Array.isArray(body) && body.length > 0) {
+        return extractJsonRpcId(body[0]);
+    }
+    if (!body || typeof body !== 'object') {
+        return null;
+    }
+    const record = body;
+    return typeof record.id === 'string' || typeof record.id === 'number' ? record.id : null;
+}
+/**
+ * @name isInitializeJsonRpcRequest
+ * @description Detects MCP initialize requests that are allowed to create a new stateful session.
+ */
+function isInitializeJsonRpcRequest(body) {
+    if (Array.isArray(body)) {
+        return body.some(isInitializeJsonRpcRequest);
+    }
+    if (!body || typeof body !== 'object') {
+        return false;
+    }
+    return body.method === 'initialize';
 }
 /**
  * @name writeHtml
  * @description Writes a cacheable HTML response for public endpoint previews and social sharing.
  */
-function writeHtml(res, status, html) {
+function writeHtml(res, status, html, omitBody = false) {
     res.writeHead(status, {
         'Content-Type': 'text/html; charset=utf-8',
         'Cache-Control': 'public, max-age=300',
+        'Content-Length': Buffer.byteLength(html),
+        'X-Content-Type-Options': 'nosniff',
+    });
+    res.end(omitBody ? undefined : html);
+}
+/**
+ * @name isPublicReadMethod
+ * @description Returns true for cacheable public metadata reads, including crawler-friendly HEAD checks.
+ */
+function isPublicReadMethod(method) {
+    return method === 'GET' || method === 'HEAD';
+}
+/**
+ * @name isHeadMethod
+ * @description Returns true when the request must emit headers without a response body.
+ */
+function isHeadMethod(method) {
+    return method === 'HEAD';
+}
+/**
+ * @name writeMarkdownAsset
+ * @description Writes a resolved public markdown documentation asset.
+ */
+function writeMarkdownAsset(res, asset) {
+    res.writeHead(200, {
+        'Content-Type': asset.contentType,
+        'Cache-Control': 'public, max-age=120',
+        'Content-Length': asset.contentLength,
         'X-Content-Type-Options': 'nosniff',
     });
-    res.end(html);
+    res.end(asset.body);
+}
+/**
+ * @name resolvePublicDocsMarkdown
+ * @description Resolves safe hosted documentation markdown requests under /docs and /docs/user.
+ */
+export function resolvePublicDocsMarkdown(method, pathname) {
+    if (method !== 'GET' && method !== 'HEAD') {
+        return undefined;
+    }
+    if (!pathname.startsWith('/docs/') || !pathname.endsWith('.md')) {
+        return undefined;
+    }
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(pathname.slice('/docs/'.length));
+    }
+    catch {
+        return undefined;
+    }
+    const normalizedPath = posix.normalize(decodedPath.replace(/\\/g, '/')).replace(/^[/\\]+/, '');
+    if (isUnsafeDocsPath(normalizedPath)) {
+        return undefined;
+    }
+    const root = normalizedPath.startsWith('user/')
+        ? USER_DOCS_ROOT_PATH
+        : DOCS_ROOT_PATH;
+    const relativePath = normalizedPath.startsWith('user/')
+        ? normalizedPath.slice('user/'.length)
+        : normalizedPath;
+    if (isUnsafeDocsPath(relativePath)) {
+        return undefined;
+    }
+    const absolutePath = join(root, relativePath);
+    if (!existsSync(absolutePath)) {
+        return undefined;
+    }
+    const markdown = readFileSync(absolutePath, 'utf-8');
+    return {
+        contentType: 'text/markdown; charset=utf-8',
+        contentLength: Buffer.byteLength(markdown),
+        body: method === 'HEAD' ? undefined : markdown,
+    };
+}
+function isUnsafeDocsPath(pathname) {
+    return pathname === ''
+        || pathname.includes('\0')
+        || pathname === '..'
+        || pathname.startsWith('../')
+        || pathname.includes('/../');
 }
 /**
- * @name writePngAsset
- * @description Writes the bundled SAP logo as a public icon/social image asset.
+ * @name resolvePublicLogoAsset
+ * @description Resolves public icon/social image routes, including HEAD-safe favicon responses for crawlers.
  */
-function writePngAsset(res) {
+export function resolvePublicLogoAsset(method, pathname) {
+    if (method !== 'GET' && method !== 'HEAD') {
+        return undefined;
+    }
     const image = readLogoAsset();
+    const body = method === 'HEAD' ? undefined : image;
+    if (['/favicon.png', '/apple-touch-icon.png', '/og.png'].includes(pathname)) {
+        return {
+            contentType: 'image/png',
+            contentLength: image.byteLength,
+            body,
+        };
+    }
+    if (pathname === '/favicon.ico') {
+        return {
+            contentType: 'image/x-icon',
+            contentLength: image.byteLength,
+            body,
+        };
+    }
+    return undefined;
+}
+/**
+ * @name writeLogoAsset
+ * @description Writes a resolved public logo asset response.
+ */
+function writeLogoAsset(res, asset) {
     res.writeHead(200, {
-        'Content-Type': 'image/png',
+        'Content-Type': asset.contentType,
         'Cache-Control': 'public, max-age=86400',
-        'Content-Length': image.byteLength,
+        'Content-Length': asset.contentLength,
         'X-Content-Type-Options': 'nosniff',
     });
-    res.end(image);
+    res.end(asset.body);
 }
 /**
  * @name readLogoAsset
@@ -135,6 +372,87 @@ function readLogoAsset() {
     logoAssetCache ??= readFileSync(LOGO_ASSET_PATH);
     return logoAssetCache;
 }
+/**
+ * @name readPublicPaymentStats
+ * @description Reads cached public-safe payment totals from the append-only usage ledger.
+ */
+export function readPublicPaymentStats(now = Date.now()) {
+    if (paymentStatsCache && paymentStatsCache.expiresAt > now) {
+        return paymentStatsCache.stats;
+    }
+    const stats = readPaymentStatsFromLedger();
+    paymentStatsCache = {
+        expiresAt: now + PAYMENT_STATS_CACHE_MS,
+        stats,
+    };
+    return stats;
+}
+function readPaymentStatsFromLedger() {
+    const stats = {
+        totalVolumeUsd: 0,
+        totalSettlements: 0,
+        totalPaymentRequests: 0,
+        totalVerifiedPayments: 0,
+        totalFailedSettlements: 0,
+        ledgerAvailable: false,
+    };
+    const ledgerPath = join(getDataDir(), 'payments', 'usage-ledger.jsonl');
+    if (!existsSync(ledgerPath)) {
+        return stats;
+    }
+    stats.ledgerAvailable = true;
+    const lines = readFileSync(ledgerPath, 'utf-8').split('\n');
+    for (const line of lines) {
+        const event = parsePaymentLedgerEvent(line);
+        if (!event) {
+            continue;
+        }
+        if (event.event === 'payment_required') {
+            stats.totalPaymentRequests += 1;
+        }
+        if (event.event === 'payment_verified') {
+            stats.totalVerifiedPayments += 1;
+        }
+        if (event.event === 'payment_settled') {
+            stats.totalSettlements += 1;
+            stats.totalVolumeUsd += event.priceUsd ?? 0;
+            stats.lastSettlementAt = event.timestamp;
+        }
+        if (event.event === 'payment_failed') {
+            stats.totalFailedSettlements += 1;
+        }
+    }
+    return stats;
+}
+function parsePaymentLedgerEvent(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!isPaymentLedgerEvent(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPaymentLedgerEvent(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return typeof record.event === 'string'
+        && typeof record.timestamp === 'string'
+        && typeof record.requestHash === 'string'
+        && typeof record.method === 'string'
+        && typeof record.path === 'string'
+        && Array.isArray(record.toolNames)
+        && typeof record.paymentHeaderPresent === 'boolean';
+}
 /**
  * @name getRateLimitKey
  * @description Resolves the best available caller identity for hosted MCP rate limiting behind a reverse proxy.
@@ -182,13 +500,27 @@ export function buildPublicServerInfo(req, config) {
         },
         endpoints: {
             landing: `${baseUrl}/`,
+            docs: `${baseUrl}/docs`,
             mcp: `${baseUrl}/mcp`,
             health: `${baseUrl}/health`,
             serverInfo: `${baseUrl}/server.json`,
+            openApi: `${baseUrl}/openapi.json`,
+            x402Discovery: `${baseUrl}/.well-known/x402`,
+            payShProvider: `${baseUrl}/pay/provider.yml`,
             agentCard: `${baseUrl}/.well-known/agent-card.json`,
             wizardDescriptor: `${baseUrl}/.well-known/sap-mcp-wizard.json`,
+            wizardDownloads: `${baseUrl}/wizard/downloads.json`,
             wizardInstallScript: `${baseUrl}/wizard/install.sh`,
             favicon: `${baseUrl}/favicon.png`,
+            faviconIco: `${baseUrl}/favicon.ico`,
+        },
+        downloads: {
+            release: `https://github.com/OOBE-PROTOCOL/sap-mcp/releases/tag/${MCP_SERVER_VERSION}`,
+            desktopWizard: {
+                macosArm64Dmg: `${RELEASE_DOWNLOAD_BASE_URL}/SAP-MCP-Wizard-${MCP_SERVER_VERSION}-arm64.dmg`,
+                windowsX64Setup: `${RELEASE_DOWNLOAD_BASE_URL}/SAP-MCP-Wizard-Setup-${MCP_SERVER_VERSION}-x64.exe`,
+                linuxX64TarGz: `${RELEASE_DOWNLOAD_BASE_URL}/sap-mcp-wizard-${MCP_SERVER_VERSION}-x64.tar.gz`,
+            },
         },
         capabilities: {
             tools: true,
@@ -202,6 +534,7 @@ export function buildPublicServerInfo(req, config) {
             schemes: authRequired ? ['Bearer'] : ['none', 'x402'],
             bearerRequired: authRequired,
         },
+        ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
         security: {
             keypairBytesExposed: false,
             storesUserKeypairs: false,
@@ -215,17 +548,252 @@ export function buildPublicServerInfo(req, config) {
         },
     };
 }
+/**
+ * @name buildPublicPayShProviderYaml
+ * @description Builds a public pay.sh provider catalog for the hosted SAP MCP endpoint without RPC secrets or signer paths.
+ */
+export function buildPublicPayShProviderYaml(req, config, appConfig) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    return generatePayShProviderYaml(appConfig, {
+        name: 'oobe-sap-mcp',
+        subdomain: 'oobe-sap-mcp',
+        title: 'OOBE SAP MCP Server',
+        description: PUBLIC_SERVER_DESCRIPTION,
+        version: MCP_SERVER_VERSION,
+        upstreamUrl: baseUrl,
+        recipient: config.paymentDiscovery?.payTo ?? appConfig.monetization.payTo,
+        rpcUrl: undefined,
+        signerPath: undefined,
+    });
+}
+/**
+ * @name buildOpenApiSpec
+ * @description OpenAPI 3.1 spec for x402scan discovery. Describes the /mcp endpoint
+ * with x-payment-info so x402scan can discover and register the API.
+ */
+export function buildOpenApiSpec(req, config) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    const priceRange = config.paymentPriceRange ?? { minUsd: 0.001, maxUsd: 100 };
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: 'SAP MCP Server',
+            version: MCP_SERVER_VERSION,
+            description: 'MCP gateway for Solana DeFi, SAP agent registry, and x402 micropayments. 248 tools across Jupiter, Drift, Metaplex, Pump.fun, Raydium, Orca, and more.',
+            'x-guidance': 'Connect to POST /mcp with Accept: application/json, text/event-stream. Initialize an MCP session first, then call tools. Paid tools return a payment_required JSON-RPC error (HTTP 200 for MCP SDK compatibility) or HTTP 402 for non-MCP clients. Use x402_paid_call or npx sap-mcp-x402-paid-call to self-pay and retry.',
+            contact: {
+                name: 'OOBE Protocol Labs',
+                url: 'https://github.com/OOBE-PROTOCOL/sap-mcp',
+                email: 'oobe@oobeprotocol.ai',
+            },
+        },
+        'x-discovery': {
+            resources: [`${baseUrl}/mcp`],
+            openApi: `${baseUrl}/openapi.json`,
+            x402Discovery: `${baseUrl}/.well-known/x402`,
+            payShProvider: `${baseUrl}/pay/provider.yml`,
+            ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
+        },
+        'x-pay-sh': {
+            providerYaml: `${baseUrl}/pay/provider.yml`,
+            routing: {
+                type: 'proxy',
+                upstream: `${baseUrl}/`,
+            },
+            monetization: {
+                mode: 'metered',
+                unit: 'requests',
+                sourceOfTruth: 'SAP MCP per-tool x402 pricing remains authoritative after proxy forwarding.',
+            },
+        },
+        servers: [
+            { url: baseUrl, description: 'SAP MCP Hosted Server' },
+        ],
+        paths: {
+            '/mcp': {
+                post: {
+                    operationId: 'mcpCall',
+                    summary: 'Fetch SAP MCP JSON-RPC response',
+                    tags: ['MCP'],
+                    'x-payment-info': {
+                        price: {
+                            mode: 'dynamic',
+                            currency: 'USD',
+                            min: formatOpenApiUsd(priceRange.minUsd),
+                            max: formatOpenApiUsd(priceRange.maxUsd),
+                        },
+                        protocols: ['x402'],
+                        ...(config.paymentDiscovery
+                            ? {
+                                network: config.paymentDiscovery.network,
+                                asset: config.paymentDiscovery.asset,
+                                assetSymbol: config.paymentDiscovery.assetSymbol,
+                                payTo: config.paymentDiscovery.payTo,
+                                seller: config.paymentDiscovery.seller,
+                                facilitator: config.paymentDiscovery.facilitator,
+                            }
+                            : {}),
+                    },
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    oneOf: [
+                                        {
+                                            type: 'object',
+                                            description: 'General MCP JSON-RPC request such as initialize, tools/list, prompts/list, resources/list, or ping.',
+                                            properties: {
+                                                jsonrpc: { type: 'string', const: '2.0' },
+                                                id: { oneOf: [{ type: 'integer' }, { type: 'string' }], description: 'JSON-RPC request ID' },
+                                                method: {
+                                                    type: 'string',
+                                                    description: 'MCP method.',
+                                                    examples: ['initialize', 'tools/list', 'prompts/list', 'resources/list', 'ping'],
+                                                },
+                                                params: { type: 'object', additionalProperties: true },
+                                            },
+                                            required: ['jsonrpc', 'id', 'method'],
+                                        },
+                                        {
+                                            type: 'object',
+                                            description: 'MCP tools/call request. Paid tool calls may require x402 payment before execution.',
+                                            properties: {
+                                                jsonrpc: { type: 'string', const: '2.0' },
+                                                id: { oneOf: [{ type: 'integer' }, { type: 'string' }], description: 'JSON-RPC request ID' },
+                                                method: { type: 'string', const: 'tools/call' },
+                                                params: {
+                                                    type: 'object',
+                                                    description: 'MCP tools/call parameters containing the target tool name and optional tool arguments.',
+                                                    properties: {
+                                                        name: { type: 'string', description: 'Tool name (e.g. jupiter_getPrice)' },
+                                                        arguments: { type: 'object', description: 'Tool arguments', additionalProperties: true },
+                                                    },
+                                                    required: ['name'],
+                                                    additionalProperties: true,
+                                                },
+                                            },
+                                            required: ['jsonrpc', 'id', 'method', 'params'],
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'MCP tool result or payment_required JSON-RPC error (for MCP SDK clients)',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            jsonrpc: { type: 'string' },
+                                            id: { type: 'integer' },
+                                            result: { type: 'object', description: 'Tool result (if free or paid)' },
+                                            error: {
+                                                type: 'object',
+                                                properties: {
+                                                    code: { type: 'integer' },
+                                                    message: { type: 'string' },
+                                                    data: {
+                                                        type: 'object',
+                                                        properties: {
+                                                            protocol: { type: 'string' },
+                                                            paymentRequirements: { type: 'array' },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                                'text/event-stream': {
+                                    schema: {
+                                        type: 'string',
+                                        description: 'Streamable HTTP MCP event stream containing JSON-RPC response events.',
+                                    },
+                                },
+                            },
+                        },
+                        '402': {
+                            description: 'Payment Required (x402 challenge for non-MCP clients)',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            x402Version: { type: 'integer' },
+                                            error: { type: 'string' },
+                                            accepts: {
+                                                type: 'array',
+                                                items: {
+                                                    type: 'object',
+                                                    properties: {
+                                                        scheme: { type: 'string' },
+                                                        network: { type: 'string' },
+                                                        amount: { type: 'string', description: 'USDC atomic units (6 decimals)' },
+                                                        asset: { type: 'string' },
+                                                        payTo: { type: 'string' },
+                                                        maxTimeoutSeconds: { type: 'integer' },
+                                                        extra: {
+                                                            type: 'object',
+                                                            properties: {
+                                                                feePayer: { type: 'string' },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                            resource: {
+                                                type: 'object',
+                                                properties: {
+                                                    url: { type: 'string' },
+                                                    description: { type: 'string' },
+                                                    mimeType: { type: 'string' },
+                                                    serviceName: { type: 'string' },
+                                                    tags: { type: 'array', items: { type: 'string' } },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+/**
+ * @name buildX402DiscoveryDocument
+ * @description Builds the compatibility discovery document consumed by x402scan.
+ */
+export function buildX402DiscoveryDocument(req, config) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    return {
+        version: 1,
+        resources: [`${baseUrl}/mcp`],
+        ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
+        instructions: 'SAP MCP exposes paid hosted MCP tool calls at /mcp. Probe POST /mcp without a payment header to receive a parseable x402 challenge for paid tools.',
+    };
+}
 /**
  * @name buildLandingHtml
  * @description Builds professional public HTML metadata for root and `/mcp` URL previews.
  */
 export function buildLandingHtml(req, config, endpoint = 'root') {
     const info = buildPublicServerInfo(req, config);
+    const paymentStats = readPublicPaymentStats();
     const pageUrl = endpoint === 'mcp' ? info.endpoints.mcp : info.endpoints.landing;
     const title = endpoint === 'mcp'
         ? 'SAP MCP Streamable HTTP Endpoint | OOBE Protocol'
         : info.title;
     const endpointLabel = endpoint === 'mcp' ? 'Streamable HTTP MCP endpoint' : 'Hosted MCP gateway';
+    const wizardCommand = WIZARD_NPM_COMMAND;
+    const installScriptCommand = 'curl -fsSL https://mcp.sap.oobeprotocol.ai/wizard/install.sh | sh';
+    const x402PaidCallCommand = X402_PAID_CALL_NPX_COMMAND;
     const publicInfo = JSON.stringify(info, null, 2).replace(/</g, '\\u003c');
     return `<!doctype html>
 <html lang="en">
@@ -236,8 +804,9 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
   <meta name="description" content="${escapeHtml(info.description)}">
   <meta name="robots" content="index,follow">
   <link rel="canonical" href="${escapeHtml(pageUrl)}">
+  <link rel="icon" type="image/x-icon" href="/favicon.ico">
   <link rel="icon" type="image/png" href="/favicon.png">
-  <link rel="shortcut icon" type="image/png" href="/favicon.png">
+  <link rel="shortcut icon" href="/favicon.ico">
   <link rel="apple-touch-icon" href="/apple-touch-icon.png">
   <meta property="og:type" content="website">
   <meta property="og:title" content="${escapeHtml(title)}">
@@ -250,72 +819,343 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
   <meta name="twitter:image" content="${escapeHtml(info.endpoints.favicon)}">
   <script type="application/ld+json">${publicInfo}</script>
   <style>
-    :root { color-scheme: dark; --aqua: #28d8e8; --ink: #f4fbff; --muted: #9db7c0; --panel: rgba(255,255,255,.055); --line: rgba(255,255,255,.14); }
+    :root {
+      color-scheme: dark;
+      --aqua: #28d8e8;
+      --aqua-soft: rgba(40,216,232,.13);
+      --ink: #f4fbff;
+      --muted: #a8bdc6;
+      --subtle: #76909a;
+      --panel: rgba(255,255,255,.062);
+      --panel-strong: rgba(255,255,255,.095);
+      --line: rgba(255,255,255,.14);
+      --line-strong: rgba(40,216,232,.38);
+      --surface: #080d12;
+      --success: #8ef3c5;
+      --warning: #ffd38a;
+    }
     * { box-sizing: border-box; }
-    body { margin: 0; min-height: 100vh; font: 16px/1.55 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: var(--ink); background: radial-gradient(circle at 20% 10%, rgba(40,216,232,.24), transparent 32rem), #080d12; }
-    main { width: min(1040px, calc(100% - 32px)); margin: 0 auto; padding: 56px 0; }
-    header { display: grid; grid-template-columns: 88px 1fr; gap: 22px; align-items: center; margin-bottom: 34px; }
-    img { width: 88px; height: 88px; border-radius: 22px; box-shadow: 0 18px 70px rgba(40,216,232,.22); }
-    h1 { margin: 0; font-size: clamp(2rem, 4vw, 4rem); line-height: 1; letter-spacing: 0; }
+    html { scroll-behavior: smooth; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      font: 16px/1.55 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      color: var(--ink);
+      background:
+        linear-gradient(115deg, rgba(40,216,232,.13), transparent 34%),
+        linear-gradient(180deg, #0a1218 0%, var(--surface) 46%, #05080b 100%);
+    }
+    body::before {
+      content: "";
+      position: fixed;
+      inset: 0;
+      pointer-events: none;
+      background-image: linear-gradient(rgba(255,255,255,.035) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,.025) 1px, transparent 1px);
+      background-size: 64px 64px;
+      mask-image: linear-gradient(to bottom, rgba(0,0,0,.75), transparent 72%);
+    }
+    main { width: min(1180px, calc(100% - 32px)); margin: 0 auto; padding: 56px 0 40px; position: relative; }
+    header { display: grid; grid-template-columns: 92px 1fr; gap: 24px; align-items: center; margin-bottom: 30px; }
+    img.logo { width: 92px; height: 92px; border-radius: 24px; box-shadow: 0 18px 70px rgba(40,216,232,.22); }
+    h1 { margin: 0; max-width: 920px; font-size: clamp(2.2rem, 5vw, 5rem); line-height: .95; letter-spacing: 0; }
     p { margin: 10px 0 0; color: var(--muted); max-width: 760px; }
-    .badge { display: inline-flex; align-items: center; gap: 8px; color: var(--aqua); font-weight: 700; text-transform: uppercase; font-size: .78rem; letter-spacing: 0; }
-    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 14px; margin-top: 28px; }
-    section, a.card { border: 1px solid var(--line); border-radius: 8px; background: var(--panel); padding: 18px; text-decoration: none; color: inherit; }
-    h2 { margin: 0 0 12px; font-size: 1rem; color: var(--aqua); }
-    code { color: #dffbff; overflow-wrap: anywhere; }
-    ul { padding-left: 18px; margin: 0; color: var(--muted); }
-    li + li { margin-top: 8px; }
-    a { color: var(--aqua); }
+    a { color: var(--aqua); text-underline-offset: 4px; }
+    a:focus-visible { outline: 2px solid var(--aqua); outline-offset: 3px; border-radius: 6px; }
+    code {
+      color: #e9fcff;
+      overflow-wrap: anywhere;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+      font-size: .92em;
+    }
+    .badge { display: inline-flex; align-items: center; gap: 8px; color: var(--aqua); font-weight: 750; text-transform: uppercase; font-size: .78rem; letter-spacing: 0; }
+    .hero-actions { display: flex; flex-wrap: wrap; gap: 12px; margin-top: 22px; }
+    .button {
+      display: inline-flex;
+      min-height: 42px;
+      align-items: center;
+      justify-content: center;
+      border: 1px solid var(--line-strong);
+      border-radius: 8px;
+      padding: 9px 14px;
+      background: var(--aqua-soft);
+      color: var(--ink);
+      font-weight: 700;
+      text-decoration: none;
+    }
+    .button.secondary { background: transparent; border-color: var(--line); color: var(--aqua); }
+    .bento { display: grid; grid-template-columns: repeat(12, 1fr); gap: 14px; margin-top: 28px; }
+    .card {
+      min-height: 148px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--panel);
+      padding: 18px;
+      color: inherit;
+      text-decoration: none;
+    }
+    .card.strong { background: linear-gradient(180deg, var(--panel-strong), var(--panel)); border-color: var(--line-strong); }
+    .span-3 { grid-column: span 3; }
+    .span-4 { grid-column: span 4; }
+    .span-5 { grid-column: span 5; }
+    .span-6 { grid-column: span 6; }
+    .span-7 { grid-column: span 7; }
+    .span-8 { grid-column: span 8; }
+    .span-12 { grid-column: span 12; }
+    h2 { margin: 0 0 12px; font-size: 1rem; color: var(--aqua); letter-spacing: 0; }
+    h3 { margin: 0 0 6px; font-size: .86rem; color: var(--muted); font-weight: 650; text-transform: uppercase; letter-spacing: 0; }
+    .metric { margin-top: 4px; font-size: clamp(2rem, 4vw, 3.35rem); line-height: 1; font-weight: 800; letter-spacing: 0; }
+    .metric.small { font-size: clamp(1.55rem, 3vw, 2.3rem); }
+    .caption { margin-top: 10px; color: var(--subtle); font-size: .94rem; }
+    .status { color: var(--success); }
+    .warning { color: var(--warning); }
+    .list { padding-left: 18px; margin: 0; color: var(--muted); }
+    .list li + li { margin-top: 8px; }
+    .command { margin-top: 12px; border: 1px solid rgba(255,255,255,.10); border-radius: 8px; background: rgba(0,0,0,.28); padding: 13px; }
+    .download-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 10px; margin-top: 14px; }
+    .download-link {
+      display: grid;
+      min-height: 74px;
+      align-content: center;
+      gap: 4px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: rgba(0,0,0,.18);
+      padding: 12px;
+      color: var(--ink);
+      text-decoration: none;
+    }
+    .download-link strong { color: var(--aqua); }
+    .download-link span { color: var(--muted); font-size: .88rem; }
+    .endpoint-list { display: grid; gap: 10px; margin-top: 10px; }
+    .endpoint-row { display: grid; grid-template-columns: 72px 1fr; gap: 12px; align-items: baseline; }
+    .method { color: var(--success); font: 700 .78rem/1 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
     .footer { margin-top: 26px; color: var(--muted); font-size: .94rem; }
+    @media (max-width: 860px) {
+      header { grid-template-columns: 1fr; }
+      img.logo { width: 76px; height: 76px; border-radius: 20px; }
+      .span-3, .span-4, .span-5, .span-6, .span-7, .span-8 { grid-column: span 12; }
+      .download-grid { grid-template-columns: 1fr; }
+    }
+    @media (min-width: 861px) and (max-width: 1120px) {
+      .span-3, .span-4 { grid-column: span 6; }
+      .span-5, .span-6, .span-7, .span-8 { grid-column: span 12; }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      html { scroll-behavior: auto; }
+    }
   </style>
 </head>
 <body>
   <main>
     <header>
-      <img src="/favicon.png" alt="SAP MCP logo">
+      <img class="logo" src="/favicon.png" alt="SAP MCP logo" width="92" height="92">
       <div>
         <span class="badge">OOBE Protocol • ${escapeHtml(endpointLabel)}</span>
         <h1>${escapeHtml(title)}</h1>
         <p>${escapeHtml(info.description)}</p>
+        <div class="hero-actions">
+          <a class="button" href="/wizard/install.sh">Install wizard</a>
+          <a class="button secondary" href="/wizard/downloads.json">Downloads</a>
+          <a class="button secondary" href="/docs">Docs</a>
+          <a class="button secondary" href="/server.json">Server JSON</a>
+          <a class="button secondary" href="/openapi.json">OpenAPI</a>
+          <a class="button secondary" href="/pay/provider.yml">pay.sh YAML</a>
+          <a class="button secondary" href="/.well-known/agent-card.json">Agent card</a>
+        </div>
       </div>
     </header>
-    <div class="grid">
-      <section>
-        <h2>Public Endpoints</h2>
-        <ul>
-          <li>MCP: <code>${escapeHtml(info.endpoints.mcp)}</code></li>
-          <li>Health: <code>${escapeHtml(info.endpoints.health)}</code></li>
-          <li>Server info: <code>${escapeHtml(info.endpoints.serverInfo)}</code></li>
-          <li>Agent card: <code>${escapeHtml(info.endpoints.agentCard)}</code></li>
-        </ul>
+
+    <div class="bento" aria-label="SAP MCP hosted server overview">
+      <section class="card strong span-4">
+        <h3>Facilitator Volume</h3>
+        <div class="metric">${escapeHtml(formatUsd(paymentStats.totalVolumeUsd))}</div>
+        <p class="caption">Estimated settled x402/pay.sh tool volume recorded by the hosted payment ledger.</p>
+      </section>
+
+      <section class="card strong span-4">
+        <h3>Total Settlements</h3>
+        <div class="metric">${escapeHtml(formatInteger(paymentStats.totalSettlements))}</div>
+        <p class="caption">${escapeHtml(formatLastSettlement(paymentStats))}</p>
+      </section>
+
+      <section class="card span-4">
+        <h3>Payment Requests</h3>
+        <div class="metric">${escapeHtml(formatInteger(paymentStats.totalPaymentRequests))}</div>
+        <p class="caption"><span class="status">${escapeHtml(formatInteger(paymentStats.totalVerifiedPayments))}</span> verified, <span class="warning">${escapeHtml(formatInteger(paymentStats.totalFailedSettlements))}</span> failed settlements.</p>
+      </section>
+
+      <section class="card span-7">
+        <h2>Install Wizard</h2>
+        <p>Create a local SAP MCP profile, signer, policy limits, and optional client injection. Hosted users still sign x402/pay.sh and value-moving operations from their own machine or external signer.</p>
+        <div class="command"><code>${escapeHtml(installScriptCommand)}</code></div>
+        <div class="command"><code>${escapeHtml(wizardCommand)}</code></div>
+      </section>
+
+      <section class="card span-5">
+        <h2>Native Downloads</h2>
+        <p>Use the desktop wizard when you want a guided setup without touching config files by hand.</p>
+        <div class="download-grid">
+          <a class="download-link" href="${escapeHtml(info.downloads.desktopWizard.windowsX64Setup)}"><strong>Windows</strong><span>x64 setup .exe</span></a>
+          <a class="download-link" href="${escapeHtml(info.downloads.desktopWizard.macosArm64Dmg)}"><strong>macOS</strong><span>Apple Silicon .dmg</span></a>
+          <a class="download-link" href="${escapeHtml(info.downloads.desktopWizard.linuxX64TarGz)}"><strong>Linux</strong><span>x64 tar.gz</span></a>
+        </div>
+        <p class="caption">Machine-readable links: <a href="${escapeHtml(info.endpoints.wizardDownloads)}">/wizard/downloads.json</a>.</p>
       </section>
-      <section>
-        <h2>Capabilities</h2>
-        <ul>
-          <li>Native MCP tools, resources, and prompts</li>
-          <li>x402 and pay.sh monetization flows</li>
-          <li>User-controlled signing through local profile or external signer</li>
-          <li>Wizard config under <code>~/.config/mcp-sap</code></li>
+
+      <section class="card span-5">
+        <h2>Payments</h2>
+        <ul class="list">
+          <li><strong>x402:</strong> paid MCP tool calls return HTTP 402 with payment requirements, then settle through the OOBE facilitator.</li>
+          <li><strong>pay.sh:</strong> public provider YAML is available at <a href="${escapeHtml(info.endpoints.payShProvider)}">/pay/provider.yml</a> for catalog and proxy workflows.</li>
+          <li><strong>Local stdio:</strong> free by default; monetization applies to hosted remote usage.</li>
         </ul>
       </section>
-      <section>
-        <h2>Security</h2>
-        <ul>
+
+      <section class="card strong span-12">
+        <h2>x402 Paid-Call Plugin For Agents</h2>
+        <p>Agents that can reach hosted MCP but cannot replay x402 challenges natively can install the wizard addon or invoke the local paid-call helper directly. The helper signs the payment payload locally and retries the hosted tool call without sending keypair bytes to OOBE.</p>
+        <div class="command"><code>Addon path: ${escapeHtml(X402_PAID_CALL_ADDON_PATH)}</code></div>
+        <div class="command"><code>${escapeHtml(x402PaidCallCommand)}</code></div>
+      </section>
+
+      <section class="card span-8">
+        <h2>Endpoints</h2>
+        <div class="endpoint-list">
+          <div class="endpoint-row"><span class="method">POST</span><code>${escapeHtml(info.endpoints.mcp)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.docs)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.health)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.serverInfo)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.openApi)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.x402Discovery)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.payShProvider)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.agentCard)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.wizardDescriptor)}</code></div>
+        </div>
+      </section>
+
+      <section class="card span-4">
+        <h2>Security Boundary</h2>
+        <ul class="list">
           <li>Keypair bytes are never exposed by public endpoints.</li>
-          <li>Hosted server metadata does not print private RPC query secrets.</li>
-          <li>Paid tools return 402 payment instructions before execution.</li>
+          <li>RPC secrets are redacted from public metadata and UI.</li>
+          <li>Paid tools require payment before execution.</li>
         </ul>
       </section>
-      <section>
-        <h2>Install Wizard</h2>
-        <p><code>npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard</code></p>
-      </section>
     </div>
     <p class="footer">Use <a href="/server.json">/server.json</a> for machine-readable public metadata. MCP clients should connect to <a href="/mcp">/mcp</a> with <code>Accept: application/json, text/event-stream</code>.</p>
   </main>
 </body>
 </html>`;
 }
+/**
+ * @name buildDocsHtml
+ * @description Builds the hosted SAP MCP documentation shell powered by Docsify.
+ */
+export function buildDocsHtml(req, config) {
+    const info = buildPublicServerInfo(req, config);
+    const docsUrl = info.endpoints.docs;
+    const title = 'SAP MCP Documentation | OOBE Protocol';
+    const description = 'Install, configure, and operate SAP MCP with a focus on hosted remote access, local signer setup, x402/pay.sh payments, and MCP client configuration.';
+    const docsifyConfig = JSON.stringify({
+        name: 'SAP MCP',
+        repo: 'https://github.com/OOBE-PROTOCOL/sap-mcp',
+        homepage: 'README.md',
+        loadSidebar: true,
+        alias: {
+            '/.*/_sidebar.md': '/docs/_sidebar.md',
+        },
+        subMaxLevel: 2,
+        auto2top: true,
+        themeColor: '#28d8e8',
+        search: {
+            paths: 'auto',
+            placeholder: 'Search SAP MCP docs',
+            noData: 'No results.',
+            depth: 6,
+        },
+    }, null, 2).replace(/</g, '\\u003c');
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <meta name="description" content="${escapeHtml(description)}">
+  <meta name="robots" content="index,follow">
+  <link rel="canonical" href="${escapeHtml(docsUrl)}">
+  <link rel="icon" type="image/x-icon" href="/favicon.ico">
+  <link rel="icon" type="image/png" href="/favicon.png">
+  <link rel="shortcut icon" href="/favicon.ico">
+  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
+  <meta property="og:type" content="website">
+  <meta property="og:title" content="${escapeHtml(title)}">
+  <meta property="og:description" content="${escapeHtml(description)}">
+  <meta property="og:url" content="${escapeHtml(docsUrl)}">
+  <meta property="og:image" content="${escapeHtml(info.endpoints.favicon)}">
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="${escapeHtml(title)}">
+  <meta name="twitter:description" content="${escapeHtml(description)}">
+  <meta name="twitter:image" content="${escapeHtml(info.endpoints.favicon)}">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/themes/vue.css">
+  <style>
+    :root {
+      --theme-color: #28d8e8;
+      --sidebar-width: 310px;
+    }
+    body {
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      color: #17242b;
+    }
+    .app-name-link {
+      color: #062730;
+      font-weight: 800;
+    }
+    .sidebar {
+      border-right: 1px solid rgba(6,39,48,.10);
+    }
+    .sidebar-nav strong,
+    .markdown-section h1,
+    .markdown-section h2,
+    .markdown-section h3 {
+      color: #062730;
+      letter-spacing: 0;
+    }
+    .markdown-section a {
+      color: #087f91;
+      text-underline-offset: 3px;
+    }
+    .markdown-section code {
+      color: #062730;
+      border-radius: 6px;
+    }
+    .markdown-section pre {
+      border-radius: 8px;
+      border: 1px solid rgba(6,39,48,.10);
+    }
+    .markdown-section table {
+      display: table;
+      width: 100%;
+    }
+    .markdown-section blockquote {
+      border-left-color: #28d8e8;
+      color: #49656f;
+    }
+    .cover-main,
+    section.cover {
+      background: linear-gradient(115deg, rgba(40,216,232,.13), transparent 34%), #f8fdff;
+    }
+  </style>
+</head>
+<body>
+  <div id="app">Loading SAP MCP documentation...</div>
+  <script>
+    window.$docsify = ${docsifyConfig};
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/docsify.min.js" defer></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/plugins/search.min.js" defer></script>
+</body>
+</html>`;
+}
 /**
  * @name acceptsHtmlPreview
  * @description Returns true for browser-style GET previews without interfering with MCP SSE clients.
@@ -324,6 +1164,30 @@ function acceptsHtmlPreview(req) {
     const accept = String(req.headers.accept ?? '');
     return accept.includes('text/html') && !accept.includes('text/event-stream') && !accept.includes('application/json');
 }
+function formatUsd(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return '$0.00';
+    }
+    return `$${value.toLocaleString('en-US', {
+        minimumFractionDigits: value < 1 ? 3 : 2,
+        maximumFractionDigits: value < 1 ? 3 : 2,
+    })}`;
+}
+function formatInteger(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return '0';
+    }
+    return Math.trunc(value).toLocaleString('en-US');
+}
+function formatLastSettlement(stats) {
+    if (!stats.ledgerAvailable) {
+        return 'Ledger not initialized yet. Metrics appear after the first paid hosted call.';
+    }
+    if (!stats.lastSettlementAt) {
+        return 'No settlements yet. Paid requests will update this card after successful settlement.';
+    }
+    return `Last settlement: ${stats.lastSettlementAt}`;
+}
 /**
  * @name escapeHtml
  * @description Escapes dynamic strings before embedding them in public HTML metadata.
@@ -432,13 +1296,16 @@ export function buildWizardInstallDescriptor(req, config) {
         ],
         endpoints: {
             descriptor: `${baseUrl}/.well-known/sap-mcp-wizard.json`,
+            downloads: `${baseUrl}/wizard/downloads.json`,
             installScript: `${baseUrl}/wizard/install.sh`,
             mcp: `${baseUrl}/mcp`,
         },
         commands: {
-            runWizard: 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard',
+            runWizard: WIZARD_NPM_COMMAND,
             showConfig: 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config show',
             showProfile: 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config profile-info',
+            installX402PaidCallAddon: WIZARD_NPM_COMMAND,
+            runX402PaidCall: X402_PAID_CALL_NPX_COMMAND,
         },
         security: {
             keypairBytesExposed: false,
@@ -470,6 +1337,44 @@ export function buildWizardInstallScript(req, config) {
         '',
     ].join('\n');
 }
+/**
+ * @name extractToolNamesFromJsonRpc
+ * @description Extracts tool names from a parsed JSON-RPC 2.0 request body for request logging.
+ */
+function extractToolNamesFromJsonRpc(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const record = body;
+    // tools/call request: { method: "tools/call", params: { name: "tool_name", ... } }
+    if (record.method === 'tools/call' && record.params && typeof record.params === 'object') {
+        const params = record.params;
+        if (typeof params.name === 'string')
+            return [params.name];
+    }
+    // Batch request: array of requests
+    if (Array.isArray(body)) {
+        const names = [];
+        for (const item of body) {
+            const extracted = extractToolNamesFromJsonRpc(item);
+            if (extracted)
+                names.push(...extracted);
+        }
+        return names.length > 0 ? names : undefined;
+    }
+    return undefined;
+}
+/**
+ * @name extractJsonRpcMethod
+ * @description Extracts the JSON-RPC method name from a parsed request body for request logging.
+ */
+function extractJsonRpcMethod(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const record = body;
+    if (typeof record.method === 'string')
+        return record.method;
+    return undefined;
+}
 /**
  * @name RemoteMCPServer
  * @description Remote MCP server backed by the official Streamable HTTP transport.
@@ -479,7 +1384,7 @@ export class RemoteMCPServer {
     appConfig;
     authManager;
     rateLimiter;
-    transport;
+    statefulSessions = new Map();
     httpServer;
     constructor(config) {
         this.appConfig = loadConfig();
@@ -499,58 +1404,89 @@ export class RemoteMCPServer {
     async start() {
         this.validateAuthConfig();
         await this.rateLimiter.initialize();
-        const server = await createSapMcpServer(this.appConfig);
-        this.transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: this.config.stateless ? undefined : () => randomUUID(),
-        });
-        await server.connect(this.transport);
         const monetizationGate = await McpMonetizationGate.create(this.appConfig);
         this.httpServer = http.createServer(async (req, res) => {
             if (this.applyCors(req, res)) {
                 return;
             }
             const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
-            if (req.method === 'GET' && url.pathname === '/') {
-                writeHtml(res, 200, buildLandingHtml(req, this.config));
+            if (isPublicReadMethod(req.method) && url.pathname === '/') {
+                writeHtml(res, 200, buildLandingHtml(req, this.config), isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && ['/docs', '/docs/', '/docs/index.html'].includes(url.pathname)) {
+                writeHtml(res, 200, buildDocsHtml(req, this.config), isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/server.json') {
+            if (isPublicReadMethod(req.method) && url.pathname === '/server.json') {
                 writeJson(res, 200, buildPublicServerInfo(req, this.config), {
                     'Cache-Control': 'public, max-age=300',
-                });
+                }, isHeadMethod(req.method));
+                return;
+            }
+            const publicLogoAsset = resolvePublicLogoAsset(req.method, url.pathname);
+            if (publicLogoAsset) {
+                writeLogoAsset(res, publicLogoAsset);
                 return;
             }
-            if (req.method === 'GET' && ['/favicon.png', '/favicon.ico', '/apple-touch-icon.png', '/og.png'].includes(url.pathname)) {
-                writePngAsset(res);
+            const publicDocsMarkdown = resolvePublicDocsMarkdown(req.method, url.pathname);
+            if (publicDocsMarkdown) {
+                writeMarkdownAsset(res, publicDocsMarkdown);
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/health') {
+            if (isPublicReadMethod(req.method) && url.pathname === '/health') {
                 writeJson(res, 200, {
                     status: 'ok',
                     service: 'sap-mcp-remote',
                     transport: 'streamable-http',
                     timestamp: new Date().toISOString(),
-                });
+                }, {}, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && ['/.well-known/agent-card.json', '/a2a/agent-card'].includes(url.pathname)) {
+                writeJson(res, 200, buildA2AAgentCard(req, this.config), {}, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && ['/.well-known/sap-mcp-wizard.json', '/wizard', '/wizard.json'].includes(url.pathname)) {
+                writeJson(res, 200, buildWizardInstallDescriptor(req, this.config), {}, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/wizard/downloads.json') {
+                const info = buildPublicServerInfo(req, this.config);
+                writeJson(res, 200, info.downloads, {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/openapi.json') {
+                writeJson(res, 200, buildOpenApiSpec(req, this.config), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && ['/.well-known/agent-card.json', '/a2a/agent-card'].includes(url.pathname)) {
-                writeJson(res, 200, buildA2AAgentCard(req, this.config));
+            if (isPublicReadMethod(req.method) && url.pathname === '/pay/provider.yml') {
+                const providerYaml = buildPublicPayShProviderYaml(req, this.config, this.appConfig);
+                writeText(res, 200, providerYaml, 'application/yaml; charset=utf-8', {}, isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && ['/.well-known/sap-mcp-wizard.json', '/wizard', '/wizard.json'].includes(url.pathname)) {
-                writeJson(res, 200, buildWizardInstallDescriptor(req, this.config));
+            if (isPublicReadMethod(req.method) && url.pathname === '/.well-known/x402') {
+                writeJson(res, 200, buildX402DiscoveryDocument(req, this.config), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/wizard/install.sh') {
+            if (isPublicReadMethod(req.method) && url.pathname === '/wizard/install.sh') {
+                const script = buildWizardInstallScript(req, this.config);
                 res.writeHead(200, {
                     'Content-Type': 'text/x-shellscript; charset=utf-8',
                     'Cache-Control': 'public, max-age=300',
+                    'Content-Length': Buffer.byteLength(script),
                 });
-                res.end(buildWizardInstallScript(req, this.config));
+                res.end(isHeadMethod(req.method) ? undefined : script);
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/mcp' && acceptsHtmlPreview(req)) {
-                writeHtml(res, 200, buildLandingHtml(req, this.config, 'mcp'));
+            if (isPublicReadMethod(req.method) && url.pathname === '/mcp' && (isHeadMethod(req.method) || acceptsHtmlPreview(req))) {
+                writeHtml(res, 200, buildLandingHtml(req, this.config, 'mcp'), isHeadMethod(req.method));
                 return;
             }
             if (url.pathname !== '/mcp') {
@@ -577,14 +1513,64 @@ export class RemoteMCPServer {
                 });
                 return;
             }
+            // ── Request logging ─────────────────────────────────────────────
+            const reqStart = Date.now();
+            const callerIp = getRateLimitKey(req);
+            const originalEnd = res.end.bind(res);
+            let loggedMethod;
+            let loggedToolNames;
+            res.end = ((...args) => {
+                const latencyMs = Date.now() - reqStart;
+                const statusCode = res.statusCode;
+                logger.info('MCP request', {
+                    method: req.method,
+                    path: url.pathname,
+                    status: statusCode,
+                    latencyMs,
+                    callerIp,
+                    toolNames: loggedToolNames,
+                    rpcMethod: loggedMethod,
+                });
+                return originalEnd(...args);
+            });
             try {
-                if (monetizationGate) {
-                    await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
-                        await this.transport?.handleRequest(mcpReq, mcpRes, parsedBody);
+                if (this.config.stateless) {
+                    // Stateless mode: create a fresh transport + server per request.
+                    // The MCP SDK prohibits reusing a stateless transport across requests.
+                    const perRequestServer = await createSapMcpServer(this.appConfig);
+                    const perRequestTransport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: undefined,
                     });
+                    await perRequestServer.connect(perRequestTransport);
+                    if (monetizationGate) {
+                        await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                            // Extract tool names from parsed JSON-RPC body for logging
+                            loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
+                            loggedMethod = extractJsonRpcMethod(parsedBody);
+                            await perRequestTransport.handleRequest(mcpReq, mcpRes, parsedBody);
+                        });
+                    }
+                    else {
+                        // Parse body for logging before passing to transport
+                        // The transport will re-read it from the stream
+                        loggedToolNames = undefined; // Will be logged without tool names in free mode
+                        await perRequestTransport.handleRequest(req, res);
+                    }
                 }
                 else {
-                    await this.transport?.handleRequest(req, res);
+                    // Stateful mode: route each request to the transport created by its initialize response.
+                    if (monetizationGate) {
+                        await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                            loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
+                            loggedMethod = extractJsonRpcMethod(parsedBody);
+                            await this.handleStatefulMcpRequest(mcpReq, mcpRes, parsedBody);
+                        }, {
+                            validatePaidRequest: context => this.validateStatefulPaidRequest(context.request, context.parsedBody),
+                        });
+                    }
+                    else {
+                        await this.handleStatefulMcpRequest(req, res);
+                    }
                 }
             }
             catch (error) {
@@ -622,7 +1608,9 @@ export class RemoteMCPServer {
      * @description Gracefully closes the MCP transport and HTTP listener.
      */
     async stop() {
-        await this.transport?.close();
+        const sessions = Array.from(this.statefulSessions.values());
+        this.statefulSessions.clear();
+        await Promise.allSettled(sessions.map(session => session.transport.close()));
         if (!this.httpServer) {
             return;
         }
@@ -650,6 +1638,110 @@ export class RemoteMCPServer {
             throw new Error('Remote MCP JWT auth requires SAP_MCP_AUTH_SECRET');
         }
     }
+    /**
+     * @name handleStatefulMcpRequest
+     * @description Routes a stateful MCP request to the session transport created by initialize.
+     */
+    async handleStatefulMcpRequest(req, res, parsedBody) {
+        const transport = await this.resolveStatefulTransport(req, parsedBody);
+        if (!transport) {
+            const providedSessionId = readSingleHeader(req.headers['mcp-session-id']);
+            writeMcpJsonRpcError(res, providedSessionId ? 404 : 400, providedSessionId ? -32011 : -32010, extractJsonRpcId(parsedBody), providedSessionId ? 'mcp_session_not_found' : 'mcp_session_required', {
+                requiredHeader: 'mcp-session-id',
+                ...(providedSessionId ? { providedSessionId } : {}),
+                hint: providedSessionId
+                    ? 'The mcp-session-id must come from this server initialize response. Client-generated UUIDs are not valid MCP sessions.'
+                    : 'Call initialize first and reuse the returned mcp-session-id header. Do not generate a client-side UUID.',
+            });
+            return;
+        }
+        await transport.handleRequest(req, res, parsedBody);
+    }
+    /**
+     * @name validateStatefulPaidRequest
+     * @description Fails paid tool calls before x402 verification when the MCP session is missing or unknown.
+     */
+    validateStatefulPaidRequest(req, parsedBody) {
+        if (isInitializeJsonRpcRequest(parsedBody)) {
+            return undefined;
+        }
+        const sessionId = readSingleHeader(req.headers['mcp-session-id']);
+        if (!sessionId) {
+            return {
+                code: -32010,
+                message: 'mcp_session_required',
+                data: {
+                    requiredHeader: 'mcp-session-id',
+                    hint: 'Initialize the MCP Streamable HTTP session first, then reuse the returned mcp-session-id for the unpaid payment challenge and the paid retry.',
+                },
+            };
+        }
+        if (!this.statefulSessions.has(sessionId)) {
+            return {
+                code: -32011,
+                message: 'mcp_session_not_found',
+                data: {
+                    requiredHeader: 'mcp-session-id',
+                    providedSessionId: sessionId,
+                    hint: 'The mcp-session-id must come from this server initialize response. Client-generated UUIDs are not valid MCP sessions.',
+                },
+            };
+        }
+        return undefined;
+    }
+    /**
+     * @name resolveStatefulTransport
+     * @description Returns the transport for an existing session or creates one for an initialize request.
+     */
+    async resolveStatefulTransport(req, parsedBody) {
+        const sessionId = readSingleHeader(req.headers['mcp-session-id']);
+        if (sessionId) {
+            const session = this.statefulSessions.get(sessionId);
+            if (!session) {
+                return undefined;
+            }
+            session.lastSeenAt = Date.now();
+            return session.transport;
+        }
+        if (req.method === 'POST' && (parsedBody === undefined || isInitializeJsonRpcRequest(parsedBody))) {
+            return await this.createStatefulSessionTransport();
+        }
+        return undefined;
+    }
+    /**
+     * @name createStatefulSessionTransport
+     * @description Creates one MCP server and Streamable HTTP transport for a single initialized session.
+     */
+    async createStatefulSessionTransport() {
+        const server = await createSapMcpServer(this.appConfig);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: sessionId => {
+                this.statefulSessions.set(sessionId, {
+                    server,
+                    transport,
+                    createdAt: Date.now(),
+                    lastSeenAt: Date.now(),
+                });
+                logger.info('Stateful MCP session initialized', {
+                    sessionId,
+                    activeSessions: this.statefulSessions.size,
+                });
+            },
+        });
+        transport.onclose = () => {
+            const sessionId = transport.sessionId;
+            if (sessionId) {
+                this.statefulSessions.delete(sessionId);
+                logger.info('Stateful MCP session closed', {
+                    sessionId,
+                    activeSessions: this.statefulSessions.size,
+                });
+            }
+        };
+        await server.connect(transport);
+        return transport;
+    }
     /**
      * @name applyCors
      * @description Applies configured CORS headers and handles preflight requests.