@nitrostack/core 1.0.14 → 1.0.16

package/dist/core/server.js

@@ -13,6 +13,9 @@ import { buildController } from './builders.js';
 import { DIContainer } from './di/container.js';
 import { TaskManager, TaskContext, TaskNotFoundError, TaskAlreadyTerminalError, TaskAugmentationRequiredError, } from './task.js';
 import { triggerLifecycleHook } from './lifecycle.js';
+import { resolveProtocolEra, needsModernEngine, protocolVersionForEra, } from './protocol/version.js';
+import { isInputRequired } from './protocol/features/mrtr.js';
+import { extractBearerToken } from '../auth/token-validation.js';
 /** Optional Streamable HTTP session limits from environment variables. */
 function getStreamableHttpEnvOptions() {
     const maxSessions = process.env.MCP_MAX_SESSIONS
@@ -48,6 +51,8 @@ export class NitroStackServer {
     pendingComponentRegistrations = [];
     /** Transport type used by the server */
     _transportType;
+    /** Transport options configured during application creation */
+    _transportOptions;
     /** HTTP transport instance (when using http or dual mode) */
     _httpTransport;
     /** SDK legacy HTTP+SSE routes (GET /sse + POST /mcp/messages) attached once per Express app */
@@ -60,6 +65,13 @@ export class NitroStackServer {
     _shutdownSignalHandlers = [];
     /** Guards stop() so double signals / repeated calls don't re-run teardown */
     _stopping;
+    /**
+     * Resolved MCP protocol era. `legacy` (default) keeps the current 2025-era
+     * sessionful path unchanged; `modern` / `auto` engage the 2026-07-28 adapter.
+     */
+    protocolEra;
+    /** Lazily constructed modern (2026-07-28) adapter (only on modern/auto). */
+    modernAdapter;
     constructor(config) {
         // Default config if not provided (e.g., when instantiated by DI container)
         this.config = config || {
@@ -81,17 +93,74 @@ export class NitroStackServer {
         // Initialize task manager for MCP Tasks support
         this.taskManager = new TaskManager({
             logger: this.logger,
+            store: this.config.taskStore ?? this.config.tasks?.store,
+            defaultTtl: this.config.tasks?.defaultTtl,
+            defaultPollInterval: this.config.tasks?.defaultPollInterval,
             onStatusChange: (taskData) => {
                 // Send notifications/tasks/status when task status changes
                 this.sendTaskStatusNotification(taskData);
             },
         });
+        // Resolve the protocol era. Env NITRO_MCP_PROTOCOL_VERSION wins over the
+        // optional config.protocolVersion; unset ⇒ 'auto' (dual modern/legacy support).
+        this.protocolEra = resolveProtocolEra(this.config.protocolVersion);
+        if (this.protocolEra !== 'legacy') {
+            this.logger.info(`MCP protocol era: ${this.protocolEra} (${protocolVersionForEra(this.protocolEra)})`);
+        }
         this.mcpServer = new McpServer({
             name: this.config.name,
             version: this.config.version,
         }, NitroStackServer.mcpServerOptions);
         this.setupHandlersOn(this.mcpServer);
     }
+    /**
+     * Build the read-only registry view the modern protocol adapter consumes.
+     * Captures `this` so the adapter never imports NitroStack internals.
+     */
+    buildProtocolRegistry() {
+        return {
+            config: this.config,
+            logger: this.logger,
+            getTools: () => this.tools,
+            getResources: () => this.resources,
+            getResourceTemplates: () => this.resourceTemplates,
+            getTemplateResources: () => this.templateResources,
+            getPrompts: () => this.prompts,
+            getTaskManager: () => this.taskManager,
+            createExecutionContext: (options) => this.createContext(options),
+        };
+    }
+    /**
+     * Lazily create the modern (2026-07-28) protocol adapter. `auto` uses the v2
+     * stateless legacy fallback so a single endpoint serves both eras for
+     * validation; `modern` rejects legacy-classified traffic.
+     */
+    async getModernAdapter() {
+        if (!this.modernAdapter) {
+            const { ModernProtocolAdapter } = await import('./protocol/modern-v2.adapter.js');
+            this.modernAdapter = new ModernProtocolAdapter(this.buildProtocolRegistry(), {
+                legacyMode: this.protocolEra === 'auto' ? 'stateless' : 'reject',
+                taskManager: this.taskManager,
+            });
+        }
+        return this.modernAdapter;
+    }
+    /**
+     * Bind an HTTP transport's /mcp endpoint to the correct protocol engine:
+     * the modern stateless handler on modern/auto, or the legacy per-session
+     * SDK factory otherwise.
+     */
+    async configureTransportForProtocol(transport) {
+        if (needsModernEngine(this.protocolEra) && transport.setModernHandler) {
+            const adapter = await this.getModernAdapter();
+            const nodeHandler = await adapter.createNodeHandler();
+            transport.setModernHandler(nodeHandler);
+            transport.setProtocolVersionLabel?.(protocolVersionForEra(this.protocolEra));
+        }
+        else if (transport.setMcpServerFactory) {
+            transport.setMcpServerFactory((sessionContext) => this.createConfiguredMcpServer(sessionContext));
+        }
+    }
     /** Shared MCP server constructor options (main + per legacy SSE session) */
     static mcpServerOptions = {
         capabilities: {
@@ -120,24 +189,28 @@ export class NitroStackServer {
      * server instance (legacy SSE sessions, official Streamable HTTP sessions),
      * since a single SDK server can only be connected to one transport at a time.
      */
-    createConfiguredMcpServer() {
+    createConfiguredMcpServer(sessionContext) {
         const mcp = new McpServer({
             name: this.config.name,
             version: this.config.version,
         }, NitroStackServer.mcpServerOptions);
-        this.setupHandlersOn(mcp);
+        this.setupHandlersOn(mcp, sessionContext);
         return mcp;
     }
     /**
      * SDK-compatible legacy HTTP+SSE: GET /sse (SSEServerTransport) and POST /mcp/messages?sessionId=.
      * Streamable HTTP stays on GET/POST /mcp.
      */
-    async startLegacySdkSseSession(res, messagesPath) {
+    async startLegacySdkSseSession(res, messagesPath, authHeader) {
         try {
-            const sessionMcp = this.createConfiguredMcpServer();
+            const sessionContext = {};
+            if (authHeader) {
+                sessionContext.authHeader = authHeader;
+            }
+            const sessionMcp = this.createConfiguredMcpServer(sessionContext);
             const transport = new SSEServerTransport(messagesPath, res);
             const sessionId = transport.sessionId;
-            this.legacySdkSseSessions.set(sessionId, { server: sessionMcp, transport });
+            this.legacySdkSseSessions.set(sessionId, { server: sessionMcp, transport, sessionContext });
             let closing = false;
             transport.onclose = async () => {
                 if (closing) {
@@ -174,8 +247,8 @@ export class NitroStackServer {
         this._legacySseRoutesAttached = true;
         const LEGACY_SSE_PATH = '/sse';
         const LEGACY_MESSAGES_PATH = '/mcp/messages';
-        app.get(LEGACY_SSE_PATH, async (_req, res) => {
-            await this.startLegacySdkSseSession(res, LEGACY_MESSAGES_PATH);
+        app.get(LEGACY_SSE_PATH, async (req, res) => {
+            await this.startLegacySdkSseSession(res, LEGACY_MESSAGES_PATH, req.get('authorization'));
         });
         app.post(LEGACY_MESSAGES_PATH, async (req, res) => {
             const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId : undefined;
@@ -188,6 +261,10 @@ export class NitroStackServer {
                 res.status(404).send('Unknown session');
                 return;
             }
+            const authHeader = req.get('authorization');
+            if (authHeader) {
+                session.sessionContext.authHeader = authHeader;
+            }
             try {
                 await session.transport.handlePostMessage(req, res, req.body);
             }
@@ -244,37 +321,33 @@ export class NitroStackServer {
             mimeType: getWidgetMimeType(),
             handler: async (uri, context) => {
                 context.logger.info(`Serving component: ${uri}`);
-                // In production, serve the bundled HTML file if available
-                if (process.env.NODE_ENV === 'production' || process.env.NODE_ENV === 'prod') {
-                    try {
-                        // Check if we have a bundled file for this component
-                        // The component ID usually matches the widget output name
-                        const widgetId = component.id;
-                        // We need to find where the widgets are located relative to the running server
-                        // In production, we expect them in src/widgets/out or dist/widgets/out
-                        // Try to find the bundled file
-                        const fs = await import('fs');
-                        const path = await import('path');
-                        // Possible locations for bundled widgets
-                        const possiblePaths = [
-                            path.join(process.cwd(), 'src/widgets/out', `${widgetId}.html`),
-                            path.join(process.cwd(), 'dist/widgets/out', `${widgetId}.html`),
-                            path.join(process.cwd(), 'widgets/out', `${widgetId}.html`)
-                        ];
-                        for (const p of possiblePaths) {
-                            if (fs.existsSync(p)) {
-                                const html = fs.readFileSync(p, 'utf-8');
-                                return {
-                                    type: 'text',
-                                    data: html
-                                };
-                            }
+                // Serve the bundled HTML file if available
+                try {
+                    const widgetId = component.id;
+                    const cleanId = widgetId.replace(/^next-/, '');
+                    const fs = await import('fs');
+                    const path = await import('path');
+                    const possiblePaths = [
+                        path.join(process.cwd(), 'src/widgets/out', `${cleanId}.html`),
+                        path.join(process.cwd(), 'src/widgets/out', `${widgetId}.html`),
+                        path.join(process.cwd(), 'dist/widgets/out', `${cleanId}.html`),
+                        path.join(process.cwd(), 'dist/widgets/out', `${widgetId}.html`),
+                        path.join(process.cwd(), 'widgets/out', `${cleanId}.html`),
+                        path.join(process.cwd(), 'widgets/out', `${widgetId}.html`),
+                    ];
+                    for (const p of possiblePaths) {
+                        if (fs.existsSync(p)) {
+                            const html = fs.readFileSync(p, 'utf-8');
+                            return {
+                                type: 'text',
+                                data: html,
+                            };
                         }
-                        context.logger.warn(`Bundled widget not found for ${widgetId}, falling back to default bundle`);
-                    }
-                    catch (error) {
-                        context.logger.error(`Error serving bundled widget: ${error}`);
                     }
+                    context.logger.warn(`Bundled widget not found for ${widgetId} (${cleanId}), falling back to default bundle`);
+                }
+                catch (error) {
+                    context.logger.error(`Error serving bundled widget: ${error}`);
                 }
                 return {
                     type: 'text',
@@ -331,6 +404,7 @@ export class NitroStackServer {
      * Notify clients that the list of resources has changed
      */
     notifyResourcesListChanged() {
+        this.modernAdapter?.notifyResourcesListChanged();
         try {
             // Send notification through the MCP server
             const mcpServerWithNotification = this.mcpServer;
@@ -348,6 +422,7 @@ export class NitroStackServer {
      * Notify clients that the list of prompts has changed
      */
     notifyPromptsListChanged() {
+        this.modernAdapter?.notifyPromptsListChanged();
         try {
             const mcpServerWithNotification = this.mcpServer;
             if (mcpServerWithNotification.notification) {
@@ -364,6 +439,7 @@ export class NitroStackServer {
      * Notify clients that the list of tools has changed
      */
     notifyToolsListChanged() {
+        this.modernAdapter?.notifyToolsListChanged();
         try {
             const mcpServerWithNotification = this.mcpServer;
             if (mcpServerWithNotification.notification) {
@@ -380,6 +456,7 @@ export class NitroStackServer {
      * Notify subscribers that a resource has been updated
      */
     notifyResourceUpdated(uri) {
+        this.modernAdapter?.notifyResourceUpdated(uri);
         try {
             const resource = this.resources.get(uri);
             if (!resource || !resource.hasSubscribers())
@@ -477,17 +554,51 @@ export class NitroStackServer {
      * Create execution context
      */
     createContext(options) {
+        const metadata = options?.metadata || {};
+        let auth = options?.extra?.auth;
+        if (!auth) {
+            const authHeader = (metadata.authorization || metadata.Authorization);
+            const metaToken = (metadata._oauth || metadata.token || metadata.jwtToken || metadata._meta?.jwtToken || metadata._meta?.token);
+            const token = extractBearerToken(authHeader) || (typeof metaToken === 'string' ? extractBearerToken(metaToken) || metaToken : null);
+            if (token) {
+                let subject = 'authenticated-user';
+                let tokenPayload = undefined;
+                try {
+                    const parts = token.split('.');
+                    if (parts.length === 3) {
+                        tokenPayload = JSON.parse(Buffer.from(parts[1], 'base64').toString('utf8'));
+                        if (tokenPayload?.sub) {
+                            subject = tokenPayload.sub;
+                        }
+                    }
+                }
+                catch {
+                    // ignore parse errors
+                }
+                auth = {
+                    authenticated: true,
+                    subject,
+                    clientId: tokenPayload?.client_id || tokenPayload?.azp,
+                    scopes: typeof tokenPayload?.scope === 'string' ? tokenPayload.scope.split(' ') : [],
+                    tokenInfo: tokenPayload,
+                };
+            }
+        }
         return {
             logger: this.logger,
             requestId: uuidv4(),
             toolName: options?.toolName,
-            metadata: options?.metadata || {},
+            metadata,
+            auth,
+            // Additive 2026-07-28 fields (protocolVersion, requestState, inputResponses,
+            // trace, clientInfo, clientCapabilities, auth) supplied by the modern adapter.
+            ...(options?.extra || {}),
         };
     }
     /**
      * Register MCP protocol handlers on the given server instance (main or per legacy SSE session).
      */
-    setupHandlersOn(mcp) {
+    setupHandlersOn(mcp, sessionContext) {
         // List tools
         mcp.setRequestHandler(ListToolsRequestSchema, async () => {
             this.logger.debug('Listing tools');
@@ -521,25 +632,47 @@ export class NitroStackServer {
             if (!isTaskAugmented && tool.taskSupport === 'required') {
                 throw new TaskAugmentationRequiredError();
             }
-            // Extract _meta from args if present and add to context metadata
+            // Extract _meta from request params (MCP spec) and from arguments
+            // (legacy Studio clients); params._meta takes precedence.
             const argsRecord = (args || {});
-            const { _meta, ...toolArgs } = argsRecord;
+            const { _meta: metaFromArgs, ...toolArgs } = argsRecord;
+            const combinedMeta = {
+                ...metaFromArgs,
+                ...requestParams._meta,
+            };
+            // Bridge the transport-captured HTTP Authorization header so OAuth
+            // guards can authenticate remote HTTP/SSE clients. Explicit _meta wins.
+            const rawAuth = combinedMeta['authorization'] || combinedMeta['Authorization'] || sessionContext?.authHeader;
+            if (rawAuth) {
+                combinedMeta['authorization'] = rawAuth;
+                combinedMeta['Authorization'] = rawAuth;
+            }
+            const rawToken = combinedMeta['token'] || combinedMeta['_oauth'] || combinedMeta['jwtToken'] || combinedMeta['_meta']?.jwtToken || combinedMeta['_meta']?.token;
+            if (rawToken) {
+                combinedMeta['token'] = rawToken;
+                combinedMeta['_oauth'] = rawToken;
+            }
             const context = this.createContext({
-                metadata: _meta,
+                metadata: combinedMeta,
                 toolName: name
             });
             // ----------------------------------------------------------------
             // Task-augmented path: create task, run async, return immediately
             // ----------------------------------------------------------------
             if (isTaskAugmented) {
-                const taskData = this.taskManager.createTask(taskParam, name);
+                const accessContext = sessionContext ? {
+                    sessionId: sessionContext.sessionId,
+                    userId: sessionContext.userId,
+                    tenantId: sessionContext.tenantId,
+                } : undefined;
+                const taskData = this.taskManager.createTask(taskParam, name, accessContext);
                 const taskId = taskData.taskId;
                 // Attach a TaskContext to the execution context so handlers can
                 // report progress and check for cancellation
                 const taskContext = new TaskContext(this.taskManager, taskId);
                 context.task = taskContext;
                 // Execute the tool asynchronously (fire-and-forget)
-                this.runTaskAsync(tool, args, context, taskId, name);
+                this.runTaskAsync(tool, toolArgs, context, taskId, name);
                 // Return CreateTaskResult immediately
                 return {
                     task: taskData,
@@ -549,8 +682,22 @@ export class NitroStackServer {
             // Normal synchronous path
             // ----------------------------------------------------------------
             try {
-                // Pass original args (including _meta) to tool
-                const result = await tool.execute(args, context);
+                // Pass sanitized toolArgs to tool (protocol _meta is preserved in context.metadata)
+                const result = await tool.execute(toolArgs, context);
+                // MRTR (SEP-2322) is a 2026-07-28 feature. On the legacy path there is
+                // no client round-trip mechanism, so surface it as a clear error rather
+                // than leaking the marker's serialized shape.
+                if (isInputRequired(result)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'This tool requires multi-round-trip input (MCP 2026-07-28). Set NITRO_MCP_PROTOCOL_VERSION=2026-07-28 to enable it.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 this.stats.toolCalls++;
                 // Check if tool has a UI component
                 const response = {
@@ -619,7 +766,12 @@ export class NitroStackServer {
                 throw { code: -32602, message: 'Invalid params: taskId is required' };
             }
             try {
-                return this.taskManager.getTask(taskId);
+                const accessContext = sessionContext ? {
+                    sessionId: sessionContext.sessionId,
+                    userId: sessionContext.userId,
+                    tenantId: sessionContext.tenantId,
+                } : undefined;
+                return this.taskManager.getTask(taskId, accessContext);
             }
             catch (err) {
                 if (err instanceof TaskNotFoundError) {
@@ -639,7 +791,12 @@ export class NitroStackServer {
                 throw { code: -32602, message: 'Invalid params: taskId is required' };
             }
             try {
-                const { result, error } = await this.taskManager.getResult(taskId);
+                const accessContext = sessionContext ? {
+                    sessionId: sessionContext.sessionId,
+                    userId: sessionContext.userId,
+                    tenantId: sessionContext.tenantId,
+                } : undefined;
+                const { result, error } = await this.taskManager.getResult(taskId, accessContext);
                 if (error) {
                     // Re-throw the original error so the client gets the JSON-RPC error
                     throw error;
@@ -670,9 +827,14 @@ export class NitroStackServer {
         // Lists tasks with cursor-based pagination.
         // ----------------------------------------------------------------
         this.registerCustomHandler(mcp, 'tasks/list', async (params) => {
-            const { cursor } = (params || {});
+            const { cursor, limit } = (params || {});
             try {
-                return this.taskManager.listTasks(cursor);
+                const accessContext = sessionContext ? {
+                    sessionId: sessionContext.sessionId,
+                    userId: sessionContext.userId,
+                    tenantId: sessionContext.tenantId,
+                } : undefined;
+                return this.taskManager.listTasks(cursor, limit ?? 50, accessContext);
             }
             catch (err) {
                 if (err instanceof TaskNotFoundError) {
@@ -692,7 +854,12 @@ export class NitroStackServer {
                 throw { code: -32602, message: 'Invalid params: taskId is required' };
             }
             try {
-                return this.taskManager.cancelTask(taskId);
+                const accessContext = sessionContext ? {
+                    sessionId: sessionContext.sessionId,
+                    userId: sessionContext.userId,
+                    tenantId: sessionContext.tenantId,
+                } : undefined;
+                return this.taskManager.cancelTask(taskId, accessContext);
             }
             catch (err) {
                 if (err instanceof TaskNotFoundError) {
@@ -868,15 +1035,24 @@ export class NitroStackServer {
      * - NODE_ENV=development or unset → stdio mode
      * - NODE_ENV=production → dual mode (STDIO + HTTP)
      */
-    async start() {
+    /**
+     * Start the server.
+     *
+     * Transport determination precedence:
+     * 1. Explicit `options.transport` passed to `start({ transport: 'stdio' })`
+     * 2. `MCP_TRANSPORT_TYPE` environment variable
+     * 3. Configured `this._transportType` (from `@McpApp` / `McpApplicationFactory`)
+     * 4. Default: `NODE_ENV=development` or unset → 'stdio', `production` → 'dual'
+     */
+    async start(options) {
         // Check for explicit transport type override
-        const explicitTransport = process.env.MCP_TRANSPORT_TYPE;
+        const explicitTransport = options?.transport || process.env.MCP_TRANSPORT_TYPE;
         // Determine if we're in development mode
         // On Windows, NODE_ENV might not be passed correctly, so we're more lenient
         const nodeEnv = process.env.NODE_ENV?.toLowerCase();
         const isDevelopment = nodeEnv === 'development' || nodeEnv === 'dev' || !nodeEnv;
-        // Use explicit transport if set, otherwise infer from NODE_ENV
-        const transportType = explicitTransport || (isDevelopment ? 'stdio' : 'dual');
+        // Use explicit transport if set, otherwise check configured instance transport, then fallback based on NODE_ENV
+        const transportType = explicitTransport || this._transportType || (isDevelopment ? 'stdio' : 'dual');
         this._transportType = transportType;
         this.logger.debug(`NitroStackServer.start(): NODE_ENV=${process.env.NODE_ENV}, MCP_TRANSPORT_TYPE=${explicitTransport}, transportType=${transportType}`);
         // Resolve all modules so they (and their dependencies) are initialized in the DI container
@@ -889,24 +1065,26 @@ export class NitroStackServer {
         // Call onModuleInit for currently resolved instances (NestJS: after DI resolution)
         const initializedInstances = new Set(DIContainer.getInstance().getInstances());
         await triggerLifecycleHook([...initializedInstances], 'onModuleInit');
+        // Resolve port/host/endpoint/cors
+        const port = options?.port ?? (this._transportOptions?.port !== undefined ? this._transportOptions.port : parseInt(process.env.PORT || '3000'));
+        const host = options?.host || this._transportOptions?.host || process.env.HOST || 'localhost';
+        const endpoint = options?.endpoint || this._transportOptions?.endpoint || '/mcp';
+        const enableCors = options?.enableCors ?? (this._transportOptions?.enableCors !== undefined ? this._transportOptions.enableCors : process.env.ENABLE_CORS !== 'false');
         // If HTTP transport is needed (dual or http mode), set it up BEFORE calling module.start()
         // This allows modules like OAuthModule to register endpoints/middleware on the HTTP server
         if (transportType === 'dual' || transportType === 'http') {
-            const port = parseInt(process.env.PORT || '3000');
-            const host = process.env.HOST || 'localhost';
             // Create HTTP transport first (do not start listening yet)
             const { StreamableHttpTransport } = await import('./transports/streamable-http.js');
             const httpTransport = new StreamableHttpTransport({
-                port: port,
-                host: host,
-                endpoint: '/mcp',
+                port,
+                host,
+                endpoint,
                 enableSessions: transportType === 'http', // Sessions ONLY in pure http mode
-                enableCors: process.env.ENABLE_CORS !== 'false',
+                enableCors,
                 ...getStreamableHttpEnvOptions(),
             });
-            // Delegate /mcp protocol handling to the official SDK transport: each
-            // session gets its own configured MCP server built via this factory.
-            httpTransport.setMcpServerFactory(() => this.createConfiguredMcpServer());
+            // Delegate /mcp protocol handling to the correct protocol engine.
+            await this.configureTransportForProtocol(httpTransport);
             // Set up tools callback and server config for documentation page
             httpTransport.setToolsCallback(async () => {
                 const tools = await Promise.all(Array.from(this.tools.values()).map((tool) => tool.toMcpTool()));
@@ -943,13 +1121,11 @@ export class NitroStackServer {
             await this._httpTransport.start();
         }
         // Now complete the transport setup (connect MCP server) using the determined transportType
-        const port = parseInt(process.env.PORT || '3000');
-        const host = process.env.HOST || 'localhost';
         await this.startWithTransport(transportType, {
             port,
             host,
-            endpoint: '/mcp',
-            enableCors: process.env.ENABLE_CORS !== 'false',
+            endpoint,
+            enableCors,
         });
     }
     /**
@@ -985,15 +1161,20 @@ export class NitroStackServer {
                         enableCors: transportOptions?.enableCors !== false, // Enable CORS by default for web clients
                         ...getStreamableHttpEnvOptions(),
                     });
-                    transport.setMcpServerFactory(() => this.createConfiguredMcpServer());
+                    await this.configureTransportForProtocol(transport);
                     this.attachLegacySdkSseIfNeeded(transport);
                     await transport.start();
                     httpTransport = transport;
                     this._httpTransport = httpTransport;
                 }
                 // 2. Connect the primary MCP server via STDIO for direct connections.
-                const stdioTransport = new StdioServerTransport();
-                await this.mcpServer.connect(stdioTransport);
+                if (needsModernEngine(this.protocolEra)) {
+                    await (await this.getModernAdapter()).serveStdio();
+                }
+                else {
+                    const stdioTransport = new StdioServerTransport();
+                    await this.mcpServer.connect(stdioTransport);
+                }
                 this.logger.info(`${this.config.name} started successfully (DUAL MODE)`);
                 this.logger.info(`✨ Mode: ${getAppMode().toUpperCase()} (via NITROSTACK_APP_MODE)`);
                 this.logger.info(`📡 STDIO: Ready for direct MCP connections`);
@@ -1013,8 +1194,8 @@ export class NitroStackServer {
                         enableCors: transportOptions?.enableCors || false,
                         ...getStreamableHttpEnvOptions(),
                     });
-                    // Delegate /mcp protocol handling to the official SDK transport.
-                    transport.setMcpServerFactory(() => this.createConfiguredMcpServer());
+                    // Delegate /mcp protocol handling to the correct protocol engine.
+                    await this.configureTransportForProtocol(transport);
                     // Set up tools callback and server config for documentation page
                     transport.setToolsCallback(async () => {
                         const tools = await Promise.all(Array.from(this.tools.values()).map((tool) => tool.toMcpTool()));
@@ -1040,8 +1221,13 @@ export class NitroStackServer {
             }
             else {
                 // STDIO-only transport (default)
-                const transport = new StdioServerTransport();
-                await this.mcpServer.connect(transport);
+                if (needsModernEngine(this.protocolEra)) {
+                    await (await this.getModernAdapter()).serveStdio();
+                }
+                else {
+                    const transport = new StdioServerTransport();
+                    await this.mcpServer.connect(transport);
+                }
                 this.logger.info(`${this.config.name} started successfully (STDIO transport)`);
                 this.logger.info(`✨ Mode: ${getAppMode().toUpperCase()} (via NITROSTACK_APP_MODE)`);
             }
@@ -1059,7 +1245,9 @@ export class NitroStackServer {
      */
     async runTaskAsync(tool, args, context, taskId, toolName) {
         try {
-            const result = await tool.execute(args, context);
+            const argsRecord = (args || {});
+            const { _meta: _, ...toolArgs } = argsRecord;
+            const result = await tool.execute(toolArgs, context);
             this.stats.toolCalls++;
             const response = {
                 content: [
@@ -1091,23 +1279,25 @@ export class NitroStackServer {
                     }
                 }
             }
-            this.taskManager.completeTask(taskId, response);
+            if (this.taskManager.hasTask(taskId)) {
+                this.taskManager.completeTask(taskId, response);
+            }
         }
         catch (error) {
             this.stats.errors++;
             const errorMessage = error instanceof Error ? error.message : String(error);
             context.logger.error(`Task tool execution failed: ${toolName}`, { error: errorMessage, taskId });
-            // Check if due to cancellation
-            const taskData = this.taskManager.hasTask(taskId)
-                ? this.taskManager.getTask(taskId)
-                : null;
-            if (taskData?.status === 'cancelled') {
-                return; // Already cancelled — don't overwrite status
+            // Check if task exists and is not cancelled
+            if (this.taskManager.hasTask(taskId)) {
+                const taskData = this.taskManager.getTask(taskId);
+                if (taskData?.status === 'cancelled') {
+                    return; // Already cancelled — don't overwrite status
+                }
+                const formattedError = error instanceof ValidationError || error instanceof ToolExecutionError
+                    ? error
+                    : new ToolExecutionError(toolName, error);
+                this.taskManager.failTask(taskId, { code: -32603, message: formattedError.message }, formattedError.message);
             }
-            const formattedError = error instanceof ValidationError || error instanceof ToolExecutionError
-                ? error
-                : new ToolExecutionError(toolName, error);
-            this.taskManager.failTask(taskId, { code: -32603, message: formattedError.message }, formattedError.message);
         }
     }
     /**
@@ -1132,14 +1322,39 @@ export class NitroStackServer {
      */
     sendTaskStatusNotification(taskData) {
         try {
+            // 1. If task is bound to a legacy SSE session, deliver notification to that session's McpServer
+            if (taskData.sessionId && this.legacySdkSseSessions.has(taskData.sessionId)) {
+                const session = this.legacySdkSseSessions.get(taskData.sessionId);
+                const sessionMcp = session?.server;
+                if (sessionMcp?.notification) {
+                    sessionMcp.notification({
+                        method: 'notifications/tasks/status',
+                        params: taskData,
+                    }).catch((err) => this.logger.debug('Failed to send task status notification to session SSE', {
+                        sessionId: taskData.sessionId,
+                        error: err instanceof Error ? err.message : String(err),
+                    }));
+                    return;
+                }
+            }
+            // 2. If modern protocol adapter is running, notify via modern adapter
+            if (this.modernAdapter) {
+                this.modernAdapter.notifyTaskStatus?.(taskData);
+                return;
+            }
+            // 3. Fallback to global mcpServer (used by STDIO transport)
             const mcpServerWithNotification = this.mcpServer;
-            if (mcpServerWithNotification.notification) {
+            if (mcpServerWithNotification?.notification) {
                 mcpServerWithNotification.notification({
                     method: 'notifications/tasks/status',
                     params: taskData,
-                }).catch(err => this.logger.error('Failed to send task status notification', {
-                    error: err instanceof Error ? err.message : String(err),
-                }));
+                }).catch((err) => {
+                    // In stateless HTTP mode, global mcpServer is not connected to a single persistent client
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    if (!errMsg.includes('Not connected')) {
+                        this.logger.error('Failed to send task status notification', { error: errMsg });
+                    }
+                });
             }
         }
         catch (error) {
@@ -1153,6 +1368,22 @@ export class NitroStackServer {
     getTaskManager() {
         return this.taskManager;
     }
+    /**
+     * Configure a custom TaskStore (e.g., Redis, SQL, DynamoDB) for distributed task state
+     */
+    setTaskStore(store) {
+        this.taskManager.destroy();
+        this.taskManager = new TaskManager({
+            logger: this.logger,
+            store,
+            defaultTtl: this.config.tasks?.defaultTtl,
+            defaultPollInterval: this.config.tasks?.defaultPollInterval,
+            onStatusChange: (taskData) => {
+                this.sendTaskStatusNotification(taskData);
+            },
+        });
+        return this;
+    }
     /**
      * Register OS signal handlers so the server shuts down gracefully, running the
      * NestJS-style shutdown lifecycle hooks (beforeApplicationShutdown /
@@ -1228,6 +1459,11 @@ export class NitroStackServer {
             }
             // Destroy task manager (stops cleanup interval)
             this.taskManager.destroy();
+            // Close the modern protocol adapter (aborts in-flight modern exchanges).
+            if (this.modernAdapter) {
+                await this.modernAdapter.close();
+                this.modernAdapter = undefined;
+            }
             for (const { server: sessionMcp, transport: legacyTransport } of this.legacySdkSseSessions.values()) {
                 try {
                     await legacyTransport.close();