@nitrostack/core 1.0.11 → 1.0.13

package/dist/core/prompt.js

@@ -2,6 +2,32 @@ import { ValidationError } from './errors.js';
 /**
  * Prompt class provides a clean abstraction for defining and executing prompts
  */
+// Enforces the PromptMessage contract (see types.ts): role in
+// user|assistant|system and string content. Structured content blocks are not
+// supported here by design; supporting them requires changing the PromptMessage
+// type and the server-side MCP mapping together.
+function validateMessageFormat(msg) {
+    if (!msg || typeof msg !== 'object') {
+        throw new ValidationError('Invalid prompt message format: message must be an object');
+    }
+    if (!msg.role || !['user', 'assistant', 'system'].includes(msg.role)) {
+        throw new ValidationError(`Invalid prompt message role: '${msg.role}'. Must be 'user', 'assistant', or 'system'`);
+    }
+    if (typeof msg.content !== 'string') {
+        throw new ValidationError('Invalid prompt message content: content must be a string');
+    }
+    return {
+        role: msg.role,
+        content: msg.content,
+    };
+}
+function normalizePromptResponse(result) {
+    if (result === null || result === undefined) {
+        return [];
+    }
+    const arrayResult = Array.isArray(result) ? result : [result];
+    return arrayResult.map(validateMessageFormat);
+}
 export class Prompt {
     definition;
     constructor(definition) {
@@ -39,7 +65,8 @@ export class Prompt {
         this.validateArguments(args);
         context.logger.info(`Executing prompt: ${this.name}`, { args: args });
         try {
-            const messages = await this.definition.handler(args, context);
+            const messagesResult = await this.definition.handler(args, context);
+            const messages = normalizePromptResponse(messagesResult);
             context.logger.info(`Prompt executed successfully: ${this.name}`, {
                 messageCount: messages.length,
             });

package/dist/core/prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAY9C;;GAEG;AACH,MAAM,OAAO,MAAM;IACT,UAAU,CAAmB;IAErC,YAAY,UAA4B;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,IAAyC,EAAE,OAAyB;QAChF,8BAA8B;QAC9B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAE7B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAA6B,EAAE,CAAC,CAAC;QAE/F,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAE9D,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,IAAI,CAAC,IAAI,EAAE,EAAE;gBAChE,YAAY,EAAE,QAAQ,CAAC,MAAM;aAC9B,CAAC,CAAC;YAEH,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAChI,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,IAAyC;QACjE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS;YAAE,OAAO;QAEvC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YAC5C,IAAI,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACxC,MAAM,IAAI,eAAe,CACvB,8BAA8B,GAAG,CAAC,IAAI,iBAAiB,IAAI,CAAC,IAAI,GAAG,CACpE,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW;QACT,MAAM,MAAM,GAAc;YACxB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QAEF,IAAI,IAAI,CAAC,KAAK;YAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAE1C,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,UAA4B;IACvD,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"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"}

package/dist/core/server.d.ts

@@ -1,4 +1,5 @@
-import type { Express } from 'express';
+import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Express, Response } from 'express';
 import { Tool } from './tool.js';
 import { Resource, ResourceTemplate } from './resource.js';
 import { Prompt } from './prompt.js';
@@ -10,8 +11,9 @@ import { TaskManager } from './task.js';
 interface HttpTransport {
     start(): Promise<void>;
     close(): Promise<void>;
-    send(message: JsonRpcResponse): Promise<void>;
-    onmessage?: (message: JsonRpcRequest) => Promise<void>;
+    /** Provide the factory used to build a configured MCP server per /mcp session. */
+    setMcpServerFactory?(factory: () => McpServer): void;
+    setLegacySseHandler?(handler: (req: unknown, res: Response) => Promise<void>): void;
     setToolsCallback?(callback: () => Promise<unknown[]>): void;
     setServerConfig?(config: {
         name: string;
@@ -21,28 +23,6 @@ interface HttpTransport {
     /** StreamableHttpTransport exposes the Express app for extra routes (legacy SDK SSE). */
     getApp?(): Express;
 }
-/**
- * JSON-RPC request structure
- */
-interface JsonRpcRequest {
-    jsonrpc: '2.0';
-    id?: string | number | null;
-    method?: string;
-    params?: Record<string, unknown>;
-}
-/**
- * JSON-RPC response structure
- */
-interface JsonRpcResponse {
-    jsonrpc: '2.0';
-    id: string | number | null;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-        data?: unknown;
-    };
-}
 /**
  * NitroStackServer - Main server class
  */
@@ -68,13 +48,25 @@ export declare class NitroStackServer {
     private readonly legacySdkSseSessions;
     /** Task manager for MCP Tasks support */
     private taskManager;
+    /** Registered OS signal handlers for graceful shutdown (see enableShutdownHooks) */
+    private _shutdownSignalHandlers;
+    /** Guards stop() so double signals / repeated calls don't re-run teardown */
+    private _stopping?;
     constructor(config?: McpServerConfig);
     /** Shared MCP server constructor options (main + per legacy SSE session) */
     private static readonly mcpServerOptions;
+    /**
+     * Build a fresh MCP server instance wired with all of this application's
+     * tool/resource/prompt handlers. Used for transports that require their own
+     * 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(): McpServer;
     /**
      * SDK-compatible legacy HTTP+SSE: GET /sse (SSEServerTransport) and POST /mcp/messages?sessionId=.
      * Streamable HTTP stays on GET/POST /mcp.
      */
+    private startLegacySdkSseSession;
     private attachLegacySdkSseRoutes;
     private attachLegacySdkSseIfNeeded;
     /**
@@ -174,10 +166,31 @@ export declare class NitroStackServer {
      * Get the TaskManager instance (useful for advanced use cases)
      */
     getTaskManager(): TaskManager;
+    /**
+     * Register OS signal handlers so the server shuts down gracefully, running the
+     * NestJS-style shutdown lifecycle hooks (beforeApplicationShutdown /
+     * onApplicationShutdown) with the received signal.
+     *
+     * Opt-in (like NestJS `enableShutdownHooks`) to avoid attaching process
+     * listeners for consumers that manage their own shutdown. Safe to call more
+     * than once; handlers are only attached once per signal.
+     *
+     * @param signals - Signals to listen for (default: SIGTERM, SIGINT)
+     */
+    enableShutdownHooks(signals?: NodeJS.Signals[]): this;
+    /**
+     * Remove any process signal handlers registered via enableShutdownHooks().
+     */
+    private removeShutdownHooks;
     /**
      * Stop the server
+     *
+     * Idempotent: concurrent or repeated calls (e.g. from multiple OS signals)
+     * share the same in-flight teardown instead of re-running lifecycle hooks or
+     * double-closing transports.
      */
-    stop(): Promise<void>;
+    stop(signal?: string): Promise<void>;
+    private doStop;
     /**
      * Get the HTTP transport (for modules that need to register endpoints)
      */

package/dist/core/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/core/server.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAavC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAkB,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACL,eAAe,EAGf,WAAW,EAEX,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AASpB,OAAO,EACL,WAAW,EAOZ,MAAM,WAAW,CAAC;AAkBnB;;GAEG;AACH,UAAU,aAAa;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,gBAAgB,CAAC,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5D,eAAe,CAAC,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxF,yFAAyF;IACzF,MAAM,CAAC,IAAI,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,UAAU,cAAc;IACtB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,UAAU,eAAe;IACvB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,iBAAiB,CAA4C;IACrE,OAAO,CAAC,iBAAiB,CAAoC;IAC7D,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAKX;IACF,OAAO,CAAC,6BAA6B,CAAuB;IAE5D,wCAAwC;IACxC,OAAO,CAAC,cAAc,CAAC,CAA4B;IAEnD,6DAA6D;IAC7D,OAAO,CAAC,cAAc,CAAC,CAAgB;IAEvC,+FAA+F;IAC/F,OAAO,CAAC,wBAAwB,CAAS;IAEzC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGjC;IAEJ,yCAAyC;IACzC,OAAO,CAAC,WAAW,CAAc;gBAErB,MAAM,CAAC,EAAE,eAAe;IAkCpC,4EAA4E;IAC5E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAoBtC;IAEF;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAkFhC,OAAO,CAAC,0BAA0B;IAMlC;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAkBtB;;OAEG;YACW,yBAAyB;IAiEvC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAqBlC;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM5B;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAMlD;;OAEG;IACH,0BAA0B,IAAI,IAAI;IAgBlC;;OAEG;IACH,wBAAwB,IAAI,IAAI;IAehC;;OAEG;IACH,sBAAsB,IAAI,IAAI;IAe9B;;OAEG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAoBxC;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAW,EAAE,gBAAgB,GAAG,IAAI;IAiD3C;;OAEG;IACH,QAAQ,IAAI,WAAW;IAIvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,eAAe;IA8bvB;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiF5B;;;;OAIG;YACW,kBAAkB;IAyIhC;;;;OAIG;YACW,YAAY;IA+E1B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAkB7B,iFAAiF;IACjF,OAAO,CAAC,eAAe,CAAiF;IAExG;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAqBlC;;OAEG;IACH,cAAc,IAAI,WAAW;IAI7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C3B;;OAEG;IACH,gBAAgB,IAAI,aAAa,GAAG,SAAS;CAG9C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAEtE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/core/server.ts"],"names":[],"mappings":"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"}

package/dist/core/server.js

@@ -12,6 +12,20 @@ import { isModule, getModuleMetadata } from './module.js';
 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';
+/** Optional Streamable HTTP session limits from environment variables. */
+function getStreamableHttpEnvOptions() {
+    const maxSessions = process.env.MCP_MAX_SESSIONS
+        ? parseInt(process.env.MCP_MAX_SESSIONS, 10)
+        : undefined;
+    const sessionTimeout = process.env.MCP_SESSION_TIMEOUT_MS
+        ? parseInt(process.env.MCP_SESSION_TIMEOUT_MS, 10)
+        : undefined;
+    return {
+        ...(maxSessions !== undefined && !Number.isNaN(maxSessions) ? { maxSessions } : {}),
+        ...(sessionTimeout !== undefined && !Number.isNaN(sessionTimeout) ? { sessionTimeout } : {}),
+    };
+}
 /**
  * NitroStackServer - Main server class
  */
@@ -42,12 +56,22 @@ export class NitroStackServer {
     legacySdkSseSessions = new Map();
     /** Task manager for MCP Tasks support */
     taskManager;
+    /** Registered OS signal handlers for graceful shutdown (see enableShutdownHooks) */
+    _shutdownSignalHandlers = [];
+    /** Guards stop() so double signals / repeated calls don't re-run teardown */
+    _stopping;
     constructor(config) {
         // Default config if not provided (e.g., when instantiated by DI container)
         this.config = config || {
             name: 'nitrostack-server',
             version: '1.0.0',
         };
+        // Register itself in DI container so modules can inject the server.
+        // NOTE: DIContainer is a process-wide singleton, so this assumes a single
+        // NitroStackServer instance per process. Multiple instances would overwrite
+        // each other's registration here.
+        DIContainer.getInstance().registerValue(NitroStackServer, this);
+        DIContainer.getInstance().registerValue('NitroStackServer', this);
         this.logger = createLogger({
             level: this.config.logging?.level || 'info',
             file: this.config.logging?.file,
@@ -90,10 +114,59 @@ export class NitroStackServer {
             },
         },
     };
+    /**
+     * Build a fresh MCP server instance wired with all of this application's
+     * tool/resource/prompt handlers. Used for transports that require their own
+     * 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() {
+        const mcp = new McpServer({
+            name: this.config.name,
+            version: this.config.version,
+        }, NitroStackServer.mcpServerOptions);
+        this.setupHandlersOn(mcp);
+        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) {
+        try {
+            const sessionMcp = this.createConfiguredMcpServer();
+            const transport = new SSEServerTransport(messagesPath, res);
+            const sessionId = transport.sessionId;
+            this.legacySdkSseSessions.set(sessionId, { server: sessionMcp, transport });
+            let closing = false;
+            transport.onclose = async () => {
+                if (closing) {
+                    return;
+                }
+                closing = true;
+                this.legacySdkSseSessions.delete(sessionId);
+                try {
+                    await sessionMcp.close();
+                }
+                catch {
+                    // ignore
+                }
+            };
+            transport.onerror = (err) => {
+                this.logger.error('Legacy SDK SSE transport error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            };
+            await sessionMcp.connect(transport);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to start legacy SDK SSE session', { error: message });
+            if (!res.headersSent) {
+                res.status(500).end('Failed to establish SSE connection');
+            }
+        }
+    }
     attachLegacySdkSseRoutes(app) {
         if (this._legacySseRoutesAttached) {
             return;
@@ -101,44 +174,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) => {
-            try {
-                const sessionMcp = new McpServer({
-                    name: this.config.name,
-                    version: this.config.version,
-                }, NitroStackServer.mcpServerOptions);
-                this.setupHandlersOn(sessionMcp);
-                const transport = new SSEServerTransport(LEGACY_MESSAGES_PATH, res);
-                const sessionId = transport.sessionId;
-                this.legacySdkSseSessions.set(sessionId, { server: sessionMcp, transport });
-                let closing = false;
-                transport.onclose = async () => {
-                    if (closing) {
-                        return;
-                    }
-                    closing = true;
-                    this.legacySdkSseSessions.delete(sessionId);
-                    try {
-                        await sessionMcp.close();
-                    }
-                    catch {
-                        // ignore
-                    }
-                };
-                transport.onerror = (err) => {
-                    this.logger.error('Legacy SDK SSE transport error', {
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                };
-                await sessionMcp.connect(transport);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                this.logger.error('Failed to start legacy SDK SSE session', { error: message });
-                if (!res.headersSent) {
-                    res.status(500).end('Failed to establish SSE connection');
-                }
-            }
+        app.get(LEGACY_SSE_PATH, async (_req, res) => {
+            await this.startLegacySdkSseSession(res, LEGACY_MESSAGES_PATH);
         });
         app.post(LEGACY_MESSAGES_PATH, async (req, res) => {
             const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId : undefined;
@@ -168,6 +205,12 @@ export class NitroStackServer {
         if (typeof transport.getApp === 'function') {
             this.attachLegacySdkSseRoutes(transport.getApp());
         }
+        // Cursor opens GET /mcp without mcp-session-id; fall back to legacy SSE on that path.
+        if (typeof transport.setLegacySseHandler === 'function') {
+            transport.setLegacySseHandler(async (_req, res) => {
+                await this.startLegacySdkSseSession(res, '/mcp/messages');
+            });
+        }
     }
     /**
      * Add a tool to the server
@@ -376,10 +419,32 @@ export class NitroStackServer {
             throw new Error(`Failed to get metadata for module ${moduleClass.name}`);
         }
         this.logger.info(`Registering module: ${metadata.name}`);
+        // Register providers in DI so declared-but-uninjected providers are still
+        // instantiated during start() (via instantiateAll) and run lifecycle hooks,
+        // matching the McpApplicationFactory path.
+        const providers = metadata.providers || [];
+        for (const provider of providers) {
+            if (typeof provider === 'function') {
+                DIContainer.getInstance().register(provider);
+            }
+            else if (provider && typeof provider === 'object' && 'provide' in provider) {
+                const token = provider.provide;
+                if (provider.useValue !== undefined) {
+                    DIContainer.getInstance().registerValue(token, provider.useValue);
+                }
+                else if (provider.useClass) {
+                    DIContainer.getInstance().register(token, provider.useClass);
+                }
+            }
+        }
         // Process all controllers in the module
         const controllers = metadata.controllers || [];
         for (const controller of controllers) {
             this.logger.info(`  Processing controller: ${controller.name}`);
+            // Register the controller in DI so it is instantiated during start()
+            // (via instantiateAll) and participates in lifecycle hooks, matching the
+            // McpApplicationFactory path.
+            DIContainer.getInstance().register(controller);
             // Build all tools, resources, and prompts from controller
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const { tools, resources, prompts } = buildController(controller);
@@ -702,7 +767,7 @@ export class NitroStackServer {
                             text: JSON.stringify(content, null, 2),
                         };
                 }
-                const contentsMeta = buildResourceReadContentsMeta(resource.getWidgetReadMeta());
+                const contentsMeta = buildResourceReadContentsMeta(resource.getWidgetReadMeta?.());
                 if (contentsMeta) {
                     responseContent._meta = contentsMeta;
                 }
@@ -814,27 +879,34 @@ export class NitroStackServer {
         const transportType = explicitTransport || (isDevelopment ? 'stdio' : 'dual');
         this._transportType = transportType;
         this.logger.debug(`NitroStackServer.start(): NODE_ENV=${process.env.NODE_ENV}, MCP_TRANSPORT_TYPE=${explicitTransport}, transportType=${transportType}`);
-        // Call onModuleInit for all modules
+        // Resolve all modules so they (and their dependencies) are initialized in the DI container
         for (const moduleClass of this.modules) {
-            const moduleInstance = DIContainer.getInstance().resolve(moduleClass);
-            if (moduleInstance.onModuleInit) {
-                await moduleInstance.onModuleInit();
-            }
+            DIContainer.getInstance().resolve(moduleClass);
         }
-        // If HTTP transport is needed (dual mode), set it up BEFORE calling module.start()
-        // This allows modules like OAuthModule to register endpoints on the HTTP server
-        if (transportType === 'dual') {
+        // Eagerly instantiate all registered providers/controllers so their lifecycle
+        // hooks fire even when they aren't injected anywhere (NestJS-style singletons).
+        DIContainer.getInstance().instantiateAll(this.logger);
+        // Call onModuleInit for currently resolved instances (NestJS: after DI resolution)
+        const initializedInstances = new Set(DIContainer.getInstance().getInstances());
+        await triggerLifecycleHook([...initializedInstances], 'onModuleInit');
+        // 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 and start HTTP transport first
+            // 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',
-                enableSessions: false, // Disable sessions for dual mode
+                enableSessions: transportType === 'http', // Sessions ONLY in pure http mode
                 enableCors: process.env.ENABLE_CORS !== 'false',
+                ...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());
             // 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()));
@@ -845,13 +917,11 @@ export class NitroStackServer {
                 version: this.config.version,
                 description: this.config.description,
             });
-            this.attachLegacySdkSseIfNeeded(httpTransport);
-            await httpTransport.start();
             // Store HTTP transport reference BEFORE modules start
-            // This allows OAuthModule to register discovery endpoints
+            // This allows OAuthModule to register discovery endpoints and middleware
             this._httpTransport = httpTransport;
         }
-        // Call start for all modules (e.g., OAuthModule to register discovery endpoints)
+        // Call start for all modules (e.g., OAuthModule to register discovery endpoints and middleware)
         // Now _httpTransport is available for OAuthModule to use
         for (const moduleClass of this.modules) {
             const moduleInstance = DIContainer.getInstance().resolve(moduleClass);
@@ -859,7 +929,20 @@ export class NitroStackServer {
                 await moduleInstance.start();
             }
         }
-        // Now complete the transport setup using the determined transportType
+        // Init any instances registered during module.start() that missed the first pass
+        const allInstances = DIContainer.getInstance().getInstances();
+        const lateInstances = allInstances.filter((instance) => !initializedInstances.has(instance));
+        if (lateInstances.length > 0) {
+            await triggerLifecycleHook(lateInstances, 'onModuleInit');
+        }
+        // NestJS: onApplicationBootstrap runs after init, before the app accepts connections
+        await triggerLifecycleHook(DIContainer.getInstance().getInstances(), 'onApplicationBootstrap');
+        // Start HTTP listener and attach legacy SSE routes ONLY AFTER dynamic modules have finished starting
+        if ((transportType === 'dual' || transportType === 'http') && this._httpTransport) {
+            this.attachLegacySdkSseIfNeeded(this._httpTransport);
+            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, {
@@ -888,57 +971,27 @@ export class NitroStackServer {
                 // DUAL transport: STDIO + HTTP SSE
                 // STDIO: For direct MCP connections (dev tools, Claude Desktop)
                 // HTTP SSE: For web-based clients and multiple concurrent connections
-                // 1. Start HTTP SSE transport (reuse if already created by start())
+                // 1. Ensure the HTTP host is running (normally created by start()).
+                // The host owns /mcp and delegates protocol handling to the official SDK
+                // Streamable HTTP transport via the MCP server factory (one server per
+                // session), so no manual message forwarding is required here.
                 let httpTransport = this._httpTransport;
                 if (!httpTransport) {
                     const { StreamableHttpTransport } = await import('./transports/streamable-http.js');
-                    httpTransport = new StreamableHttpTransport({
+                    const transport = new StreamableHttpTransport({
                         port: transportOptions?.port || 3000,
                         host: transportOptions?.host || 'localhost',
                         endpoint: transportOptions?.endpoint || '/mcp',
-                        enableSessions: false, // Disable sessions for simpler backward compat
                         enableCors: transportOptions?.enableCors !== false, // Enable CORS by default for web clients
+                        ...getStreamableHttpEnvOptions(),
                     });
-                    this.attachLegacySdkSseIfNeeded(httpTransport);
-                    await httpTransport.start();
+                    transport.setMcpServerFactory(() => this.createConfiguredMcpServer());
+                    this.attachLegacySdkSseIfNeeded(transport);
+                    await transport.start();
+                    httpTransport = transport;
                     this._httpTransport = httpTransport;
                 }
-                // Wire up HTTP transport to handle MCP messages
-                // Since we can't connect to two transports, manually forward HTTP messages
-                const transport = httpTransport;
-                transport.onmessage = async (message) => {
-                    // Handle the message through the MCP server's internal handler
-                    try {
-                        // Access internal handlers - this is necessary for dual mode
-                        const mcpServerInternal = this.mcpServer;
-                        const handlers = mcpServerInternal._requestHandlers;
-                        if (handlers && message && message.method && message.id !== undefined) {
-                            const handler = handlers.get(message.method);
-                            if (handler) {
-                                const result = await handler(message);
-                                // Send response back through HTTP transport
-                                await transport.send({
-                                    jsonrpc: '2.0',
-                                    id: message.id,
-                                    result,
-                                });
-                            }
-                        }
-                    }
-                    catch (error) {
-                        const err = error;
-                        // Send error response
-                        await transport.send({
-                            jsonrpc: '2.0',
-                            id: message.id ?? null,
-                            error: {
-                                code: -32603,
-                                message: err.message || 'Internal error',
-                            },
-                        });
-                    }
-                };
-                // 2. Connect MCP server via STDIO for direct connections
+                // 2. Connect the primary MCP server via STDIO for direct connections.
                 const stdioTransport = new StdioServerTransport();
                 await this.mcpServer.connect(stdioTransport);
                 this.logger.info(`${this.config.name} started successfully (DUAL MODE)`);
@@ -957,9 +1010,11 @@ export class NitroStackServer {
                         port: transportOptions?.port || 3000,
                         host: transportOptions?.host || 'localhost',
                         endpoint: transportOptions?.endpoint || '/mcp',
-                        enableSessions: true,
                         enableCors: transportOptions?.enableCors || false,
+                        ...getStreamableHttpEnvOptions(),
                     });
+                    // Delegate /mcp protocol handling to the official SDK transport.
+                    transport.setMcpServerFactory(() => this.createConfiguredMcpServer());
                     // 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()));
@@ -971,13 +1026,13 @@ export class NitroStackServer {
                         description: this.config.description,
                     });
                     this.attachLegacySdkSseIfNeeded(transport);
-                    // Start HTTP server first
+                    // Start HTTP server
                     await transport.start();
                     httpTransport = transport;
                     this._httpTransport = httpTransport;
                 }
-                // Then connect MCP server
-                await this.mcpServer.connect(httpTransport);
+                // The HTTP host owns /mcp and manages its own per-session MCP servers via
+                // the factory; no direct mcpServer.connect() is needed here.
                 this.logger.info(`${this.config.name} started successfully (HTTP SSE transport)`);
                 this.logger.info(`✨ Mode: ${getAppMode().toUpperCase()} (via NITROSTACK_APP_MODE)`);
                 this.logger.info(`🌐 Streamable HTTP: http://${transportOptions?.host || 'localhost'}:${transportOptions?.port || 3000}${transportOptions?.endpoint || '/mcp'}`);
@@ -1098,16 +1153,77 @@ export class NitroStackServer {
     getTaskManager() {
         return this.taskManager;
     }
+    /**
+     * Register OS signal handlers so the server shuts down gracefully, running the
+     * NestJS-style shutdown lifecycle hooks (beforeApplicationShutdown /
+     * onApplicationShutdown) with the received signal.
+     *
+     * Opt-in (like NestJS `enableShutdownHooks`) to avoid attaching process
+     * listeners for consumers that manage their own shutdown. Safe to call more
+     * than once; handlers are only attached once per signal.
+     *
+     * @param signals - Signals to listen for (default: SIGTERM, SIGINT)
+     */
+    enableShutdownHooks(signals = ['SIGTERM', 'SIGINT']) {
+        for (const signal of signals) {
+            if (this._shutdownSignalHandlers.some((h) => h.signal === signal)) {
+                continue;
+            }
+            const handler = () => {
+                // stop() is idempotent, so repeated signals are safe.
+                this.stop(signal).catch((error) => {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    this.logger.error(`Error during ${signal} shutdown`, { error: errorMessage });
+                });
+            };
+            process.on(signal, handler);
+            this._shutdownSignalHandlers.push({ signal, handler });
+        }
+        return this;
+    }
+    /**
+     * Remove any process signal handlers registered via enableShutdownHooks().
+     */
+    removeShutdownHooks() {
+        for (const { signal, handler } of this._shutdownSignalHandlers) {
+            process.removeListener(signal, handler);
+        }
+        this._shutdownSignalHandlers = [];
+    }
     /**
      * Stop the server
+     *
+     * Idempotent: concurrent or repeated calls (e.g. from multiple OS signals)
+     * share the same in-flight teardown instead of re-running lifecycle hooks or
+     * double-closing transports.
      */
-    async stop() {
+    async stop(signal) {
+        if (!this._stopping) {
+            this._stopping = this.doStop(signal);
+        }
+        return this._stopping;
+    }
+    async doStop(signal) {
+        // Detach signal handlers first so nothing re-enters teardown mid-shutdown.
+        this.removeShutdownHooks();
+        const instances = DIContainer.getInstance().getInstances();
         try {
-            // Call stop for all modules
+            // Call onModuleDestroy for all resolved instances
+            await triggerLifecycleHook(instances, 'onModuleDestroy', { safe: true, logger: this.logger });
+            // Call beforeApplicationShutdown for all resolved instances
+            await triggerLifecycleHook(instances, 'beforeApplicationShutdown', { safe: true, logger: this.logger }, signal);
+            // Call stop for all modules. A single failing module must not prevent the
+            // remaining modules (or transport teardown) from stopping.
             for (const moduleClass of this.modules) {
                 const moduleInstance = DIContainer.getInstance().resolve(moduleClass);
                 if (moduleInstance.stop) {
-                    await moduleInstance.stop();
+                    try {
+                        await moduleInstance.stop();
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        this.logger.error(`Error stopping module ${moduleClass.name}`, { error: errorMessage });
+                    }
                 }
             }
             // Destroy task manager (stops cleanup interval)
@@ -1142,6 +1258,10 @@ export class NitroStackServer {
             this.logger.error('Error stopping server', { error: errorMessage });
             throw error;
         }
+        finally {
+            // NestJS: always run after connection close attempts, even if close threw
+            await triggerLifecycleHook(instances, 'onApplicationShutdown', { safe: true, logger: this.logger }, signal);
+        }
     }
     /**
      * Get the HTTP transport (for modules that need to register endpoints)