mcp-use 1.5.0 → 1.5.1-canary.1

package/dist/src/server/logging.d.ts

@@ -8,6 +8,12 @@ import type { Context, Next } from "hono";
  * - MCP method name in brackets for POST requests to /mcp
  * - Color-coded status codes (green 2xx, yellow 3xx, red 4xx, magenta 5xx)
  *
+ * When DEBUG environment variable is set, also logs:
+ * - Request headers
+ * - Full request payload/body
+ * - Response headers
+ * - Response body
+ *
  * @param c - Hono context object
  * @param next - Hono next function
  */

package/dist/src/server/logging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/server/logging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CzE"}
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/server/logging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAyC1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAsIzE"}

package/dist/src/server/mcp-server.d.ts

@@ -1,3 +1,5 @@
+import type { CreateMessageRequest, CreateMessageResult } from "@modelcontextprotocol/sdk/types.js";
+import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { type Hono as HonoType } from "hono";
 import type { PromptDefinition, ResourceDefinition, ResourceTemplateDefinition, ServerConfig, ToolDefinition, UIResourceDefinition } from "./types/index.js";
 export declare class McpServer {
@@ -12,6 +14,9 @@ export declare class McpServer {
     private registeredTools;
     private registeredPrompts;
     private registeredResources;
+    private buildId?;
+    private sessions;
+    private idleCleanupInterval?;
     /**
      * Creates a new MCP server instance with Hono integration
      *
@@ -175,6 +180,43 @@ export declare class McpServer {
      * ```
      */
     prompt(promptDefinition: PromptDefinition): 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 }]
+     *     };
+     *   }
+     * })
+     * ```
+     */
+    createMessage(params: CreateMessageRequest["params"], options?: RequestOptions): Promise<CreateMessageResult>;
     /**
      * Register a UI widget as both a tool and a resource
      *
@@ -256,6 +298,16 @@ export declare class McpServer {
      * @returns UIResource object compatible with MCP-UI
      */
     private createWidgetUIResource;
+    /**
+     * 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
+     */
+    private generateWidgetUri;
     /**
      * Build a complete URL for a widget including query parameters
      *
@@ -358,12 +410,11 @@ export declare class McpServer {
      */
     private waitForRequestComplete;
     /**
-     * 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.
@@ -373,9 +424,9 @@ export declare class McpServer {
      *
      * @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
      */
     private mountMcp;
     /**
@@ -385,7 +436,7 @@ export declare class McpServer {
      * 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)
@@ -395,7 +446,7 @@ export declare class McpServer {
      * ```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
      * ```
      */
@@ -440,6 +491,132 @@ export declare class McpServer {
     getHandler(options?: {
         provider?: "supabase" | "cloudflare" | "deno-deploy";
     }): Promise<(req: Request) => Promise<Response>>;
+    /**
+     * 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(): string[];
+    /**
+     * 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");
+     * ```
+     */
+    sendNotification(method: string, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * 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
+     *   });
+     * });
+     * ```
+     */
+    sendNotificationToSession(sessionId: string, method: string, params?: Record<string, unknown>): Promise<boolean>;
+    private 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: (roots: Array<{
+        uri: string;
+        name?: string;
+    }>) => void | Promise<void>): 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}`));
+     *   }
+     * }
+     * ```
+     */
+    listRoots(sessionId: string): Promise<Array<{
+        uri: string;
+        name?: string;
+    }> | null>;
     /**
      * Mount MCP Inspector UI at /inspector
      *
@@ -456,7 +633,7 @@ export declare class McpServer {
      * @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
@@ -591,16 +768,30 @@ export type McpServerInstance = Omit<McpServer, keyof HonoType> & HonoType & {
  * @param config.description - Server description
  * @param config.host - Hostname for widget URLs and server endpoints (defaults to 'localhost')
  * @param config.baseUrl - Full base URL (e.g., 'https://myserver.com') - overrides host:port for widget URLs
+ * @param config.allowedOrigins - Allowed origins for DNS rebinding protection
+ *   - **Development mode** (NODE_ENV !== "production"): If not set, all origins are allowed
+ *   - **Production mode** (NODE_ENV === "production"): Only uses explicitly configured origins
+ *   - See {@link ServerConfig.allowedOrigins} for detailed documentation
+ * @param config.sessionIdleTimeoutMs - Idle timeout for sessions in milliseconds (default: 300000 = 5 minutes)
  * @returns McpServerInstance with both MCP and Hono methods
  *
  * @example
  * ```typescript
- * // Basic usage
+ * // Basic usage (development mode - allows all origins)
  * const server = createMCPServer('my-server', {
  *   version: '1.0.0',
  *   description: 'My MCP server'
  * })
  *
+ * // Production mode with explicit allowed origins
+ * const server = createMCPServer('my-server', {
+ *   version: '1.0.0',
+ *   allowedOrigins: [
+ *     'https://myapp.com',
+ *     'https://app.myapp.com'
+ *   ]
+ * })
+ *
  * // With custom host (e.g., for Docker or remote access)
  * const server = createMCPServer('my-server', {
  *   version: '1.0.0',

package/dist/src/server/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../../src/server/mcp-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../../src/server/mcp-server.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EAEpB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,EAAsB,KAAK,IAAI,IAAI,QAAQ,EAAa,MAAM,MAAM,CAAC;AAkB5E,OAAO,KAAK,EAEV,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,YAAY,EACZ,cAAc,EAEd,oBAAoB,EAErB,MAAM,kBAAkB,CAAC;AA4G1B,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,GAAG,CAAW;IACtB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,mBAAmB,CAAgB;IAC3C,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,QAAQ,CAMZ;IACJ,OAAO,CAAC,mBAAmB,CAAC,CAAiB;IAE7C;;;;;;;;;OASG;gBACS,MAAM,EAAE,YAAY;IAwGhC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,GAAG,IAAI;IAoBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,gBAAgB,CACd,0BAA0B,EAAE,0BAA0B,GACrD,IAAI;IAkDP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,IAAI,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI;IAmC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI;IAiBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,aAAa,CACjB,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACtC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,mBAAmB,CAAC;IAO/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACH,UAAU,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI;IAwKlD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,sBAAsB;IA2C9B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;;;;OAKG;YACW,iBAAiB;IAkB/B;;;;;;;;;;OAUG;IACG,YAAY,CAAC,OAAO,CAAC,EAAE;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjB;;;;;;;;;;;;OAYG;YACW,eAAe;IAihB7B;;;;;;;;;;;OAWG;YACW,sBAAsB;IAqNpC;;;;;;;;OAQG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;;;;;;;;;;;;;;OAkBG;YACW,QAAQ;IAslBtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAuBpB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6G1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE;QACzB,QAAQ,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;KACtD,GAAG,OAAO,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAiEhD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC;IAoBhB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,yBAAyB,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC;IAyBnB,OAAO,CAAC,sBAAsB,CAAC,CAEL;IAE1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CACZ,QAAQ,EAAE,CACR,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,KACzC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxB,IAAI;IAKP;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,SAAS,CACb,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAkCxD;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,cAAc;IAwC5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,iBAAiB;IAoLzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,kBAAkB;IA+C1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,sBAAsB;IAqC9B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,gBAAgB;CA4BzB;AAED,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,QAAQ,CAAC,GAC7D,QAAQ,GAAG;IACT,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE;QACrB,QAAQ,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;KACtD,KAAK,OAAO,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;CACpD,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,iBAAiB,CAWnB"}

package/dist/src/server/types/common.d.ts

@@ -7,6 +7,65 @@ export interface ServerConfig {
     description?: string;
     host?: string;
     baseUrl?: string;
+    /**
+     * Allowed origins for DNS rebinding protection
+     *
+     * **Development mode** (NODE_ENV !== "production"):
+     * - If not set: All origins are allowed (DNS rebinding protection disabled)
+     * - This enables direct browser connections from any origin for easier development
+     *
+     * **Production mode** (NODE_ENV === "production"):
+     * - If not set: DNS rebinding protection is disabled (not recommended for production)
+     * - If set to empty array: DNS rebinding protection is disabled
+     * - If set with origins: DNS rebinding protection is enabled with those specific origins
+     *
+     * @example
+     * ```typescript
+     * // Development: No need to set (allows all origins)
+     * const server = createMCPServer('my-server');
+     *
+     * // Production: Explicitly set allowed origins
+     * const server = createMCPServer('my-server', {
+     *   allowedOrigins: [
+     *     'https://myapp.com',
+     *     'https://app.myapp.com'
+     *   ]
+     * });
+     * ```
+     */
+    allowedOrigins?: string[];
+    sessionIdleTimeoutMs?: number;
+    /**
+     * Automatically create a new session when a request is received with an invalid/expired session ID.
+     *
+     * **Default: true** (enables compatibility with non-compliant clients like ChatGPT)
+     *
+     * When set to `true` (default), the server will automatically create a new session when it receives
+     * a request with an invalid or expired session ID. This allows clients to seamlessly
+     * reconnect after server restarts without needing to send a new `initialize` request.
+     *
+     * **Note**: According to the [MCP protocol specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management),
+     * clients **MUST** start a new session by sending a new `InitializeRequest` when they receive
+     * HTTP 404 in response to a request containing an `MCP-Session-Id`. However, some clients (like
+     * ChatGPT) don't properly handle this and fail to reconnect. Setting this to `true` enables
+     * compatibility with these non-compliant clients.
+     *
+     * When set to `false`, the server follows the MCP protocol specification strictly:
+     * it returns HTTP 404 Not Found for requests with invalid session IDs, requiring
+     * clients to explicitly send a new `initialize` request.
+     *
+     * @example
+     * ```typescript
+     * // Default behavior (compatible with ChatGPT and other non-compliant clients)
+     * const server = createMCPServer('my-server');
+     *
+     * // Use strict MCP spec behavior (requires compliant clients)
+     * const server = createMCPServer('my-server', {
+     *   autoCreateSessionOnInvalidId: false
+     * });
+     * ```
+     */
+    autoCreateSessionOnInvalidId?: boolean;
 }
 export interface InputDefinition {
     name: string;

package/dist/src/server/types/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/server/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/server/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/src/session.d.ts

@@ -1,4 +1,5 @@
-import type { BaseConnector } from "./connectors/base.js";
+import type { Notification, Root } from "@modelcontextprotocol/sdk/types.js";
+import type { BaseConnector, NotificationHandler } from "./connectors/base.js";
 export declare class MCPSession {
     readonly connector: BaseConnector;
     private autoConnect;
@@ -7,5 +8,43 @@ export declare class MCPSession {
     disconnect(): Promise<void>;
     initialize(): Promise<void>;
     get isConnected(): boolean;
+    /**
+     * Register an event handler for session events
+     *
+     * @param event - The event type to listen for
+     * @param handler - The handler function to call when the event occurs
+     *
+     * @example
+     * ```typescript
+     * session.on("notification", async (notification) => {
+     *   console.log(`Received: ${notification.method}`, notification.params);
+     *
+     *   if (notification.method === "notifications/tools/list_changed") {
+     *     // Refresh tools list
+     *   }
+     * });
+     * ```
+     */
+    on(event: "notification", handler: NotificationHandler): void;
+    /**
+     * Set roots and notify the server.
+     * Roots represent directories or files that the client has access to.
+     *
+     * @param roots - Array of Root objects with `uri` (must start with "file://") and optional `name`
+     *
+     * @example
+     * ```typescript
+     * await session.setRoots([
+     *   { uri: "file:///home/user/project", name: "My Project" },
+     *   { uri: "file:///home/user/data" }
+     * ]);
+     * ```
+     */
+    setRoots(roots: Root[]): Promise<void>;
+    /**
+     * Get the current roots.
+     */
+    getRoots(): Root[];
 }
+export type { Notification, Root };
 //# sourceMappingURL=session.d.ts.map

package/dist/src/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,qBAAa,UAAU;IACrB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,OAAO,CAAC,WAAW,CAAU;gBAEjB,SAAS,EAAE,aAAa,EAAE,WAAW,UAAO;IAKlD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,IAAI,WAAW,IAAI,OAAO,CAEzB;CACF"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,qBAAa,UAAU;IACrB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,OAAO,CAAC,WAAW,CAAU;gBAEjB,SAAS,EAAE,aAAa,EAAE,WAAW,UAAO;IAKlD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAM7D;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;CAGnB;AAGD,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.5.1-canary.1",
   "description": "Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents and Clients + MCP Servers with support for MCP-UI.",
   "author": "mcp-use, Inc.",
   "license": "MIT",
@@ -115,8 +115,8 @@
     "ws": "^8.18.2",
     "zod": "^3.25.48",
     "zod-to-json-schema": "^3.24.6",
-    "@mcp-use/cli": "2.3.0",
-    "@mcp-use/inspector": "0.7.0"
+    "@mcp-use/cli": "2.3.1-canary.1",
+    "@mcp-use/inspector": "0.7.1-canary.1"
   },
   "optionalDependencies": {
     "@tailwindcss/vite": "^4.1.15",
@@ -193,6 +193,12 @@
     "example:structured": "tsx examples/client/structured_output.ts",
     "example:observability": "tsx examples/client/observability.ts",
     "example:code_mode": "tsx examples/client/code_mode_example.ts",
-    "example:code_mode_e2b": "source .env 2>/dev/null || true && tsx examples/client/code_mode_e2b_example.ts"
+    "example:code_mode_e2b": "source .env 2>/dev/null || true && tsx examples/client/code_mode_e2b_example.ts",
+    "example:server:notification": "tsx examples/server/notification-example/src/server.ts",
+    "example:client:notification": "tsx examples/client/notification-client.ts",
+    "example:notifications": "lsof -ti:3000 | xargs kill -9 2>/dev/null; tsx examples/server/notification-example/src/server.ts & sleep 3 && tsx examples/client/notification-client.ts",
+    "example:server:sampling": "tsx examples/server/sampling/src/server.ts",
+    "example:client:sampling": "tsx examples/client/sampling-client.ts",
+    "example:sampling": "lsof -ti:3001 | xargs kill -9 2>/dev/null; tsx examples/server/sampling/src/server.ts & sleep 3 && tsx examples/client/sampling-client.ts"
   }
 }