@mastra/mcp 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/index.js

@@ -1,20 +1,20 @@
+import $RefParser from '@apidevtools/json-schema-ref-parser';
 import { MastraBase } from '@mastra/core/base';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import equal from 'fast-deep-equal';
-import { v5 } from 'uuid';
-import $RefParser from '@apidevtools/json-schema-ref-parser';
 import { createTool } from '@mastra/core/tools';
-import { makeCoreTool, isZodType } from '@mastra/core/utils';
+import { isZodType, makeCoreTool } from '@mastra/core/utils';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, CallToolResultSchema, JSONRPCMessageSchema, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ListRootsRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, ProgressNotificationSchema, ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, CallToolResultSchema, ErrorCode, JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
 import { asyncExitHook, gracefulExit } from 'exit-hook';
 import { z } from 'zod';
 import { convertJsonSchemaToZod } from 'zod-from-json-schema';
 import { convertJsonSchemaToZod as convertJsonSchemaToZod$1 } from 'zod-from-json-schema-v3';
+import equal from 'fast-deep-equal';
+import { v5 } from 'uuid';
 import { randomUUID } from 'crypto';
 import { MCPServerBase } from '@mastra/core/mcp';
 import { RequestContext } from '@mastra/core/request-context';
@@ -22,10 +22,11 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+export { UnauthorizedError, auth, buildDiscoveryUrls, discoverAuthorizationServerMetadata, discoverOAuthMetadata, discoverOAuthProtectedResourceMetadata, exchangeAuthorization, extractResourceMetadataUrl, parseErrorResponse, refreshAuthorization, registerClient, selectResourceURL, startAuthorization } from '@modelcontextprotocol/sdk/client/auth.js';
 
-// src/client/configuration.ts
+// src/client/client.ts
 
-// src/client/elicitationActions.ts
+// src/client/actions/elicitation.ts
 var ElicitationClientActions = class {
   client;
   logger;
@@ -78,6 +79,23 @@ var ElicitationClientActions = class {
     this.client.setElicitationRequestHandler(handler);
   }
 };
+
+// src/client/actions/progress.ts
+var ProgressClientActions = class {
+  client;
+  logger;
+  constructor({ client, logger }) {
+    this.client = client;
+    this.logger = logger;
+  }
+  /**
+   * Set a notification handler for progress updates.
+   * @param handler The callback function to handle progress notifications.
+   */
+  onUpdate(handler) {
+    this.client.setProgressNotificationHandler(handler);
+  }
+};
 var PromptClientActions = class {
   client;
   logger;
@@ -366,6 +384,8 @@ var ResourceClientActions = class {
 };
 
 // src/client/client.ts
+var DEFAULT_SERVER_CONNECT_TIMEOUT_MSEC = 3e3;
+var SSE_FALLBACK_STATUS_CODES = [400, 404, 405];
 function convertLogLevelToLoggerMethod(level) {
   switch (level) {
     case "debug":
@@ -390,15 +410,21 @@ var InternalMastraMCPClient = class extends MastraBase {
   timeout;
   logHandler;
   enableServerLogs;
+  enableProgressTracking;
   serverConfig;
   transport;
   currentOperationContext = null;
+  exitHookUnsubscribe;
+  sigTermHandler;
+  _roots;
   /** Provides access to resource operations (list, read, subscribe, etc.) */
   resources;
   /** Provides access to prompt operations (list, get, notifications) */
   prompts;
   /** Provides access to elicitation operations (request handling) */
   elicitation;
+  /** Provides access to progress operations (notifications) */
+  progress;
   /**
    * @internal
    */
@@ -415,7 +441,15 @@ var InternalMastraMCPClient = class extends MastraBase {
     this.logHandler = server.logger;
     this.enableServerLogs = server.enableServerLogs ?? true;
     this.serverConfig = server;
-    const clientCapabilities = { ...capabilities, elicitation: {} };
+    this.enableProgressTracking = !!server.enableProgressTracking;
+    this._roots = server.roots ?? [];
+    const hasRoots = this._roots.length > 0 || !!capabilities.roots;
+    const clientCapabilities = {
+      ...capabilities,
+      elicitation: {},
+      // Auto-enable roots capability if roots are provided
+      ...hasRoots ? { roots: { listChanged: true, ...capabilities.roots ?? {} } } : {}
+    };
     this.client = new Client(
       {
         name,
@@ -426,9 +460,13 @@ var InternalMastraMCPClient = class extends MastraBase {
       }
     );
     this.setupLogging();
+    if (hasRoots) {
+      this.setupRootsHandler();
+    }
     this.resources = new ResourceClientActions({ client: this, logger: this.logger });
     this.prompts = new PromptClientActions({ client: this, logger: this.logger });
     this.elicitation = new ElicitationClientActions({ client: this, logger: this.logger });
+    this.progress = new ProgressClientActions({ client: this, logger: this.logger });
   }
   /**
    * Log a message at the specified level
@@ -467,6 +505,63 @@ var InternalMastraMCPClient = class extends MastraBase {
       );
     }
   }
+  /**
+   * Set up handler for roots/list requests from the server.
+   *
+   * Per MCP spec (https://modelcontextprotocol.io/specification/2025-11-25/client/roots):
+   * When a server sends a roots/list request, the client responds with the configured roots.
+   */
+  setupRootsHandler() {
+    this.log("debug", "Setting up roots/list request handler");
+    this.client.setRequestHandler(ListRootsRequestSchema, async () => {
+      this.log("debug", `Responding to roots/list request with ${this._roots.length} roots`);
+      return { roots: this._roots };
+    });
+  }
+  /**
+   * Get the currently configured roots.
+   *
+   * @returns Array of configured filesystem roots
+   */
+  get roots() {
+    return [...this._roots];
+  }
+  /**
+   * Update the list of filesystem roots and notify the server.
+   *
+   * Per MCP spec, when roots change, the client sends a `notifications/roots/list_changed`
+   * notification to inform the server that it should re-fetch the roots list.
+   *
+   * @param roots - New list of filesystem roots
+   *
+   * @example
+   * ```typescript
+   * await client.setRoots([
+   *   { uri: 'file:///home/user/projects', name: 'Projects' },
+   *   { uri: 'file:///tmp', name: 'Temp' }
+   * ]);
+   * ```
+   */
+  async setRoots(roots) {
+    this.log("debug", `Updating roots to ${roots.length} entries`);
+    this._roots = [...roots];
+    await this.sendRootsListChanged();
+  }
+  /**
+   * Send a roots/list_changed notification to the server.
+   *
+   * Per MCP spec, clients that support `listChanged` MUST send this notification
+   * when the list of roots changes. The server will then call roots/list to get
+   * the updated list.
+   */
+  async sendRootsListChanged() {
+    if (!this.transport) {
+      this.log("debug", "Cannot send roots/list_changed: not connected");
+      return;
+    }
+    this.log("debug", "Sending notifications/roots/list_changed");
+    await this.client.notification({ method: "notifications/roots/list_changed" });
+  }
   async connectStdio(command) {
     this.log("debug", `Using Stdio transport for command: ${command}`);
     try {
@@ -483,7 +578,7 @@ var InternalMastraMCPClient = class extends MastraBase {
     }
   }
   async connectHttp(url) {
-    const { requestInit, eventSourceInit, authProvider } = this.serverConfig;
+    const { requestInit, eventSourceInit, authProvider, connectTimeout, fetch: fetch2 } = this.serverConfig;
     this.log("debug", `Attempting to connect to URL: ${url}`);
     let shouldTrySSE = url.pathname.endsWith(`/sse`);
     if (!shouldTrySSE) {
@@ -492,25 +587,33 @@ var InternalMastraMCPClient = class extends MastraBase {
         const streamableTransport = new StreamableHTTPClientTransport(url, {
           requestInit,
           reconnectionOptions: this.serverConfig.reconnectionOptions,
-          authProvider
+          authProvider,
+          fetch: fetch2
         });
         await this.client.connect(streamableTransport, {
-          timeout: (
-            // this is hardcoded to 3s because the long default timeout would be extremely slow for sse backwards compat (60s)
-            3e3
-          )
+          timeout: connectTimeout ?? DEFAULT_SERVER_CONNECT_TIMEOUT_MSEC
         });
         this.transport = streamableTransport;
         this.log("debug", "Successfully connected using Streamable HTTP transport.");
       } catch (error) {
         this.log("debug", `Streamable HTTP transport failed: ${error}`);
+        const status = error?.code;
+        if (status !== void 0 && !SSE_FALLBACK_STATUS_CODES.includes(status)) {
+          throw error;
+        }
         shouldTrySSE = true;
       }
     }
     if (shouldTrySSE) {
       this.log("debug", "Falling back to deprecated HTTP+SSE transport...");
       try {
-        const sseTransport = new SSEClientTransport(url, { requestInit, eventSourceInit, authProvider });
+        const sseEventSourceInit = fetch2 ? { ...eventSourceInit, fetch: fetch2 } : eventSourceInit;
+        const sseTransport = new SSEClientTransport(url, {
+          requestInit,
+          eventSourceInit: sseEventSourceInit,
+          authProvider,
+          fetch: fetch2
+        });
         await this.client.connect(sseTransport, { timeout: this.serverConfig.timeout ?? this.timeout });
         this.transport = sseTransport;
         this.log("debug", "Successfully connected using deprecated HTTP+SSE transport.");
@@ -563,14 +666,19 @@ var InternalMastraMCPClient = class extends MastraBase {
         reject(e);
       }
     });
-    asyncExitHook(
-      async () => {
-        this.log("debug", `Disconnecting MCP server during exit`);
-        await this.disconnect();
-      },
-      { wait: 5e3 }
-    );
-    process.on("SIGTERM", () => gracefulExit());
+    if (!this.exitHookUnsubscribe) {
+      this.exitHookUnsubscribe = asyncExitHook(
+        async () => {
+          this.log("debug", `Disconnecting MCP server during exit`);
+          await this.disconnect();
+        },
+        { wait: 5e3 }
+      );
+    }
+    if (!this.sigTermHandler) {
+      this.sigTermHandler = () => gracefulExit();
+      process.on("SIGTERM", this.sigTermHandler);
+    }
     this.log("debug", `Successfully connected to MCP server`);
     return this.isConnected;
   }
@@ -605,8 +713,64 @@ var InternalMastraMCPClient = class extends MastraBase {
       throw e;
     } finally {
       this.transport = void 0;
-      this.isConnected = Promise.resolve(false);
+      this.isConnected = null;
+      if (this.exitHookUnsubscribe) {
+        this.exitHookUnsubscribe();
+        this.exitHookUnsubscribe = void 0;
+      }
+      if (this.sigTermHandler) {
+        process.off("SIGTERM", this.sigTermHandler);
+        this.sigTermHandler = void 0;
+      }
+    }
+  }
+  /**
+   * Checks if an error indicates a session invalidation that requires reconnection.
+   * 
+   * Common session-related errors include:
+   * - "No valid session ID provided" (HTTP 400)
+   * - "Server not initialized" (HTTP 400)
+   * - "Not connected" (protocol state error)
+   * - Connection refused errors
+   * 
+   * @param error - The error to check
+   * @returns true if the error indicates a session problem requiring reconnection
+   * 
+   * @internal
+   */
+  isSessionError(error) {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const errorMessage = error.message.toLowerCase();
+    return errorMessage.includes("no valid session") || errorMessage.includes("session") || errorMessage.includes("server not initialized") || errorMessage.includes("not connected") || errorMessage.includes("http 400") || errorMessage.includes("http 401") || errorMessage.includes("http 403") || errorMessage.includes("econnrefused") || errorMessage.includes("fetch failed") || errorMessage.includes("connection refused");
+  }
+  /**
+   * Forces a reconnection to the MCP server by disconnecting and reconnecting.
+   * 
+   * This is useful when the session becomes invalid (e.g., after server restart)
+   * and the client needs to establish a fresh connection.
+   * 
+   * @returns Promise resolving when reconnection is complete
+   * @throws {Error} If reconnection fails
+   * 
+   * @internal
+   */
+  async forceReconnect() {
+    this.log("debug", "Forcing reconnection to MCP server...");
+    try {
+      if (this.transport) {
+        await this.transport.close();
+      }
+    } catch (e) {
+      this.log("debug", "Error during force disconnect (ignored)", {
+        error: e instanceof Error ? e.message : String(e)
+      });
     }
+    this.transport = void 0;
+    this.isConnected = null;
+    await this.connect();
+    this.log("debug", "Successfully reconnected to MCP server");
   }
   async listResources() {
     this.log("debug", `Requesting resources from MCP server`);
@@ -694,6 +858,12 @@ var InternalMastraMCPClient = class extends MastraBase {
       return handler(request.params);
     });
   }
+  setProgressNotificationHandler(handler) {
+    this.log("debug", "Setting progress notification handler");
+    this.client.setNotificationHandler(ProgressNotificationSchema, (notification) => {
+      handler(notification.params);
+    });
+  }
   async convertInputSchema(inputSchema) {
     if (isZodType(inputSchema)) {
       return inputSchema;
@@ -767,7 +937,7 @@ var InternalMastraMCPClient = class extends MastraBase {
   }
   async tools() {
     this.log("debug", `Requesting tools from MCP server`);
-    const { tools } = await this.client.listTools({ timeout: this.timeout });
+    const { tools } = await this.client.listTools({}, { timeout: this.timeout });
     const toolsRes = {};
     for (const tool of tools) {
       this.log("debug", `Processing tool: ${tool.name}`);
@@ -780,12 +950,14 @@ var InternalMastraMCPClient = class extends MastraBase {
           execute: async (input, context) => {
             const previousContext = this.currentOperationContext;
             this.currentOperationContext = context?.requestContext || null;
-            try {
-              this.log("debug", `Executing tool: ${tool.name}`, { toolArgs: input });
+            const executeToolCall = async () => {
+              this.log("debug", `Executing tool: ${tool.name}`, { toolArgs: input, runId: context?.runId });
               const res = await this.client.callTool(
                 {
                   name: tool.name,
-                  arguments: input
+                  arguments: input,
+                  // Use runId as progress token if available, otherwise generate a random UUID
+                  ...this.enableProgressTracking ? { _meta: { progressToken: context?.runId || crypto.randomUUID() } } : {}
                 },
                 CallToolResultSchema,
                 {
@@ -793,8 +965,31 @@ var InternalMastraMCPClient = class extends MastraBase {
                 }
               );
               this.log("debug", `Tool executed successfully: ${tool.name}`);
+              if (res.structuredContent !== void 0) {
+                return res.structuredContent;
+              }
               return res;
+            };
+            try {
+              return await executeToolCall();
             } catch (e) {
+              if (this.isSessionError(e)) {
+                this.log("debug", `Session error detected for tool ${tool.name}, attempting reconnection...`, {
+                  error: e instanceof Error ? e.message : String(e)
+                });
+                try {
+                  await this.forceReconnect();
+                  this.log("debug", `Retrying tool ${tool.name} after reconnection...`);
+                  return await executeToolCall();
+                } catch (reconnectError) {
+                  this.log("error", `Reconnection or retry failed for tool ${tool.name}`, {
+                    originalError: e instanceof Error ? e.message : String(e),
+                    reconnectError: reconnectError instanceof Error ? reconnectError.stack : String(reconnectError),
+                    toolArgs: input
+                  });
+                  throw e;
+                }
+              }
               this.log("error", `Error calling tool: ${tool.name}`, {
                 error: e instanceof Error ? e.stack : JSON.stringify(e, null, 2),
                 toolArgs: input
@@ -818,8 +1013,6 @@ var InternalMastraMCPClient = class extends MastraBase {
     return toolsRes;
   }
 };
-
-// src/client/configuration.ts
 var mcpClientInstances = /* @__PURE__ */ new Map();
 var MCPClient = class extends MastraBase {
   serverConfigs = {};
@@ -892,6 +1085,48 @@ To fix this you have three different options:
     this.addToInstanceCache();
     return this;
   }
+  /**
+   * Provides access to progress-related operations for tracking long-running operations.
+   *
+   * Progress tracking allows MCP servers to send updates about the status of ongoing operations,
+   * providing real-time feedback to users about task completion and current state.
+   *
+   * @example
+   * ```typescript
+   * // Set up handler for progress updates from a server
+   * await mcp.progress.onUpdate('serverName', (params) => {
+   *   console.log(`Progress: ${params.progress}%`);
+   *   console.log(`Status: ${params.message}`);
+   *   
+   *   if (params.total) {
+   *     console.log(`Completed ${params.progress} of ${params.total} items`);
+   *   }
+   * });
+   * ```
+   */
+  get progress() {
+    this.addToInstanceCache();
+    return {
+      onUpdate: async (serverName, handler) => {
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.progress.onUpdate(handler);
+        } catch (err) {
+          throw new MastraError(
+            {
+              id: "MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED",
+              domain: ErrorDomain.MCP,
+              category: ErrorCategory.THIRD_PARTY,
+              details: {
+                serverName
+              }
+            },
+            err
+          );
+        }
+      }
+    };
+  }
   /**
    * Provides access to elicitation-related operations for interactive user input collection.
    *
@@ -1580,14 +1815,204 @@ To fix this you have three different options:
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/utils/stream.js
+// src/client/oauth-provider.ts
+var InMemoryOAuthStorage = class {
+  data = /* @__PURE__ */ new Map();
+  set(key, value) {
+    this.data.set(key, value);
+  }
+  get(key) {
+    return this.data.get(key);
+  }
+  delete(key) {
+    this.data.delete(key);
+  }
+  clear() {
+    this.data.clear();
+  }
+};
+var MCPOAuthClientProvider = class {
+  _redirectUrl;
+  _clientMetadata;
+  storage;
+  onRedirect;
+  generateState;
+  _clientInfo;
+  constructor(options) {
+    this._redirectUrl = options.redirectUrl;
+    this._clientMetadata = options.clientMetadata;
+    this._clientInfo = options.clientInformation;
+    this.storage = options.storage ?? new InMemoryOAuthStorage();
+    this.onRedirect = options.onRedirectToAuthorization;
+    this.generateState = options.stateGenerator ?? (() => crypto.randomUUID());
+  }
+  /**
+   * The URL to redirect the user agent to after authorization.
+   */
+  get redirectUrl() {
+    return this._redirectUrl;
+  }
+  /**
+   * Metadata about this OAuth client.
+   */
+  get clientMetadata() {
+    return this._clientMetadata;
+  }
+  /**
+   * Returns a OAuth2 state parameter.
+   */
+  async state() {
+    return this.generateState();
+  }
+  /**
+   * Loads information about this OAuth client.
+   */
+  async clientInformation() {
+    if (this._clientInfo) {
+      return this._clientInfo;
+    }
+    const stored = await this.storage.get("client_info");
+    if (stored) {
+      try {
+        return JSON.parse(stored);
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Saves dynamically registered client information.
+   */
+  async saveClientInformation(clientInformation) {
+    this._clientInfo = clientInformation;
+    await this.storage.set("client_info", JSON.stringify(clientInformation));
+  }
+  /**
+   * Loads existing OAuth tokens.
+   */
+  async tokens() {
+    const stored = await this.storage.get("tokens");
+    if (stored) {
+      try {
+        return JSON.parse(stored);
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Stores new OAuth tokens after successful authorization.
+   */
+  async saveTokens(tokens) {
+    await this.storage.set("tokens", JSON.stringify(tokens));
+  }
+  /**
+   * Invoked to redirect the user agent to the authorization URL.
+   */
+  async redirectToAuthorization(authorizationUrl) {
+    if (this.onRedirect) {
+      await this.onRedirect(authorizationUrl);
+    } else {
+      console.info(`Authorization required. Please visit: ${authorizationUrl.toString()}`);
+    }
+  }
+  /**
+   * Saves a PKCE code verifier before redirecting to authorization.
+   */
+  async saveCodeVerifier(codeVerifier) {
+    await this.storage.set("code_verifier", codeVerifier);
+  }
+  /**
+   * Loads the PKCE code verifier for validating authorization result.
+   */
+  async codeVerifier() {
+    const verifier = await this.storage.get("code_verifier");
+    if (!verifier) {
+      throw new Error("No code verifier found. Authorization flow may not have started properly.");
+    }
+    return verifier;
+  }
+  /**
+   * Optional: Custom client authentication for token requests.
+   * Uses default behavior if not implemented.
+   */
+  async addClientAuthentication(_headers, _params, _url, _metadata) {
+  }
+  /**
+   * Invalidate credentials when server indicates they're no longer valid.
+   */
+  async invalidateCredentials(scope) {
+    switch (scope) {
+      case "all":
+        await this.storage.delete("tokens");
+        await this.storage.delete("client_info");
+        await this.storage.delete("code_verifier");
+        this._clientInfo = void 0;
+        break;
+      case "client":
+        await this.storage.delete("client_info");
+        this._clientInfo = void 0;
+        break;
+      case "tokens":
+        await this.storage.delete("tokens");
+        break;
+      case "verifier":
+        await this.storage.delete("code_verifier");
+        break;
+    }
+  }
+  /**
+   * Clear all stored OAuth data.
+   * Useful for logging out or resetting state.
+   */
+  async clear() {
+    await this.invalidateCredentials("all");
+  }
+  /**
+   * Check if the provider has valid (non-expired) tokens.
+   */
+  async hasValidTokens() {
+    const currentTokens = await this.tokens();
+    if (!currentTokens) return false;
+    if (!currentTokens.access_token) return false;
+    return true;
+  }
+};
+function createSimpleTokenProvider(accessToken, options) {
+  const tokens = {
+    access_token: accessToken,
+    token_type: options.tokenType ?? "Bearer",
+    refresh_token: options.refreshToken,
+    expires_in: options.expiresIn,
+    scope: options.scope
+  };
+  const storage = new InMemoryOAuthStorage();
+  storage.set("tokens", JSON.stringify(tokens));
+  if (options.clientInformation) {
+    storage.set("client_info", JSON.stringify(options.clientInformation));
+  }
+  return new MCPOAuthClientProvider({
+    redirectUrl: options.redirectUrl,
+    clientMetadata: options.clientMetadata,
+    clientInformation: options.clientInformation,
+    storage
+  });
+}
+
+// ../../node_modules/.pnpm/hono@4.11.3/node_modules/hono/dist/utils/stream.js
 var StreamingApi = class {
   writer;
   encoder;
   writable;
   abortSubscribers = [];
   responseReadable;
+  /**
+   * Whether the stream has been aborted.
+   */
   aborted = false;
+  /**
+   * Whether the stream has been closed normally.
+   */
   closed = false;
   constructor(writable, _readable) {
     this.writable = writable;
@@ -1639,6 +2064,10 @@ var StreamingApi = class {
   onAbort(listener) {
     this.abortSubscribers.push(listener);
   }
+  /**
+   * Abort the stream.
+   * You can call this method when stream is aborted by external event.
+   */
   abort() {
     if (!this.aborted) {
       this.aborted = true;
@@ -1647,7 +2076,7 @@ var StreamingApi = class {
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/helper/streaming/utils.js
+// ../../node_modules/.pnpm/hono@4.11.3/node_modules/hono/dist/helper/streaming/utils.js
 var isOldBunVersion = () => {
   const version = typeof Bun !== "undefined" ? Bun.version : void 0;
   if (version === void 0) {
@@ -1658,7 +2087,7 @@ var isOldBunVersion = () => {
   return result;
 };
 
-// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/utils/html.js
+// ../../node_modules/.pnpm/hono@4.11.3/node_modules/hono/dist/utils/html.js
 var HtmlEscapedCallbackPhase = {
   Stringify: 1};
 var resolveCallback = async (str, phase, preserveCallbacks, context, buffer) => {
@@ -1689,7 +2118,7 @@ var resolveCallback = async (str, phase, preserveCallbacks, context, buffer) =>
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/helper/streaming/sse.js
+// ../../node_modules/.pnpm/hono@4.11.3/node_modules/hono/dist/helper/streaming/sse.js
 var SSEStreamingApi = class extends StreamingApi {
   constructor(writable, readable) {
     super(writable, readable);
@@ -2137,7 +2566,16 @@ var MCPServer = class extends MCPServerBase {
     if (opts.prompts) {
       capabilities.prompts = { listChanged: true };
     }
-    this.server = new Server({ name: this.name, version: this.version }, { capabilities });
+    this.server = new Server(
+      {
+        name: this.name,
+        version: this.version
+      },
+      {
+        capabilities,
+        ...this.instructions ? { instructions: this.instructions } : {}
+      }
+    );
     this.logger.info(
       `Initialized MCPServer '${this.name}' v${this.version} (ID: ${this.id}) with tools: ${Object.keys(this.convertedTools).join(", ")} and resources. Capabilities: ${JSON.stringify(capabilities)}`
     );
@@ -2162,8 +2600,8 @@ var MCPServer = class extends MCPServerBase {
       }
     });
     this.elicitation = {
-      sendRequest: async (request) => {
-        return this.handleElicitationRequest(request);
+      sendRequest: async (request, options) => {
+        return this.handleElicitationRequest(request, void 0, options);
       }
     };
   }
@@ -2173,15 +2611,51 @@ var MCPServer = class extends MCPServerBase {
    *
    * @param request - The elicitation request containing message and schema
    * @param serverInstance - Optional server instance to use; defaults to main server for backward compatibility
+   * @param options - Optional request options (timeout, signal, etc.)
    * @returns Promise that resolves to the client's response
    */
-  async handleElicitationRequest(request, serverInstance) {
+  async handleElicitationRequest(request, serverInstance, options) {
     this.logger.debug(`Sending elicitation request: ${request.message}`);
     const server = serverInstance || this.server;
-    const response = await server.elicitInput(request);
+    const response = await server.elicitInput(request, options);
     this.logger.debug(`Received elicitation response: ${JSON.stringify(response)}`);
     return response;
   }
+  /**
+   * Reads and parses the JSON body from an HTTP request.
+   * If the request body was already parsed by middleware (e.g., express.json()),
+   * it uses the pre-parsed body from req.body. Otherwise, it reads from the stream.
+   *
+   * This allows the MCP server to work with Express apps that use express.json()
+   * globally without requiring special route exclusions.
+   *
+   * @param req - The incoming HTTP request
+   * @param options - Optional configuration
+   * @param options.preParsedOnly - If true, only return pre-parsed body from middleware,
+   *   returning undefined if not available. This allows the caller to fall back to
+   *   their own body reading logic (e.g., SDK's getRawBody with size limits).
+   */
+  async readJsonBody(req, options) {
+    const reqWithBody = req;
+    if (reqWithBody.body !== void 0) {
+      return reqWithBody.body;
+    }
+    if (options?.preParsedOnly) {
+      return void 0;
+    }
+    return new Promise((resolve, reject) => {
+      let data = "";
+      req.on("data", (chunk) => data += chunk);
+      req.on("end", () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (e) {
+          reject(e);
+        }
+      });
+      req.on("error", reject);
+    });
+  }
   /**
    * Creates a new Server instance configured with all handlers for HTTP sessions.
    * Each HTTP client connection gets its own Server instance to avoid routing conflicts.
@@ -2198,7 +2672,16 @@ var MCPServer = class extends MCPServerBase {
     if (this.promptOptions) {
       capabilities.prompts = { listChanged: true };
     }
-    const serverInstance = new Server({ name: this.name, version: this.version }, { capabilities });
+    const serverInstance = new Server(
+      {
+        name: this.name,
+        version: this.version
+      },
+      {
+        capabilities,
+        ...this.instructions ? { instructions: this.instructions } : {}
+      }
+    );
     this.registerHandlersOnServer(serverInstance);
     return serverInstance;
   }
@@ -2219,6 +2702,12 @@ var MCPServer = class extends MCPServerBase {
           if (tool.outputSchema) {
             toolSpec.outputSchema = tool.outputSchema.jsonSchema;
           }
+          if (tool.mcp?.annotations) {
+            toolSpec.annotations = tool.mcp.annotations;
+          }
+          if (tool.mcp?._meta) {
+            toolSpec._meta = tool.mcp._meta;
+          }
           return toolSpec;
         })
       };
@@ -2267,8 +2756,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           };
         }
         const sessionElicitation = {
-          sendRequest: async (request2) => {
-            return this.handleElicitationRequest(request2, serverInstance);
+          sendRequest: async (request2, options) => {
+            return this.handleElicitationRequest(request2, serverInstance, options);
           }
         };
         const mcpOptions = {
@@ -2568,7 +3057,16 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             `Executing agent tool '${agentToolName}' for agent '${agent.name}' with message: "${inputData.message}"`
           );
           try {
-            const response = await agent.generate(inputData.message, context);
+            const proxiedContext = context?.requestContext || new RequestContext();
+            if (context?.mcp?.extra) {
+              Object.entries(context.mcp.extra).forEach(([key, value]) => {
+                proxiedContext.set(key, value);
+              });
+            }
+            const response = await agent.generate(inputData.message, {
+              ...context ?? {},
+              requestContext: proxiedContext
+            });
             return response;
           } catch (error) {
             this.logger.error(`Error executing agent tool '${agentToolName}' for agent '${agent.name}':`, error);
@@ -2632,10 +3130,16 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             inputData
           );
           try {
-            const run2 = await workflow.createRun({ runId: context?.requestContext?.get("runId") });
+            const proxiedContext = context?.requestContext || new RequestContext();
+            if (context?.mcp?.extra) {
+              Object.entries(context.mcp.extra).forEach(([key, value]) => {
+                proxiedContext.set(key, value);
+              });
+            }
+            const run2 = await workflow.createRun({ runId: proxiedContext?.get("runId") });
             const response = await run2.start({
               inputData,
-              requestContext: context?.requestContext,
+              requestContext: proxiedContext,
               tracingContext: context?.tracingContext
             });
             return response;
@@ -2791,7 +3295,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    *
    * @example
    * ```typescript
-   * import http from 'http';
+   * import http from 'node:http';
    *
    * const httpServer = http.createServer(async (req, res) => {
    *   await server.startSSE({
@@ -2822,7 +3326,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           res.end("SSE connection not established");
           return;
         }
-        await this.sseTransport.handlePostMessage(req, res);
+        const parsedBody = await this.readJsonBody(req, { preParsedOnly: true });
+        await this.sseTransport.handlePostMessage(req, res, parsedBody);
       } else {
         this.logger.debug("Unknown path:", { path: url.pathname });
         res.writeHead(404);
@@ -2949,8 +3454,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    *
    * @example
    * ```typescript
-   * import http from 'http';
-   * import { randomUUID } from 'crypto';
+   * import http from 'node:http';
+   * import { randomUUID } from 'node:crypto';
    *
    * const httpServer = http.createServer(async (req, res) => {
    *   await server.startHTTP({
@@ -2994,7 +3499,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     httpPath,
     req,
     res,
-    options = { sessionIdGenerator: () => randomUUID() }
+    options
   }) {
     this.logger.debug(`startHTTP: Received ${req.method} request to ${url.pathname}`);
     if (url.pathname !== httpPath) {
@@ -3003,11 +3508,18 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       res.end();
       return;
     }
-    if (options?.serverless) {
-      this.logger.debug("startHTTP: Running in serverless (stateless) mode");
+    const isStatelessMode = options?.serverless || options && "sessionIdGenerator" in options && options.sessionIdGenerator === void 0;
+    if (isStatelessMode) {
+      this.logger.debug("startHTTP: Running in stateless mode (serverless or sessionIdGenerator: undefined)");
       await this.handleServerlessRequest(req, res);
       return;
     }
+    const mergedOptions = {
+      sessionIdGenerator: () => randomUUID(),
+      // default: enabled
+      ...options
+      // user-provided overrides default
+    };
     const sessionId = req.headers["mcp-session-id"];
     let transport;
     this.logger.debug(
@@ -3022,40 +3534,18 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             `startHTTP: Handling GET request for existing session ${sessionId}. Calling transport.handleRequest.`
           );
         }
-        const body = req.method === "POST" ? await new Promise((resolve, reject) => {
-          let data = "";
-          req.on("data", (chunk) => data += chunk);
-          req.on("end", () => {
-            try {
-              resolve(JSON.parse(data));
-            } catch (e) {
-              reject(e);
-            }
-          });
-          req.on("error", reject);
-        }) : void 0;
+        const body = req.method === "POST" ? await this.readJsonBody(req) : void 0;
         await transport.handleRequest(req, res, body);
       } else {
         this.logger.debug(`startHTTP: No existing Streamable HTTP session ID found. ${req.method}`);
         if (req.method === "POST") {
-          const body = await new Promise((resolve, reject) => {
-            let data = "";
-            req.on("data", (chunk) => data += chunk);
-            req.on("end", () => {
-              try {
-                resolve(JSON.parse(data));
-              } catch (e) {
-                reject(e);
-              }
-            });
-            req.on("error", reject);
-          });
+          const body = await this.readJsonBody(req);
           const { isInitializeRequest } = await import('@modelcontextprotocol/sdk/types.js');
           if (isInitializeRequest(body)) {
             this.logger.debug("startHTTP: Received Streamable HTTP initialize request, creating new transport.");
             transport = new StreamableHTTPServerTransport({
-              ...options,
-              sessionIdGenerator: () => randomUUID(),
+              ...mergedOptions,
+              sessionIdGenerator: mergedOptions.sessionIdGenerator,
               onsessioninitialized: (id) => {
                 this.streamableHTTPTransports.set(id, transport);
               }
@@ -3159,18 +3649,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
   async handleServerlessRequest(req, res) {
     try {
       this.logger.debug(`handleServerlessRequest: Received ${req.method} request`);
-      const body = req.method === "POST" ? await new Promise((resolve, reject) => {
-        let data = "";
-        req.on("data", (chunk) => data += chunk);
-        req.on("end", () => {
-          try {
-            resolve(JSON.parse(data));
-          } catch (e) {
-            reject(new Error(`Invalid JSON in request body: ${e instanceof Error ? e.message : String(e)}`));
-          }
-        });
-        req.on("error", reject);
-      }) : void 0;
+      const body = req.method === "POST" ? await this.readJsonBody(req) : void 0;
       this.logger.debug(`handleServerlessRequest: Processing ${req.method} request`, {
         method: body?.method,
         id: body?.id
@@ -3600,7 +4079,210 @@ Provided arguments: ${JSON.stringify(args, null, 2)}`,
     }
   }
 };
+function escapeHeaderValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function generateWWWAuthenticateHeader(options = {}) {
+  const params = [];
+  if (options.resourceMetadataUrl) {
+    params.push(`resource_metadata="${escapeHeaderValue(options.resourceMetadataUrl)}"`);
+  }
+  if (options.additionalParams) {
+    for (const [key, value] of Object.entries(options.additionalParams)) {
+      params.push(`${key}="${escapeHeaderValue(value)}"`);
+    }
+  }
+  if (params.length === 0) {
+    return "Bearer";
+  }
+  return `Bearer ${params.join(", ")}`;
+}
+function generateProtectedResourceMetadata(config) {
+  return {
+    resource: config.resource,
+    authorization_servers: config.authorizationServers,
+    scopes_supported: config.scopesSupported ?? ["mcp:read", "mcp:write"],
+    bearer_methods_supported: ["header"],
+    ...config.resourceName && { resource_name: config.resourceName },
+    ...config.resourceDocumentation && {
+      resource_documentation: config.resourceDocumentation
+    }
+  };
+}
+function extractBearerToken(authHeader) {
+  if (!authHeader) return void 0;
+  const prefix = "bearer ";
+  if (authHeader.length <= prefix.length) return void 0;
+  if (authHeader.slice(0, prefix.length).toLowerCase() !== prefix) return void 0;
+  const token = authHeader.slice(prefix.length).trim();
+  return token || void 0;
+}
+
+// src/server/oauth-middleware.ts
+function createOAuthMiddleware(options) {
+  const { oauth, mcpPath = "/mcp", logger } = options;
+  const protectedResourceMetadata = generateProtectedResourceMetadata(oauth);
+  const wellKnownPath = "/.well-known/oauth-protected-resource";
+  const resourceMetadataUrl = new URL(wellKnownPath, oauth.resource).toString();
+  return async function oauthMiddleware(req, res, url) {
+    logger?.debug?.(`OAuth middleware: ${req.method} ${url.pathname}`);
+    if (url.pathname === wellKnownPath && req.method === "GET") {
+      logger?.debug?.("OAuth middleware: Serving Protected Resource Metadata");
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Cache-Control": "max-age=3600",
+        "Access-Control-Allow-Origin": "*"
+      });
+      res.end(JSON.stringify(protectedResourceMetadata));
+      return { proceed: false, handled: true };
+    }
+    if (url.pathname === wellKnownPath && req.method === "OPTIONS") {
+      res.writeHead(204, {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type",
+        "Access-Control-Max-Age": "86400"
+      });
+      res.end();
+      return { proceed: false, handled: true };
+    }
+    if (!url.pathname.startsWith(mcpPath)) {
+      return { proceed: true, handled: false };
+    }
+    const authHeader = req.headers["authorization"];
+    const token = extractBearerToken(authHeader);
+    if (!token) {
+      logger?.debug?.("OAuth middleware: No bearer token provided");
+      res.writeHead(401, {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": generateWWWAuthenticateHeader({ resourceMetadataUrl })
+      });
+      res.end(
+        JSON.stringify({
+          error: "unauthorized",
+          error_description: "Bearer token required"
+        })
+      );
+      return { proceed: false, handled: true };
+    }
+    if (oauth.validateToken) {
+      logger?.debug?.("OAuth middleware: Validating token");
+      const validationResult = await oauth.validateToken(token, oauth.resource);
+      if (!validationResult.valid) {
+        logger?.debug?.(`OAuth middleware: Token validation failed: ${validationResult.error}`);
+        res.writeHead(401, {
+          "Content-Type": "application/json",
+          "WWW-Authenticate": generateWWWAuthenticateHeader({
+            resourceMetadataUrl,
+            additionalParams: {
+              error: validationResult.error || "invalid_token",
+              ...validationResult.errorDescription && {
+                error_description: validationResult.errorDescription
+              }
+            }
+          })
+        });
+        res.end(
+          JSON.stringify({
+            error: validationResult.error || "invalid_token",
+            error_description: validationResult.errorDescription || "Token validation failed"
+          })
+        );
+        return { proceed: false, handled: true, tokenValidation: validationResult };
+      }
+      logger?.debug?.("OAuth middleware: Token validated successfully");
+      return { proceed: true, handled: false, tokenValidation: validationResult };
+    }
+    logger?.debug?.("OAuth middleware: No token validation configured, accepting token");
+    return {
+      proceed: true,
+      handled: false,
+      tokenValidation: { valid: true }
+    };
+  };
+}
+function createStaticTokenValidator(validTokens) {
+  const tokenSet = new Set(validTokens);
+  return async (token) => {
+    if (tokenSet.has(token)) {
+      return { valid: true, scopes: ["mcp:read", "mcp:write"] };
+    }
+    return {
+      valid: false,
+      error: "invalid_token",
+      errorDescription: "Token not recognized"
+    };
+  };
+}
+function createIntrospectionValidator(introspectionEndpoint, clientCredentials) {
+  return async (token, resource) => {
+    try {
+      const headers = {
+        "Content-Type": "application/x-www-form-urlencoded"
+      };
+      if (clientCredentials) {
+        if (clientCredentials.clientId.includes(":")) {
+          return {
+            valid: false,
+            error: "invalid_request",
+            errorDescription: "clientId cannot contain a colon character per RFC 7617"
+          };
+        }
+        const credentials = Buffer.from(`${clientCredentials.clientId}:${clientCredentials.clientSecret}`).toString(
+          "base64"
+        );
+        headers["Authorization"] = `Basic ${credentials}`;
+      }
+      const response = await fetch(introspectionEndpoint, {
+        method: "POST",
+        headers,
+        body: new URLSearchParams({
+          token,
+          token_type_hint: "access_token"
+        })
+      });
+      if (!response.ok) {
+        return {
+          valid: false,
+          error: "server_error",
+          errorDescription: `Introspection failed: ${response.status}`
+        };
+      }
+      const data = await response.json();
+      if (!data.active) {
+        return {
+          valid: false,
+          error: "invalid_token",
+          errorDescription: "Token is not active"
+        };
+      }
+      if (data.aud) {
+        const audiences = Array.isArray(data.aud) ? data.aud : [data.aud];
+        if (!audiences.includes(resource)) {
+          return {
+            valid: false,
+            error: "invalid_token",
+            errorDescription: "Token audience does not match this resource"
+          };
+        }
+      }
+      return {
+        valid: true,
+        scopes: data.scope?.trim().split(" ").filter((s) => s !== "") || [],
+        subject: data.sub,
+        expiresAt: data.exp,
+        claims: data
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        error: "server_error",
+        errorDescription: error instanceof Error ? error.message : "Introspection failed"
+      };
+    }
+  };
+}
 
-export { MCPClient, MCPServer };
+export { InMemoryOAuthStorage, InternalMastraMCPClient, MCPClient, MCPOAuthClientProvider, MCPServer, createIntrospectionValidator, createOAuthMiddleware, createSimpleTokenProvider, createStaticTokenValidator, extractBearerToken, generateProtectedResourceMetadata, generateWWWAuthenticateHeader };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map