@oobe-protocol-labs/sap-mcp-server 0.9.2 → 0.9.3

package/dist/remote/server.js

@@ -14,10 +14,16 @@ 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, resolvePaymentNetwork } from '../payments/index.js';
+import { McpMonetizationGate, buildPricingCatalog, resolvePaymentNetwork } from '../payments/index.js';
 import { generatePayShProviderYaml } from '../payments/pay-sh-spec.js';
+import { listPremiumPlugins, premiumPrivatePluginSupport, publicPremiumProviderStatus, getPremiumMetrics, } from '../premium/index.js';
 import { RemoteRateLimiter, buildRemoteRateLimitConfigFromEnv } from './rate-limiter.js';
 import { renderLandingPage } from './public-home/index.js';
+import { TX_SUBMIT_PATH, submitSignedTransactionFromHttp } from './tx-relay.js';
+import { tryPremiumRoute } from './premium-routes.js';
+import { PremiumMemoryManager } from './premium-memory.js';
+import { preloadPremiumProviders, disconnectAllProviders } from '../premium/provider-bridge.js';
+import { asyncMemoryProcessor, memoryDatabase } from '../memory/index.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');
@@ -30,7 +36,8 @@ const PAYMENT_STATS_CACHE_MS = 15_000;
 const SERVER_CARD_CACHE_MS = 300_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 REPAIR_NPM_COMMAND = 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config repair';
+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.05 --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';
@@ -542,7 +549,10 @@ function readPaymentStatsFromLedger() {
         totalVolumeUsd: 0,
         totalSettlements: 0,
         totalPaymentRequests: 0,
+        totalChallengesReturned: 0,
         totalVerifiedPayments: 0,
+        totalVerificationFailures: 0,
+        totalEligibilityBlocks: 0,
         totalFailedSettlements: 0,
         uniqueRemoteCallers: 0,
         uniqueUserAgents: 0,
@@ -570,9 +580,18 @@ function readPaymentStatsFromLedger() {
         if (event.event === 'payment_required') {
             stats.totalPaymentRequests += 1;
         }
+        if (event.event === 'payment_challenge_returned') {
+            stats.totalChallengesReturned += 1;
+        }
         if (event.event === 'payment_verified') {
             stats.totalVerifiedPayments += 1;
         }
+        if (event.event === 'payment_verification_failed') {
+            stats.totalVerificationFailures += 1;
+        }
+        if (event.event === 'payment_eligibility_blocked') {
+            stats.totalEligibilityBlocks += 1;
+        }
         if (event.event === 'payment_settled') {
             stats.totalSettlements += 1;
             stats.totalVolumeUsd += event.priceUsd ?? 0;
@@ -684,9 +703,18 @@ export function buildPublicServerInfo(req, config) {
             landing: `${baseUrl}/`,
             docs: `${baseUrl}/docs`,
             mcp: `${baseUrl}/mcp`,
+            txSubmit: `${baseUrl}${TX_SUBMIT_PATH}`,
             health: `${baseUrl}/health`,
             serverInfo: `${baseUrl}/server.json`,
+            pricing: `${baseUrl}/pricing.json`,
             openApi: `${baseUrl}/openapi.json`,
+            premiumCatalog: `${baseUrl}/premium/catalog.json`,
+            premiumStreams: `${baseUrl}/premium/streams.json`,
+            premiumWebhooks: `${baseUrl}/premium/webhooks.json`,
+            premiumHealth: `${baseUrl}/premium/health.json`,
+            premiumActivate: `${baseUrl}/premium/activate`,
+            premiumStreamBase: `${baseUrl}/premium/stream`,
+            premiumWebhookRegister: `${baseUrl}/premium/webhook/register`,
             x402Discovery: `${baseUrl}/.well-known/x402`,
             smitheryConfigSchema: `${baseUrl}/smithery.config.schema.json`,
             smitheryServerCard: `${baseUrl}/.well-known/mcp/server-card.json`,
@@ -753,6 +781,49 @@ export function buildMarketplaceConfigurationMetadata(req, config) {
         },
     };
 }
+/**
+ * @name buildPremiumDiscoveryDocument
+ * @description Builds public premium stream/webhook/plugin contracts for agent runtimes and marketplaces.
+ */
+export function buildPremiumDiscoveryDocument(req, config, type) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    const plugins = listPremiumPlugins();
+    const capabilities = plugins.flatMap(plugin => plugin.capabilities
+        .filter(capability => !type || capability.type === type)
+        .map(capability => ({
+        ...capability,
+        pluginId: plugin.id,
+        providerReady: capability.providerEnv.every(envName => Boolean(process.env[envName])),
+    })));
+    return {
+        version: '1.0.0',
+        service: 'sap-mcp-server',
+        serverVersion: MCP_SERVER_VERSION,
+        kind: type ? `premium-${type}-catalog` : 'premium-plugin-catalog',
+        title: type ? `SAP MCP Premium ${type === 'stream' ? 'Stream' : 'Webhook'} Catalog` : 'SAP MCP Premium Plugin Catalog',
+        description: 'Public, secret-free premium capability contracts for SAP MCP. Discovery and planning are free; live delivery requires x402/pay.sh settlement and configured providers.',
+        links: {
+            catalog: `${baseUrl}/premium/catalog.json`,
+            streams: `${baseUrl}/premium/streams.json`,
+            webhooks: `${baseUrl}/premium/webhooks.json`,
+            docs: `${baseUrl}/docs/18_PREMIUM_PLUGIN_RUNTIME.md`,
+            mcp: `${baseUrl}/mcp`,
+            pricing: `${baseUrl}/pricing.json`,
+            x402Discovery: `${baseUrl}/.well-known/x402`,
+            payShProvider: `${baseUrl}/pay/provider.yml`,
+        },
+        monetization: {
+            planning: 'free',
+            liveDelivery: 'x402/pay.sh required when the selected provider is live and the session is activated.',
+            sourceOfTruth: `${baseUrl}/pricing.json`,
+            localBridgeTool: 'sap_payments_call_paid_tool',
+        },
+        providerStatus: publicPremiumProviderStatus(),
+        privatePluginSupport: premiumPrivatePluginSupport(),
+        capabilities,
+        ...(type ? {} : { plugins }),
+    };
+}
 /**
  * @name readSmitheryConfigSchema
  * @description Reads the published Smithery JSON schema from the packaged root.
@@ -876,7 +947,7 @@ export function buildOpenApiSpec(req, config) {
         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.',
+            description: 'MCP gateway for Solana DeFi, SAP agent registry, and x402 micropayments 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 the local sap_payments_call_paid_tool bridge or npx sap-mcp-x402-paid-call to self-pay and retry.',
             contact: {
                 name: 'OOBE Protocol Labs',
@@ -887,6 +958,14 @@ export function buildOpenApiSpec(req, config) {
         'x-discovery': {
             resources: [`${baseUrl}/mcp`],
             openApi: `${baseUrl}/openapi.json`,
+            pricing: `${baseUrl}/pricing.json`,
+            premiumCatalog: `${baseUrl}/premium/catalog.json`,
+            premiumStreams: `${baseUrl}/premium/streams.json`,
+            premiumWebhooks: `${baseUrl}/premium/webhooks.json`,
+            premiumHealth: `${baseUrl}/premium/health.json`,
+            premiumActivate: `${baseUrl}/premium/activate`,
+            premiumStreamBase: `${baseUrl}/premium/stream`,
+            premiumWebhookRegister: `${baseUrl}/premium/webhook/register`,
             x402Discovery: `${baseUrl}/.well-known/x402`,
             payShProvider: `${baseUrl}/pay/provider.yml`,
             ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
@@ -1064,6 +1143,171 @@ export function buildOpenApiSpec(req, config) {
                     },
                 },
             },
+            '/premium/catalog.json': {
+                get: {
+                    operationId: 'fetchPremiumCatalog',
+                    summary: 'Fetch premium plugin catalog',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Secret-free premium plugin, stream, webhook, schema, pricing, and provider readiness metadata.',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            version: { type: 'string' },
+                                            service: { type: 'string' },
+                                            kind: { type: 'string' },
+                                            capabilities: { type: 'array', items: { type: 'object', additionalProperties: true } },
+                                            providerStatus: { type: 'object', additionalProperties: { type: 'boolean' } },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            '/premium/streams.json': {
+                get: {
+                    operationId: 'fetchPremiumStreams',
+                    summary: 'Fetch premium stream catalog',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Secret-free premium stream contracts with schemas, x402/pay.sh pricing, and provider readiness.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                    },
+                },
+            },
+            '/premium/webhooks.json': {
+                get: {
+                    operationId: 'fetchPremiumWebhooks',
+                    summary: 'Fetch premium webhook catalog',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Secret-free premium webhook contracts with signed delivery expectations, pricing, and provider readiness.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                    },
+                },
+            },
+            '/premium/health.json': {
+                get: {
+                    operationId: 'fetchPremiumHealth',
+                    summary: 'Fetch premium subsystem health and metrics',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Premium subsystem metrics: active/pending/blocked sessions, events delivered, revenue, active streams/webhooks, and provider health.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                    },
+                },
+            },
+            '/premium/activate': {
+                post: {
+                    operationId: 'activatePremiumSession',
+                    summary: 'Activate a premium session with a verified x402/pay.sh receipt',
+                    tags: ['Premium'],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['sessionId', 'paymentReceipt'],
+                                    properties: {
+                                        sessionId: { type: 'string' },
+                                        paymentReceipt: { type: 'string' },
+                                        payerAddress: { type: 'string' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Session activated successfully.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                        '400': { description: 'Missing required fields.' },
+                        '402': { description: 'Session not in pending_payment status.' },
+                    },
+                },
+            },
+            '/premium/stream/{sessionId}': {
+                get: {
+                    operationId: 'openPremiumStream',
+                    summary: 'Open an SSE stream for an active premium session',
+                    tags: ['Premium'],
+                    parameters: [
+                        { name: 'sessionId', in: 'path', required: true, schema: { type: 'string' } },
+                        { name: 'subscriptionKey', in: 'query', schema: { type: 'string' } },
+                        { name: 'since', in: 'query', schema: { type: 'string' } },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'SSE event stream. Each event is `event: <type>\\ndata: <json>\\n\\n`.',
+                            content: { 'text/event-stream': { schema: { type: 'string' } } },
+                        },
+                        '403': { description: 'Session not active.' },
+                        '406': { description: 'Accept: text/event-stream required.' },
+                    },
+                },
+            },
+            '/premium/webhook/register': {
+                post: {
+                    operationId: 'registerPremiumWebhook',
+                    summary: 'Register an HTTPS webhook target for signed premium event delivery',
+                    tags: ['Premium'],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['sessionId', 'targetUrl', 'events'],
+                                    properties: {
+                                        sessionId: { type: 'string' },
+                                        targetUrl: { type: 'string', format: 'uri' },
+                                        events: { type: 'array', items: { type: 'string' }, minItems: 1 },
+                                        signingPublicKey: { type: 'string' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '201': {
+                            description: 'Webhook subscription created. Delivery worker started in background.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                        '400': { description: 'Missing required fields.' },
+                        '402': { description: 'Session not active or URL invalid.' },
+                    },
+                },
+            },
+            '/premium/webhook/{subscriptionId}/status': {
+                get: {
+                    operationId: 'getPremiumWebhookStatus',
+                    summary: 'Check webhook subscription status and recent delivery records',
+                    tags: ['Premium'],
+                    parameters: [
+                        { name: 'subscriptionId', in: 'path', required: true, schema: { type: 'string' } },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Subscription status with recent delivery attempts.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                        '404': { description: 'Subscription not found.' },
+                    },
+                },
+            },
         },
     };
 }
@@ -1099,6 +1343,7 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
         title,
         installScriptCommand: 'curl -fsSL https://mcp.sap.oobeprotocol.ai/wizard/install.sh | sh',
         wizardCommand: WIZARD_NPM_COMMAND,
+        repairCommand: REPAIR_NPM_COMMAND,
         paidCallCommand: X402_PAID_CALL_NPX_COMMAND,
         paidCallAddonPath: X402_PAID_CALL_ADDON_PATH,
     });
@@ -1589,6 +1834,8 @@ export class RemoteMCPServer {
     httpTuning;
     sessionCleanupInterval;
     httpServer;
+    monetizationGate;
+    premiumMemoryManager;
     constructor(config) {
         this.appConfig = loadConfig();
         initLogger({
@@ -1611,7 +1858,21 @@ export class RemoteMCPServer {
         this.validateAuthConfig();
         await this.rateLimiter.initialize();
         this.startSessionCleanup();
-        const monetizationGate = await McpMonetizationGate.create(this.appConfig);
+        this.monetizationGate = await McpMonetizationGate.create(this.appConfig);
+        // Start premium memory background GC.
+        this.premiumMemoryManager = new PremiumMemoryManager();
+        this.premiumMemoryManager.start();
+        // Eagerly load and connect all configured premium provider adapters.
+        // This starts the polling loops (Pyth HTTP, DexScreener, DefiLlama, etc.)
+        // before the server accepts requests, so events are already flowing when
+        // the first agent session arrives. Failures are logged but non-fatal.
+        await preloadPremiumProviders();
+        // Initialize the local agent memory subsystem (SQLite FTS5).
+        // The database is created at ~/.config/sap-mcp/memory/agent-memory.db.
+        // If the DB cannot be opened, the subsystem enters degraded mode and
+        // all memory tools return empty results instead of crashing.
+        memoryDatabase.init();
+        asyncMemoryProcessor.start();
         this.httpServer = http.createServer(async (req, res) => {
             if (this.applyCors(req, res)) {
                 return;
@@ -1631,6 +1892,57 @@ export class RemoteMCPServer {
                 }, isHeadMethod(req.method));
                 return;
             }
+            if (isPublicReadMethod(req.method) && url.pathname === '/pricing.json') {
+                writeJson(res, 200, buildPricingCatalog(this.appConfig.monetization), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/catalog.json') {
+                writeJson(res, 200, buildPremiumDiscoveryDocument(req, this.config), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/streams.json') {
+                writeJson(res, 200, buildPremiumDiscoveryDocument(req, this.config, 'stream'), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/webhooks.json') {
+                writeJson(res, 200, buildPremiumDiscoveryDocument(req, this.config, 'webhook'), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/health.json') {
+                try {
+                    const metrics = await getPremiumMetrics();
+                    writeJson(res, 200, {
+                        version: '1.0.0',
+                        service: 'sap-mcp-server',
+                        serverVersion: MCP_SERVER_VERSION,
+                        timestamp: new Date().toISOString(),
+                        ...metrics,
+                    }, {
+                        'Cache-Control': 'public, max-age=15',
+                    }, isHeadMethod(req.method));
+                }
+                catch (error) {
+                    writeJson(res, 500, {
+                        error: 'premium_health_error',
+                        message: error instanceof Error ? error.message : 'Unknown error.',
+                    });
+                }
+                return;
+            }
+            // Premium delivery rail routes (activation, SSE stream, webhook register/status).
+            // These are not public read-only — they handle POST and GET with side effects.
+            const handledByPremiumRoute = await tryPremiumRoute(req, res);
+            if (handledByPremiumRoute) {
+                return;
+            }
             if (isPublicReadMethod(req.method) && url.pathname === '/smithery.config.schema.json') {
                 writeJson(res, 200, readSmitheryConfigSchema(), {
                     'Cache-Control': 'public, max-age=300',
@@ -1712,6 +2024,47 @@ export class RemoteMCPServer {
                 writeHtml(res, 200, buildLandingHtml(req, this.config, 'mcp'), isHeadMethod(req.method));
                 return;
             }
+            if (url.pathname === TX_SUBMIT_PATH) {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, {
+                        error: 'method_not_allowed',
+                        allowedMethods: ['POST'],
+                    }, {
+                        Allow: 'POST',
+                    });
+                    return;
+                }
+                const rateLimit = await this.rateLimiter.check(`${getRateLimitKey(req)}:tx-submit`);
+                res.setHeader('X-RateLimit-Limit', String(rateLimit.limit));
+                res.setHeader('X-RateLimit-Remaining', String(rateLimit.remaining));
+                res.setHeader('X-RateLimit-Reset', String(rateLimit.resetSeconds));
+                if (!rateLimit.allowed) {
+                    writeJson(res, 429, {
+                        error: 'rate_limited',
+                        retryAfterSeconds: rateLimit.resetSeconds,
+                    }, {
+                        'Retry-After': String(rateLimit.resetSeconds),
+                    });
+                    return;
+                }
+                try {
+                    const result = await submitSignedTransactionFromHttp(req, this.appConfig);
+                    writeJson(res, result.success ? 200 : 202, result, {
+                        'Cache-Control': 'no-store',
+                    });
+                }
+                catch (error) {
+                    writeJson(res, 400, {
+                        success: false,
+                        error: error instanceof Error ? error.message : 'transaction_submit_failed',
+                        retrySafe: false,
+                        agentInstruction: 'The hosted relay only submits already-signed Solana transactions. Sign locally with sap_payments_finalize_transaction first; never send keypair bytes or unsigned transactions to this endpoint.',
+                    }, {
+                        'Cache-Control': 'no-store',
+                    });
+                }
+                return;
+            }
             if (url.pathname !== '/mcp') {
                 writeJson(res, 404, { error: 'Not Found' });
                 return;
@@ -1780,8 +2133,8 @@ export class RemoteMCPServer {
                         sessionIdGenerator: undefined,
                     });
                     await perRequestServer.connect(perRequestTransport);
-                    if (monetizationGate) {
-                        await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                    if (this.monetizationGate) {
+                        await this.monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
                             // Extract tool names from parsed JSON-RPC body for logging
                             loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
                             loggedMethod = extractJsonRpcMethod(parsedBody);
@@ -1797,8 +2150,8 @@ export class RemoteMCPServer {
                 }
                 else {
                     // Stateful mode: route each request to the transport created by its initialize response.
-                    if (monetizationGate) {
-                        await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                    if (this.monetizationGate) {
+                        await this.monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
                             loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
                             loggedMethod = extractJsonRpcMethod(parsedBody);
                             await this.handleStatefulMcpRequest(mcpReq, mcpRes, parsedBody);
@@ -1888,7 +2241,15 @@ export class RemoteMCPServer {
                 resolve();
             }, 5_000);
         });
+        await this.monetizationGate?.close();
+        this.monetizationGate = undefined;
         await this.rateLimiter.close();
+        // Premium subsystem graceful shutdown: stop streams, webhooks, providers, clear stores.
+        await disconnectAllProviders();
+        asyncMemoryProcessor.stop();
+        memoryDatabase.close();
+        await this.premiumMemoryManager?.shutdown();
+        this.premiumMemoryManager = undefined;
     }
     /**
      * @name validateAuthConfig