mcp-use 1.5.0 → 1.5.1-canary.0

package/dist/src/server/index.js

@@ -70,7 +70,8 @@ function createAppsSdkResource(uri, htmlTemplate, metadata) {
 }
 __name(createAppsSdkResource, "createAppsSdkResource");
 function createUIResourceFromDefinition(definition, params, config) {
-  const uri = definition.type === "appsSdk" ? `ui://widget/${definition.name}.html` : `ui://widget/${definition.name}`;
+  const buildIdPart = config.buildId ? `-${config.buildId}` : "";
+  const uri = definition.type === "appsSdk" ? `ui://widget/${definition.name}${buildIdPart}.html` : `ui://widget/${definition.name}${buildIdPart}`;
   const encoding = definition.encoding || "text";
   switch (definition.type) {
     case "externalUrl": {
@@ -296,6 +297,10 @@ async function requestLogger(c, next) {
 __name(requestLogger, "requestLogger");
 
 // src/server/mcp-server.ts
+function generateUUID() {
+  return globalThis.crypto.randomUUID();
+}
+__name(generateUUID, "generateUUID");
 var TMP_MCP_USE_DIR = ".mcp-use";
 var isDeno = typeof globalThis.Deno !== "undefined";
 function getEnv(key) {
@@ -391,6 +396,9 @@ var McpServer = class {
   registeredTools = [];
   registeredPrompts = [];
   registeredResources = [];
+  buildId;
+  sessions = /* @__PURE__ */ new Map();
+  idleCleanupInterval;
   /**
    * Creates a new MCP server instance with Hono integration
    *
@@ -423,7 +431,9 @@ var McpServer = class {
           "mcp-session-id",
           "X-Proxy-Token",
           "X-Target-URL"
-        ]
+        ],
+        // Expose mcp-session-id so browser clients can read it from responses
+        exposeHeaders: ["mcp-session-id"]
       })
     );
     this.app.use("*", requestLogger);
@@ -663,6 +673,11 @@ var McpServer = class {
    */
   tool(toolDefinition) {
     const inputSchema = this.createParamsSchema(toolDefinition.inputs || []);
+    const context = {
+      sample: /* @__PURE__ */ __name(async (params, options) => {
+        return await this.createMessage(params, options);
+      }, "sample")
+    };
     this.server.registerTool(
       toolDefinition.name,
       {
@@ -673,6 +688,9 @@ var McpServer = class {
         _meta: toolDefinition._meta
       },
       async (params) => {
+        if (toolDefinition.cb.length >= 2) {
+          return await toolDefinition.cb(params, context);
+        }
         return await toolDefinition.cb(params);
       }
     );
@@ -729,6 +747,46 @@ var McpServer = class {
     this.registeredPrompts.push(promptDefinition.name);
     return this;
   }
+  /**
+   * Request LLM sampling from connected clients.
+   *
+   * This method allows server tools to request LLM completions from clients
+   * that support the sampling capability. The client will handle model selection,
+   * user approval (human-in-the-loop), and return the generated response.
+   *
+   * @param params - Sampling request parameters including messages, model preferences, etc.
+   * @param options - Optional request options (timeouts, cancellation, etc.)
+   * @returns Promise resolving to the generated message from the client's LLM
+   *
+   * @example
+   * ```typescript
+   * // In a tool callback
+   * server.tool({
+   *   name: 'analyze-sentiment',
+   *   description: 'Analyze sentiment using LLM',
+   *   inputs: [{ name: 'text', type: 'string', required: true }],
+   *   cb: async (params, ctx) => {
+   *     const result = await ctx.sample({
+   *       messages: [{
+   *         role: 'user',
+   *         content: { type: 'text', text: `Analyze sentiment: ${params.text}` }
+   *       }],
+   *       modelPreferences: {
+   *         intelligencePriority: 0.8,
+   *         speedPriority: 0.5
+   *       }
+   *     });
+   *     return {
+   *       content: [{ type: 'text', text: result.content.text }]
+   *     };
+   *   }
+   * })
+   * ```
+   */
+  async createMessage(params, options) {
+    console.log("createMessage", params, options);
+    return await this.server.server.createMessage(params, options);
+  }
   /**
    * Register a UI widget as both a tool and a resource
    *
@@ -802,19 +860,19 @@ var McpServer = class {
     let mimeType;
     switch (definition.type) {
       case "externalUrl":
-        resourceUri = `ui://widget/${definition.widget}`;
+        resourceUri = this.generateWidgetUri(definition.widget);
         mimeType = "text/uri-list";
         break;
       case "rawHtml":
-        resourceUri = `ui://widget/${definition.name}`;
+        resourceUri = this.generateWidgetUri(definition.name);
         mimeType = "text/html";
         break;
       case "remoteDom":
-        resourceUri = `ui://widget/${definition.name}`;
+        resourceUri = this.generateWidgetUri(definition.name);
         mimeType = "application/vnd.mcp-ui.remote-dom+javascript";
         break;
       case "appsSdk":
-        resourceUri = `ui://widget/${definition.name}.html`;
+        resourceUri = this.generateWidgetUri(definition.name, ".html");
         mimeType = "text/html+skybridge";
         break;
       default:
@@ -833,16 +891,19 @@ var McpServer = class {
       readCallback: /* @__PURE__ */ __name(async () => {
         const params = definition.type === "externalUrl" ? this.applyDefaultProps(definition.props) : {};
         const uiResource = this.createWidgetUIResource(definition, params);
+        uiResource.resource.uri = resourceUri;
         return {
           contents: [uiResource.resource]
         };
       }, "readCallback")
     });
     if (definition.type === "appsSdk") {
+      const buildIdPart = this.buildId ? `-${this.buildId}` : "";
+      const uriTemplate = `ui://widget/${definition.name}${buildIdPart}-{id}.html`;
       this.resourceTemplate({
         name: `${definition.name}-dynamic`,
         resourceTemplate: {
-          uriTemplate: `ui://widget/${definition.name}-{id}.html`,
+          uriTemplate,
           name: definition.title || definition.name,
           description: definition.description,
           mimeType
@@ -853,6 +914,7 @@ var McpServer = class {
         annotations: definition.annotations,
         readCallback: /* @__PURE__ */ __name(async (uri, params) => {
           const uiResource = this.createWidgetUIResource(definition, {});
+          uiResource.resource.uri = uri.toString();
           return {
             contents: [uiResource.resource]
           };
@@ -884,7 +946,11 @@ var McpServer = class {
         const uiResource = this.createWidgetUIResource(definition, params);
         if (definition.type === "appsSdk") {
           const randomId = Math.random().toString(36).substring(2, 15);
-          const uniqueUri = `ui://widget/${definition.name}-${randomId}.html`;
+          const uniqueUri = this.generateWidgetUri(
+            definition.name,
+            ".html",
+            randomId
+          );
           const uniqueToolMetadata = {
             ...toolMetadata,
             "openai/outputTemplate": uniqueUri
@@ -941,7 +1007,8 @@ var McpServer = class {
     }
     const urlConfig = {
       baseUrl: configBaseUrl,
-      port: configPort
+      port: configPort,
+      buildId: this.buildId
     };
     const uiResource = createUIResourceFromDefinition(
       definition,
@@ -956,6 +1023,25 @@ var McpServer = class {
     }
     return uiResource;
   }
+  /**
+   * Generate a widget URI with optional build ID for cache busting
+   *
+   * @private
+   * @param widgetName - Widget name/identifier
+   * @param extension - Optional file extension (e.g., '.html')
+   * @param suffix - Optional suffix (e.g., random ID for dynamic URIs)
+   * @returns Widget URI with build ID if available
+   */
+  generateWidgetUri(widgetName, extension = "", suffix = "") {
+    const parts = [widgetName];
+    if (this.buildId) {
+      parts.push(this.buildId);
+    }
+    if (suffix) {
+      parts.push(suffix);
+    }
+    return `ui://widget/${parts.join("-")}${extension}`;
+  }
   /**
    * Build a complete URL for a widget including query parameters
    *
@@ -1501,6 +1587,10 @@ if (container && Component) {
         "utf8"
       );
       const manifest = JSON.parse(manifestContent);
+      if (manifest.buildId && typeof manifest.buildId === "string") {
+        this.buildId = manifest.buildId;
+        console.log(`[WIDGETS] Build ID: ${this.buildId}`);
+      }
       if (manifest.widgets && typeof manifest.widgets === "object" && !Array.isArray(manifest.widgets)) {
         widgets = Object.keys(manifest.widgets);
         widgetsMetadata = manifest.widgets;
@@ -1633,6 +1723,7 @@ if (container && Component) {
             resource_domains: [
               "https://*.oaistatic.com",
               "https://*.oaiusercontent.com",
+              "https://*.openai.com",
               // always also add the base url of the server
               ...this.getServerBaseUrl() ? [this.getServerBaseUrl()] : [],
               ...metadata.appsSdkMetadata?.["openai/widgetCSP"]?.resource_domains || []
@@ -1665,12 +1756,11 @@ if (container && Component) {
     });
   }
   /**
-   * Mount MCP server endpoints at /mcp
+   * Mount MCP server endpoints at /mcp and /sse
    *
    * Sets up the HTTP transport layer for the MCP server, creating endpoints for
    * Server-Sent Events (SSE) streaming, POST message handling, and DELETE session cleanup.
-   * Each request gets its own transport instance to prevent state conflicts between
-   * concurrent client connections.
+   * Transports are reused per session ID to maintain state across requests.
    *
    * This method is called automatically when the server starts listening and ensures
    * that MCP clients can communicate with the server over HTTP.
@@ -1680,14 +1770,80 @@ if (container && Component) {
    *
    * @example
    * Endpoints created:
-   * - GET /mcp - SSE streaming endpoint for real-time communication
-   * - POST /mcp - Message handling endpoint for MCP protocol messages
-   * - DELETE /mcp - Session cleanup endpoint
+   * - GET /mcp, GET /sse - SSE streaming endpoint for real-time communication
+   * - POST /mcp, POST /sse - Message handling endpoint for MCP protocol messages
+   * - DELETE /mcp, DELETE /sse - Session cleanup endpoint
    */
   async mountMcp() {
     if (this.mcpMounted) return;
     const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
-    const endpoint = "/mcp";
+    const idleTimeoutMs = this.config.sessionIdleTimeoutMs ?? 3e5;
+    const getOrCreateTransport = /* @__PURE__ */ __name(async (sessionId, isInit = false) => {
+      if (isInit) {
+        if (sessionId && this.sessions.has(sessionId)) {
+          try {
+            this.sessions.get(sessionId).transport.close();
+          } catch (error) {
+          }
+          this.sessions.delete(sessionId);
+        }
+        const isProduction = this.isProductionMode();
+        let allowedOrigins = this.config.allowedOrigins;
+        let enableDnsRebindingProtection = false;
+        if (isProduction) {
+          if (allowedOrigins !== void 0) {
+            enableDnsRebindingProtection = allowedOrigins.length > 0;
+          }
+        } else {
+          allowedOrigins = void 0;
+          enableDnsRebindingProtection = false;
+        }
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: /* @__PURE__ */ __name(() => generateUUID(), "sessionIdGenerator"),
+          enableJsonResponse: true,
+          allowedOrigins,
+          enableDnsRebindingProtection,
+          onsessioninitialized: /* @__PURE__ */ __name((id) => {
+            if (id) {
+              this.sessions.set(id, {
+                transport,
+                lastAccessedAt: Date.now()
+              });
+            }
+          }, "onsessioninitialized"),
+          onsessionclosed: /* @__PURE__ */ __name((id) => {
+            if (id) {
+              this.sessions.delete(id);
+            }
+          }, "onsessionclosed")
+        });
+        await this.server.connect(transport);
+        return transport;
+      }
+      if (sessionId && this.sessions.has(sessionId)) {
+        const session = this.sessions.get(sessionId);
+        session.lastAccessedAt = Date.now();
+        return session.transport;
+      }
+      if (sessionId) {
+        return null;
+      }
+      return null;
+    }, "getOrCreateTransport");
+    if (idleTimeoutMs > 0 && !this.idleCleanupInterval) {
+      this.idleCleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [sessionId, session] of this.sessions.entries()) {
+          if (now - session.lastAccessedAt > idleTimeoutMs) {
+            try {
+              session.transport.close();
+            } catch (error) {
+            }
+            this.sessions.delete(sessionId);
+          }
+        }
+      }, 6e4);
+    }
     const createExpressLikeObjects = /* @__PURE__ */ __name((c) => {
       const req = c.req.raw;
       const responseBody = [];
@@ -1795,164 +1951,250 @@ if (container && Component) {
         }, "getResponse")
       };
     }, "createExpressLikeObjects");
-    this.app.post(endpoint, async (c) => {
-      const { expressReq, expressRes, getResponse } = createExpressLikeObjects(c);
-      try {
-        expressReq.body = await c.req.json();
-      } catch {
-        expressReq.body = {};
-      }
-      const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: void 0,
-        enableJsonResponse: true
+    const mountEndpoint = /* @__PURE__ */ __name((endpoint) => {
+      this.app.post(endpoint, async (c) => {
+        const { expressReq, expressRes, getResponse } = createExpressLikeObjects(c);
+        let body = {};
+        try {
+          body = await c.req.json();
+          expressReq.body = body;
+        } catch {
+          expressReq.body = {};
+        }
+        const isInit = body?.method === "initialize";
+        const sessionId = c.req.header("mcp-session-id");
+        const transport = await getOrCreateTransport(sessionId, isInit);
+        if (!transport) {
+          if (sessionId) {
+            return c.json(
+              {
+                jsonrpc: "2.0",
+                error: {
+                  code: -32e3,
+                  message: "Session not found or expired"
+                },
+                // Notifications don't have an id, but we include null for consistency
+                id: body?.id ?? null
+              },
+              404
+            );
+          } else {
+            return c.json(
+              {
+                jsonrpc: "2.0",
+                error: {
+                  code: -32e3,
+                  message: "Bad Request: Mcp-Session-Id header is required"
+                },
+                id: body?.id ?? null
+              },
+              400
+            );
+          }
+        }
+        if (sessionId && this.sessions.has(sessionId)) {
+          this.sessions.get(sessionId).lastAccessedAt = Date.now();
+        }
+        if (expressRes._closeHandler) {
+          c.req.raw.signal?.addEventListener("abort", () => {
+            transport.close();
+          });
+        }
+        await this.waitForRequestComplete(
+          transport,
+          expressReq,
+          expressRes,
+          expressReq.body
+        );
+        const response = getResponse();
+        if (response) {
+          return response;
+        }
+        return c.text("", 200);
       });
-      if (expressRes._closeHandler) {
+      this.app.get(endpoint, async (c) => {
+        const sessionId = c.req.header("mcp-session-id");
+        const transport = await getOrCreateTransport(sessionId, false);
+        if (!transport) {
+          if (sessionId) {
+            return c.json(
+              {
+                jsonrpc: "2.0",
+                error: {
+                  code: -32e3,
+                  message: "Session not found or expired"
+                },
+                id: null
+              },
+              404
+            );
+          } else {
+            return c.json(
+              {
+                jsonrpc: "2.0",
+                error: {
+                  code: -32e3,
+                  message: "Bad Request: Mcp-Session-Id header is required"
+                },
+                id: null
+              },
+              400
+            );
+          }
+        }
+        if (sessionId && this.sessions.has(sessionId)) {
+          this.sessions.get(sessionId).lastAccessedAt = Date.now();
+        }
         c.req.raw.signal?.addEventListener("abort", () => {
           transport.close();
         });
-      }
-      await this.server.connect(transport);
-      await this.waitForRequestComplete(
-        transport,
-        expressReq,
-        expressRes,
-        expressReq.body
-      );
-      const response = getResponse();
-      if (response) {
-        return response;
-      }
-      return c.text("", 200);
-    });
-    this.app.get(endpoint, async (c) => {
-      const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: void 0,
-        enableJsonResponse: true
-      });
-      c.req.raw.signal?.addEventListener("abort", () => {
-        transport.close();
-      });
-      const { readable, writable } = new globalThis.TransformStream();
-      const writer = writable.getWriter();
-      const encoder = new TextEncoder();
-      let resolveResponse;
-      const responsePromise = new Promise((resolve) => {
-        resolveResponse = resolve;
-      });
-      let headersSent = false;
-      const headers = {};
-      let statusCode = 200;
-      const expressRes = {
-        statusCode: 200,
-        headersSent: false,
-        status: /* @__PURE__ */ __name((code) => {
-          statusCode = code;
-          expressRes.statusCode = code;
-          return expressRes;
-        }, "status"),
-        setHeader: /* @__PURE__ */ __name((name, value) => {
-          if (!headersSent) {
-            headers[name] = Array.isArray(value) ? value.join(", ") : value;
-          }
-        }, "setHeader"),
-        getHeader: /* @__PURE__ */ __name((name) => headers[name], "getHeader"),
-        write: /* @__PURE__ */ __name((chunk) => {
-          if (!headersSent) {
-            headersSent = true;
-            resolveResponse(
-              new Response(readable, {
-                status: statusCode,
-                headers
-              })
-            );
-          }
-          const data = typeof chunk === "string" ? encoder.encode(chunk) : chunk instanceof Uint8Array ? chunk : Buffer.from(chunk);
-          writer.write(data);
-          return true;
-        }, "write"),
-        end: /* @__PURE__ */ __name((chunk) => {
-          if (chunk) {
-            expressRes.write(chunk);
+        const { readable, writable } = new globalThis.TransformStream();
+        const writer = writable.getWriter();
+        const encoder = new TextEncoder();
+        let resolveResponse;
+        const responsePromise = new Promise((resolve) => {
+          resolveResponse = resolve;
+        });
+        let headersSent = false;
+        const headers = {};
+        let statusCode = 200;
+        const expressRes = {
+          statusCode: 200,
+          headersSent: false,
+          status: /* @__PURE__ */ __name((code) => {
+            statusCode = code;
+            expressRes.statusCode = code;
+            return expressRes;
+          }, "status"),
+          setHeader: /* @__PURE__ */ __name((name, value) => {
+            if (!headersSent) {
+              headers[name] = Array.isArray(value) ? value.join(", ") : value;
+            }
+          }, "setHeader"),
+          getHeader: /* @__PURE__ */ __name((name) => headers[name], "getHeader"),
+          write: /* @__PURE__ */ __name((chunk) => {
+            if (!headersSent) {
+              headersSent = true;
+              resolveResponse(
+                new Response(readable, {
+                  status: statusCode,
+                  headers
+                })
+              );
+            }
+            const data = typeof chunk === "string" ? encoder.encode(chunk) : chunk instanceof Uint8Array ? chunk : Buffer.from(chunk);
+            writer.write(data);
+            return true;
+          }, "write"),
+          end: /* @__PURE__ */ __name((chunk) => {
+            if (chunk) {
+              expressRes.write(chunk);
+            }
+            if (!headersSent) {
+              headersSent = true;
+              resolveResponse(
+                new Response(null, {
+                  status: statusCode,
+                  headers
+                })
+              );
+              writer.close();
+            } else {
+              writer.close();
+            }
+          }, "end"),
+          on: /* @__PURE__ */ __name((event, handler) => {
+            if (event === "close") {
+              expressRes._closeHandler = handler;
+            }
+          }, "on"),
+          once: /* @__PURE__ */ __name(() => {
+          }, "once"),
+          removeListener: /* @__PURE__ */ __name(() => {
+          }, "removeListener"),
+          writeHead: /* @__PURE__ */ __name((code, _headers) => {
+            statusCode = code;
+            expressRes.statusCode = code;
+            if (_headers) {
+              Object.assign(headers, _headers);
+            }
+            if (!headersSent) {
+              headersSent = true;
+              resolveResponse(
+                new Response(readable, {
+                  status: statusCode,
+                  headers
+                })
+              );
+            }
+            return expressRes;
+          }, "writeHead"),
+          flushHeaders: /* @__PURE__ */ __name(() => {
+          }, "flushHeaders")
+        };
+        const expressReq = {
+          ...c.req.raw,
+          url: new URL(c.req.url).pathname + new URL(c.req.url).search,
+          path: new URL(c.req.url).pathname,
+          query: Object.fromEntries(new URL(c.req.url).searchParams),
+          headers: c.req.header(),
+          method: c.req.method
+        };
+        transport.handleRequest(expressReq, expressRes).catch((err) => {
+          console.error("MCP Transport error:", err);
+          try {
+            writer.close();
+          } catch {
           }
-          if (!headersSent) {
-            headersSent = true;
-            resolveResponse(
-              new Response(null, {
-                status: statusCode,
-                headers
-              })
+        });
+        return responsePromise;
+      });
+      this.app.delete(endpoint, async (c) => {
+        const { expressReq, expressRes, getResponse } = createExpressLikeObjects(c);
+        const sessionId = c.req.header("mcp-session-id");
+        const transport = await getOrCreateTransport(sessionId, false);
+        if (!transport) {
+          if (sessionId) {
+            return c.json(
+              {
+                jsonrpc: "2.0",
+                error: {
+                  code: -32e3,
+                  message: "Session not found or expired"
+                },
+                id: null
+              },
+              404
             );
-            writer.close();
           } else {
-            writer.close();
-          }
-        }, "end"),
-        on: /* @__PURE__ */ __name((event, handler) => {
-          if (event === "close") {
-            expressRes._closeHandler = handler;
-          }
-        }, "on"),
-        once: /* @__PURE__ */ __name(() => {
-        }, "once"),
-        removeListener: /* @__PURE__ */ __name(() => {
-        }, "removeListener"),
-        writeHead: /* @__PURE__ */ __name((code, _headers) => {
-          statusCode = code;
-          expressRes.statusCode = code;
-          if (_headers) {
-            Object.assign(headers, _headers);
-          }
-          if (!headersSent) {
-            headersSent = true;
-            resolveResponse(
-              new Response(readable, {
-                status: statusCode,
-                headers
-              })
+            return c.json(
+              {
+                jsonrpc: "2.0",
+                error: {
+                  code: -32e3,
+                  message: "Bad Request: Mcp-Session-Id header is required"
+                },
+                id: null
+              },
+              400
             );
           }
-          return expressRes;
-        }, "writeHead"),
-        flushHeaders: /* @__PURE__ */ __name(() => {
-        }, "flushHeaders")
-      };
-      const expressReq = {
-        ...c.req.raw,
-        url: new URL(c.req.url).pathname + new URL(c.req.url).search,
-        path: new URL(c.req.url).pathname,
-        query: Object.fromEntries(new URL(c.req.url).searchParams),
-        headers: c.req.header(),
-        method: c.req.method
-      };
-      await this.server.connect(transport);
-      transport.handleRequest(expressReq, expressRes).catch((err) => {
-        console.error("MCP Transport error:", err);
-        try {
-          writer.close();
-        } catch {
         }
+        c.req.raw.signal?.addEventListener("abort", () => {
+          transport.close();
+        });
+        await this.waitForRequestComplete(transport, expressReq, expressRes);
+        const response = getResponse();
+        if (response) {
+          return response;
+        }
+        return c.text("", 200);
       });
-      return responsePromise;
-    });
-    this.app.delete(endpoint, async (c) => {
-      const { expressReq, expressRes, getResponse } = createExpressLikeObjects(c);
-      const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: void 0,
-        enableJsonResponse: true
-      });
-      c.req.raw.signal?.addEventListener("abort", () => {
-        transport.close();
-      });
-      await this.server.connect(transport);
-      await this.waitForRequestComplete(transport, expressReq, expressRes);
-      const response = getResponse();
-      if (response) {
-        return response;
-      }
-      return c.text("", 200);
-    });
+    }, "mountEndpoint");
+    mountEndpoint("/mcp");
+    mountEndpoint("/sse");
     this.mcpMounted = true;
-    console.log(`[MCP] Server mounted at ${endpoint}`);
+    console.log(`[MCP] Server mounted at /mcp and /sse`);
   }
   /**
    * Start the Hono server with MCP endpoints
@@ -1961,7 +2203,7 @@ if (container && Component) {
    * the inspector UI (if available), and starting the server to listen
    * for incoming connections. This is the main entry point for running the server.
    *
-   * The server will be accessible at the specified port with MCP endpoints at /mcp
+   * The server will be accessible at the specified port with MCP endpoints at /mcp and /sse
    * and inspector UI at /inspector (if the inspector package is installed).
    *
    * @param port - Port number to listen on (defaults to 3001 if not specified)
@@ -1971,7 +2213,7 @@ if (container && Component) {
    * ```typescript
    * await server.listen(8080)
    * // Server now running at http://localhost:8080 (or configured host)
-   * // MCP endpoints: http://localhost:8080/mcp
+   * // MCP endpoints: http://localhost:8080/mcp and http://localhost:8080/sse
    * // Inspector UI: http://localhost:8080/inspector
    * ```
    */
@@ -2075,7 +2317,7 @@ if (container && Component) {
             `[SERVER] Listening on http://${this.serverHost}:${this.serverPort}`
           );
           console.log(
-            `[MCP] Endpoints: http://${this.serverHost}:${this.serverPort}/mcp`
+            `[MCP] Endpoints: http://${this.serverHost}:${this.serverPort}/mcp and http://${this.serverHost}:${this.serverPort}/sse`
           );
         }
       );
@@ -2159,6 +2401,192 @@ if (container && Component) {
       return result;
     };
   }
+  /**
+   * Get array of active session IDs
+   *
+   * Returns an array of all currently active session IDs. This is useful for
+   * sending targeted notifications to specific clients or iterating over
+   * connected clients.
+   *
+   * Note: This only works in stateful mode. In stateless mode (edge environments),
+   * this will return an empty array.
+   *
+   * @returns Array of active session ID strings
+   *
+   * @example
+   * ```typescript
+   * const sessions = server.getActiveSessions();
+   * console.log(`${sessions.length} clients connected`);
+   *
+   * // Send notification to first connected client
+   * if (sessions.length > 0) {
+   *   server.sendNotificationToSession(sessions[0], "custom/hello", { message: "Hi!" });
+   * }
+   * ```
+   */
+  getActiveSessions() {
+    return Array.from(this.sessions.keys());
+  }
+  /**
+   * Send a notification to all connected clients
+   *
+   * Broadcasts a JSON-RPC notification to all active sessions. Notifications are
+   * one-way messages that do not expect a response from the client.
+   *
+   * Note: This only works in stateful mode with active sessions. If no sessions
+   * are connected, the notification is silently discarded (per MCP spec: "server MAY send").
+   *
+   * @param method - The notification method name (e.g., "custom/my-notification")
+   * @param params - Optional parameters to include in the notification
+   *
+   * @example
+   * ```typescript
+   * // Send a simple notification to all clients
+   * server.sendNotification("custom/server-status", {
+   *   status: "ready",
+   *   timestamp: new Date().toISOString()
+   * });
+   *
+   * // Notify all clients that resources have changed
+   * server.sendNotification("notifications/resources/list_changed");
+   * ```
+   */
+  async sendNotification(method, params) {
+    const notification = {
+      jsonrpc: "2.0",
+      method,
+      ...params && { params }
+    };
+    for (const [sessionId, session] of this.sessions.entries()) {
+      try {
+        await session.transport.send(notification);
+      } catch (error) {
+        console.warn(
+          `[MCP] Failed to send notification to session ${sessionId}:`,
+          error
+        );
+      }
+    }
+  }
+  /**
+   * Send a notification to a specific client session
+   *
+   * Sends a JSON-RPC notification to a single client identified by their session ID.
+   * This allows sending customized notifications to individual clients.
+   *
+   * Note: This only works in stateful mode. If the session ID doesn't exist,
+   * the notification is silently discarded.
+   *
+   * @param sessionId - The target session ID (from getActiveSessions())
+   * @param method - The notification method name (e.g., "custom/my-notification")
+   * @param params - Optional parameters to include in the notification
+   * @returns true if the notification was sent, false if session not found
+   *
+   * @example
+   * ```typescript
+   * const sessions = server.getActiveSessions();
+   *
+   * // Send different messages to different clients
+   * sessions.forEach((sessionId, index) => {
+   *   server.sendNotificationToSession(sessionId, "custom/welcome", {
+   *     message: `Hello client #${index + 1}!`,
+   *     clientNumber: index + 1
+   *   });
+   * });
+   * ```
+   */
+  async sendNotificationToSession(sessionId, method, params) {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return false;
+    }
+    const notification = {
+      jsonrpc: "2.0",
+      method,
+      ...params && { params }
+    };
+    try {
+      await session.transport.send(notification);
+      return true;
+    } catch (error) {
+      console.warn(
+        `[MCP] Failed to send notification to session ${sessionId}:`,
+        error
+      );
+      return false;
+    }
+  }
+  // Store the roots changed callback
+  onRootsChangedCallback;
+  /**
+   * Register a callback for when a client's roots change
+   *
+   * When a client sends a `notifications/roots/list_changed` notification,
+   * the server will automatically request the updated roots list and call
+   * this callback with the new roots.
+   *
+   * @param callback - Function called with the updated roots array
+   *
+   * @example
+   * ```typescript
+   * server.onRootsChanged(async (roots) => {
+   *   console.log("Client roots updated:", roots);
+   *   roots.forEach(root => {
+   *     console.log(`  - ${root.name || "unnamed"}: ${root.uri}`);
+   *   });
+   * });
+   * ```
+   */
+  onRootsChanged(callback) {
+    this.onRootsChangedCallback = callback;
+    return this;
+  }
+  /**
+   * Request the current roots list from a specific client session
+   *
+   * This sends a `roots/list` request to the client and returns
+   * the list of roots the client has configured.
+   *
+   * @param sessionId - The session ID of the client to query
+   * @returns Array of roots, or null if the session doesn't exist or request fails
+   *
+   * @example
+   * ```typescript
+   * const sessions = server.getActiveSessions();
+   * if (sessions.length > 0) {
+   *   const roots = await server.listRoots(sessions[0]);
+   *   if (roots) {
+   *     console.log(`Client has ${roots.length} roots:`);
+   *     roots.forEach(r => console.log(`  - ${r.uri}`));
+   *   }
+   * }
+   * ```
+   */
+  async listRoots(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return null;
+    }
+    try {
+      const request = {
+        jsonrpc: "2.0",
+        id: generateUUID(),
+        method: "roots/list",
+        params: {}
+      };
+      const response = await session.transport.send(request);
+      if (response && typeof response === "object" && "roots" in response) {
+        return response.roots;
+      }
+      return [];
+    } catch (error) {
+      console.warn(
+        `[MCP] Failed to list roots from session ${sessionId}:`,
+        error
+      );
+      return null;
+    }
+  }
   /**
    * Mount MCP Inspector UI at /inspector
    *
@@ -2175,7 +2603,7 @@ if (container && Component) {
    * @example
    * If @mcp-use/inspector is installed:
    * - Inspector UI available at http://localhost:PORT/inspector
-   * - Automatically connects to http://localhost:PORT/mcp
+   * - Automatically connects to http://localhost:PORT/mcp (or /sse)
    *
    * If not installed:
    * - Server continues to function normally
@@ -2194,7 +2622,14 @@ if (container && Component) {
     }
     try {
       const { mountInspector } = await import("@mcp-use/inspector");
-      mountInspector(this.app);
+      const mcpUrl = `http://${this.serverHost}:${this.serverPort}/mcp`;
+      const autoConnectConfig = JSON.stringify({
+        url: mcpUrl,
+        name: "Local MCP Server",
+        transportType: "sse",
+        connectionType: "Direct"
+      });
+      mountInspector(this.app, { autoConnectUrl: autoConnectConfig });
       this.inspectorMounted = true;
       console.log(
         `[INSPECTOR] UI available at http://${this.serverHost}:${this.serverPort}/inspector`
@@ -2518,7 +2953,9 @@ function createMCPServer(name, config = {}) {
     version: config.version || "1.0.0",
     description: config.description,
     host: config.host,
-    baseUrl: config.baseUrl
+    baseUrl: config.baseUrl,
+    allowedOrigins: config.allowedOrigins,
+    sessionIdleTimeoutMs: config.sessionIdleTimeoutMs
   });
   return instance;
 }