@mastra/mcp 0.13.3 → 0.13.4

package/dist/index.cjs

@@ -36,13 +36,50 @@ var equal__default = /*#__PURE__*/_interopDefault(equal);
 var ElicitationClientActions = class {
   client;
   logger;
+  /**
+   * @internal
+   */
   constructor({ client, logger }) {
     this.client = client;
     this.logger = logger;
   }
   /**
-   * Set a handler for elicitation requests.
-   * @param handler The callback function to handle the elicitation request.
+   * Sets a handler function for processing elicitation requests from the server.
+   *
+   * The handler is called when the server needs to collect user input during tool execution.
+   * The handler must return a response with action ('accept', 'decline', or 'cancel') and
+   * optional content matching the requested schema.
+   *
+   * @param handler - Callback function to handle elicitation requests
+   *
+   * @example
+   * ```typescript
+   * client.elicitation.onRequest(async (request) => {
+   *   console.log('Server message:', request.message);
+   *   console.log('Requested schema:', request.requestedSchema);
+   *
+   *   // Collect user input (e.g., via CLI prompt or UI form)
+   *   const userInput = await collectUserInput(request.requestedSchema);
+   *
+   *   return {
+   *     action: 'accept',
+   *     content: userInput
+   *   };
+   * });
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Declining an elicitation request
+   * client.elicitation.onRequest(async (request) => {
+   *   if (!shouldAcceptRequest(request)) {
+   *     return { action: 'decline' };
+   *   }
+   *
+   *   const input = await getInput();
+   *   return { action: 'accept', content: input };
+   * });
+   * ```
    */
   onRequest(handler) {
     this.client.setElicitationRequestHandler(handler);
@@ -51,13 +88,28 @@ var ElicitationClientActions = class {
 var PromptClientActions = class {
   client;
   logger;
+  /**
+   * @internal
+   */
   constructor({ client, logger }) {
     this.client = client;
     this.logger = logger;
   }
   /**
-   * Get all prompts from the connected MCP server.
-   * @returns A list of prompts with their versions.
+   * Retrieves all available prompts from the connected MCP server.
+   *
+   * Returns an empty array if the server doesn't support prompts (MethodNotFound error).
+   *
+   * @returns Promise resolving to array of prompts with their metadata
+   * @throws {Error} If fetching prompts fails (excluding MethodNotFound)
+   *
+   * @example
+   * ```typescript
+   * const prompts = await client.prompts.list();
+   * prompts.forEach(prompt => {
+   *   console.log(`${prompt.name} (v${prompt.version}): ${prompt.description}`);
+   * });
+   * ```
    */
   async list() {
     try {
@@ -83,11 +135,32 @@ var PromptClientActions = class {
     }
   }
   /**
-   * Get a specific prompt.
-   * @param name The name of the prompt to get.
-   * @param args Optional arguments for the prompt.
-   * @param version Optional version of the prompt to get.
-   * @returns The prompt content.
+   * Retrieves a specific prompt with its messages from the MCP server.
+   *
+   * Prompts can accept arguments to parameterize the template. The returned messages
+   * can be used directly in AI chat completions.
+   *
+   * @param params - Parameters for the prompt request
+   * @param params.name - Name of the prompt to retrieve
+   * @param params.args - Optional arguments to populate the prompt template
+   * @param params.version - Optional specific version of the prompt to retrieve
+   * @returns Promise resolving to the prompt result with messages
+   * @throws {Error} If fetching the prompt fails or prompt not found
+   *
+   * @example
+   * ```typescript
+   * const prompt = await client.prompts.get({
+   *   name: 'code-review',
+   *   args: {
+   *     language: 'typescript',
+   *     code: 'const x = 1;'
+   *   },
+   *   version: '1.0'
+   * });
+   *
+   * // Use prompt messages in AI completion
+   * console.log(prompt.messages);
+   * ```
    */
   async get({
     name,
@@ -97,8 +170,20 @@ var PromptClientActions = class {
     return this.client.getPrompt({ name, args, version });
   }
   /**
-   * Set a notification handler for when the list of available prompts changes.
-   * @param handler The callback function to handle the notification.
+   * Sets a notification handler for when the list of available prompts changes.
+   *
+   * The handler is called when prompts are added, removed, or modified on the server.
+   *
+   * @param handler - Callback function invoked when the prompt list changes
+   *
+   * @example
+   * ```typescript
+   * await client.prompts.onListChanged(async () => {
+   *   console.log('Prompt list changed, re-fetching...');
+   *   const prompts = await client.prompts.list();
+   *   console.log('Available prompts:', prompts.map(p => p.name));
+   * });
+   * ```
    */
   async onListChanged(handler) {
     this.client.setPromptListChangedNotificationHandler(handler);
@@ -107,13 +192,28 @@ var PromptClientActions = class {
 var ResourceClientActions = class {
   client;
   logger;
+  /**
+   * @internal
+   */
   constructor({ client, logger }) {
     this.client = client;
     this.logger = logger;
   }
   /**
-   * Get all resources from the connected MCP server.
-   * @returns A list of resources.
+   * Retrieves all available resources from the connected MCP server.
+   *
+   * Returns an empty array if the server doesn't support resources (MethodNotFound error).
+   *
+   * @returns Promise resolving to array of resources
+   * @throws {Error} If fetching resources fails (excluding MethodNotFound)
+   *
+   * @example
+   * ```typescript
+   * const resources = await client.resources.list();
+   * resources.forEach(resource => {
+   *   console.log(`${resource.name}: ${resource.uri}`);
+   * });
+   * ```
    */
   async list() {
     try {
@@ -139,8 +239,21 @@ var ResourceClientActions = class {
     }
   }
   /**
-   * Get all resource templates from the connected MCP server.
-   * @returns A list of resource templates.
+   * Retrieves all available resource templates from the connected MCP server.
+   *
+   * Resource templates are URI templates (RFC 6570) that describe dynamic resources.
+   * Returns an empty array if the server doesn't support resource templates.
+   *
+   * @returns Promise resolving to array of resource templates
+   * @throws {Error} If fetching resource templates fails (excluding MethodNotFound)
+   *
+   * @example
+   * ```typescript
+   * const templates = await client.resources.templates();
+   * templates.forEach(template => {
+   *   console.log(`${template.name}: ${template.uriTemplate}`);
+   * });
+   * ```
    */
   async templates() {
     try {
@@ -167,37 +280,92 @@ var ResourceClientActions = class {
     }
   }
   /**
-   * Read a specific resource.
-   * @param uri The URI of the resource to read.
-   * @returns The resource content.
+   * Reads the content of a specific resource from the MCP server.
+   *
+   * @param uri - URI of the resource to read (e.g., 'file://path/to/file.txt')
+   * @returns Promise resolving to the resource content
+   * @throws {Error} If reading the resource fails or resource not found
+   *
+   * @example
+   * ```typescript
+   * const result = await client.resources.read('file://data/config.json');
+   * console.log(result.contents[0].text); // Resource text content
+   * ```
    */
   async read(uri) {
     return this.client.readResource(uri);
   }
   /**
-   * Subscribe to a specific resource.
-   * @param uri The URI of the resource to subscribe to.
+   * Subscribes to updates for a specific resource.
+   *
+   * After subscribing, you'll receive notifications via the `onUpdated` handler
+   * when the resource content changes.
+   *
+   * @param uri - URI of the resource to subscribe to
+   * @returns Promise resolving when subscription is established
+   * @throws {Error} If subscription fails
+   *
+   * @example
+   * ```typescript
+   * await client.resources.subscribe('file://data/config.json');
+   * ```
    */
   async subscribe(uri) {
     return this.client.subscribeResource(uri);
   }
   /**
-   * Unsubscribe from a specific resource.
-   * @param uri The URI of the resource to unsubscribe from.
+   * Unsubscribes from updates for a specific resource.
+   *
+   * Stops receiving notifications for this resource URI.
+   *
+   * @param uri - URI of the resource to unsubscribe from
+   * @returns Promise resolving when unsubscription is complete
+   * @throws {Error} If unsubscription fails
+   *
+   * @example
+   * ```typescript
+   * await client.resources.unsubscribe('file://data/config.json');
+   * ```
    */
   async unsubscribe(uri) {
     return this.client.unsubscribeResource(uri);
   }
   /**
-   * Set a notification handler for when a specific resource is updated.
-   * @param handler The callback function to handle the notification.
+   * Sets a notification handler for when subscribed resources are updated.
+   *
+   * The handler is called whenever the server sends a resource update notification
+   * for any resource you've subscribed to.
+   *
+   * @param handler - Callback function receiving the updated resource URI
+   *
+   * @example
+   * ```typescript
+   * await client.resources.onUpdated(async (params) => {
+   *   console.log(`Resource updated: ${params.uri}`);
+   *   // Re-fetch the resource
+   *   const content = await client.resources.read(params.uri);
+   *   console.log('New content:', content);
+   * });
+   * ```
    */
   async onUpdated(handler) {
     this.client.setResourceUpdatedNotificationHandler(handler);
   }
   /**
-   * Set a notification handler for when the list of available resources changes.
-   * @param handler The callback function to handle the notification.
+   * Sets a notification handler for when the list of available resources changes.
+   *
+   * The handler is called when resources are added or removed from the server.
+   *
+   * @param handler - Callback function invoked when the resource list changes
+   *
+   * @example
+   * ```typescript
+   * await client.resources.onListChanged(async () => {
+   *   console.log('Resource list changed, re-fetching...');
+   *   const resources = await client.resources.list();
+   *   console.log('Updated resource count:', resources.length);
+   * });
+   * ```
    */
   async onListChanged(handler) {
     this.client.setResourceListChangedNotificationHandler(handler);
@@ -232,9 +400,15 @@ var InternalMastraMCPClient = class extends base.MastraBase {
   serverConfig;
   transport;
   currentOperationContext = null;
+  /** 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;
+  /**
+   * @internal
+   */
   constructor({
     name,
     version = "1.0.0",
@@ -357,6 +531,17 @@ var InternalMastraMCPClient = class extends base.MastraBase {
     }
   }
   isConnected = null;
+  /**
+   * Connects to the MCP server using the configured transport.
+   *
+   * Automatically detects transport type based on configuration (stdio vs HTTP).
+   * Safe to call multiple times - returns existing connection if already connected.
+   *
+   * @returns Promise resolving to true when connected
+   * @throws {MastraError} If connection fails
+   *
+   * @internal
+   */
   async connect() {
     if (await this.isConnected) {
       return true;
@@ -397,8 +582,13 @@ var InternalMastraMCPClient = class extends base.MastraBase {
     return this.isConnected;
   }
   /**
-   * Get the current session ID if using the Streamable HTTP transport.
-   * Returns undefined if not connected or not using Streamable HTTP.
+   * Gets the current session ID if using Streamable HTTP transport.
+   *
+   * Returns undefined if not connected or not using Streamable HTTP transport.
+   *
+   * @returns Session ID string or undefined
+   *
+   * @internal
    */
   get sessionId() {
     if (this.transport instanceof streamableHttp_js$1.StreamableHTTPClientTransport) {
@@ -650,6 +840,34 @@ var MCPClient = class extends base.MastraBase {
   defaultTimeout;
   mcpClientsById = /* @__PURE__ */ new Map();
   disconnectPromise = null;
+  /**
+   * Creates a new MCPClient instance for managing MCP server connections.
+   *
+   * The client automatically manages connection lifecycle and prevents memory leaks by
+   * caching instances with identical configurations.
+   *
+   * @param args - Configuration options
+   * @param args.id - Optional unique identifier to allow multiple instances with same config
+   * @param args.servers - Map of server names to server configurations
+   * @param args.timeout - Optional global timeout in milliseconds (default: 60000)
+   *
+   * @throws {Error} If multiple instances with identical config are created without an ID
+   *
+   * @example
+   * ```typescript
+   * const mcp = new MCPClient({
+   *   servers: {
+   *     weatherServer: {
+   *       url: new URL('http://localhost:8080/sse'),
+   *       requestInit: {
+   *         headers: { Authorization: 'Bearer token' }
+   *       }
+   *     }
+   *   },
+   *   timeout: 30000
+   * });
+   * ```
+   */
   constructor(args) {
     super({ name: "MCPClient" });
     this.defaultTimeout = args.timeout ?? protocol_js.DEFAULT_REQUEST_TIMEOUT_MSEC;
@@ -687,9 +905,48 @@ To fix this you have three different options:
     this.addToInstanceCache();
     return this;
   }
+  /**
+   * Provides access to elicitation-related operations for interactive user input collection.
+   *
+   * Elicitation allows MCP servers to request structured information from users during tool execution.
+   *
+   * @example
+   * ```typescript
+   * // Set up handler for elicitation requests from a server
+   * await mcp.elicitation.onRequest('serverName', async (request) => {
+   *   console.log(`Server requests: ${request.message}`);
+   *   console.log('Schema:', request.requestedSchema);
+   *
+   *   // Collect user input and return response
+   *   return {
+   *     action: 'accept',
+   *     content: { name: 'John Doe', email: 'john@example.com' }
+   *   };
+   * });
+   * ```
+   */
   get elicitation() {
     this.addToInstanceCache();
     return {
+      /**
+       * Sets up a handler function for elicitation requests from a specific server.
+       *
+       * The handler receives requests for user input and must return a response with
+       * action ('accept', 'decline', or 'cancel') and optional content.
+       *
+       * @param serverName - Name of the server to handle elicitation requests for
+       * @param handler - Function to handle elicitation requests
+       * @throws {MastraError} If setting up the handler fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.elicitation.onRequest('weatherServer', async (request) => {
+       *   // Prompt user for input
+       *   const userInput = await promptUser(request.requestedSchema);
+       *   return { action: 'accept', content: userInput };
+       * });
+       * ```
+       */
       onRequest: async (serverName, handler) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -710,9 +967,46 @@ To fix this you have three different options:
       }
     };
   }
+  /**
+   * Provides access to resource-related operations across all configured servers.
+   *
+   * Resources represent data exposed by MCP servers (files, database records, API responses, etc.).
+   *
+   * @example
+   * ```typescript
+   * // List all resources from all servers
+   * const allResources = await mcp.resources.list();
+   * Object.entries(allResources).forEach(([serverName, resources]) => {
+   *   console.log(`${serverName}: ${resources.length} resources`);
+   * });
+   *
+   * // Read a specific resource
+   * const content = await mcp.resources.read('weatherServer', 'file://data.json');
+   *
+   * // Subscribe to resource updates
+   * await mcp.resources.subscribe('weatherServer', 'file://data.json');
+   * await mcp.resources.onUpdated('weatherServer', async (params) => {
+   *   console.log(`Resource updated: ${params.uri}`);
+   * });
+   * ```
+   */
   get resources() {
     this.addToInstanceCache();
     return {
+      /**
+       * Lists all available resources from all configured servers.
+       *
+       * Returns a map of server names to their resource arrays. Errors for individual
+       * servers are logged but don't throw - failed servers return empty arrays.
+       *
+       * @returns Promise resolving to object mapping server names to resource arrays
+       *
+       * @example
+       * ```typescript
+       * const resources = await mcp.resources.list();
+       * console.log(resources.weatherServer); // Array of resources
+       * ```
+       */
       list: async () => {
         const allResources = {};
         for (const serverName of Object.keys(this.serverConfigs)) {
@@ -737,6 +1031,20 @@ To fix this you have three different options:
         }
         return allResources;
       },
+      /**
+       * Lists all available resource templates from all configured servers.
+       *
+       * Resource templates are URI templates (RFC 6570) describing dynamic resources.
+       * Errors for individual servers are logged but don't throw.
+       *
+       * @returns Promise resolving to object mapping server names to template arrays
+       *
+       * @example
+       * ```typescript
+       * const templates = await mcp.resources.templates();
+       * console.log(templates.weatherServer); // Array of resource templates
+       * ```
+       */
       templates: async () => {
         const allTemplates = {};
         for (const serverName of Object.keys(this.serverConfigs)) {
@@ -761,6 +1069,20 @@ To fix this you have three different options:
         }
         return allTemplates;
       },
+      /**
+       * Reads the content of a specific resource from a server.
+       *
+       * @param serverName - Name of the server to read from
+       * @param uri - URI of the resource to read
+       * @returns Promise resolving to the resource content
+       * @throws {MastraError} If reading the resource fails
+       *
+       * @example
+       * ```typescript
+       * const content = await mcp.resources.read('weatherServer', 'file://config.json');
+       * console.log(content.contents[0].text);
+       * ```
+       */
       read: async (serverName, uri) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -780,6 +1102,19 @@ To fix this you have three different options:
           );
         }
       },
+      /**
+       * Subscribes to updates for a specific resource on a server.
+       *
+       * @param serverName - Name of the server
+       * @param uri - URI of the resource to subscribe to
+       * @returns Promise resolving when subscription is established
+       * @throws {MastraError} If subscription fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.resources.subscribe('weatherServer', 'file://config.json');
+       * ```
+       */
       subscribe: async (serverName, uri) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -799,6 +1134,19 @@ To fix this you have three different options:
           );
         }
       },
+      /**
+       * Unsubscribes from updates for a specific resource on a server.
+       *
+       * @param serverName - Name of the server
+       * @param uri - URI of the resource to unsubscribe from
+       * @returns Promise resolving when unsubscription is complete
+       * @throws {MastraError} If unsubscription fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.resources.unsubscribe('weatherServer', 'file://config.json');
+       * ```
+       */
       unsubscribe: async (serverName, uri) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -818,6 +1166,22 @@ To fix this you have three different options:
           );
         }
       },
+      /**
+       * Sets a notification handler for when subscribed resources are updated on a server.
+       *
+       * @param serverName - Name of the server to monitor
+       * @param handler - Callback function receiving the updated resource URI
+       * @returns Promise resolving when handler is registered
+       * @throws {MastraError} If setting up the handler fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.resources.onUpdated('weatherServer', async (params) => {
+       *   console.log(`Resource updated: ${params.uri}`);
+       *   const content = await mcp.resources.read('weatherServer', params.uri);
+       * });
+       * ```
+       */
       onUpdated: async (serverName, handler) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -836,6 +1200,22 @@ To fix this you have three different options:
           );
         }
       },
+      /**
+       * Sets a notification handler for when the resource list changes on a server.
+       *
+       * @param serverName - Name of the server to monitor
+       * @param handler - Callback function invoked when resources are added/removed
+       * @returns Promise resolving when handler is registered
+       * @throws {MastraError} If setting up the handler fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.resources.onListChanged('weatherServer', async () => {
+       *   console.log('Resource list changed, re-fetching...');
+       *   const resources = await mcp.resources.list();
+       * });
+       * ```
+       */
       onListChanged: async (serverName, handler) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -856,9 +1236,45 @@ To fix this you have three different options:
       }
     };
   }
+  /**
+   * Provides access to prompt-related operations across all configured servers.
+   *
+   * Prompts are reusable message templates exposed by MCP servers that can be parameterized
+   * and used for AI interactions.
+   *
+   * @example
+   * ```typescript
+   * // List all prompts from all servers
+   * const allPrompts = await mcp.prompts.list();
+   * Object.entries(allPrompts).forEach(([serverName, prompts]) => {
+   *   console.log(`${serverName}: ${prompts.map(p => p.name).join(', ')}`);
+   * });
+   *
+   * // Get a specific prompt with arguments
+   * const prompt = await mcp.prompts.get({
+   *   serverName: 'weatherServer',
+   *   name: 'forecast-template',
+   *   args: { city: 'London', days: 7 }
+   * });
+   * ```
+   */
   get prompts() {
     this.addToInstanceCache();
     return {
+      /**
+       * Lists all available prompts from all configured servers.
+       *
+       * Returns a map of server names to their prompt arrays. Errors for individual
+       * servers are logged but don't throw - failed servers return empty arrays.
+       *
+       * @returns Promise resolving to object mapping server names to prompt arrays
+       *
+       * @example
+       * ```typescript
+       * const prompts = await mcp.prompts.list();
+       * console.log(prompts.weatherServer); // Array of prompts
+       * ```
+       */
       list: async () => {
         const allPrompts = {};
         for (const serverName of Object.keys(this.serverConfigs)) {
@@ -883,6 +1299,28 @@ To fix this you have three different options:
         }
         return allPrompts;
       },
+      /**
+       * Retrieves a specific prompt with its messages from a server.
+       *
+       * @param params - Parameters for the prompt request
+       * @param params.serverName - Name of the server to retrieve from
+       * @param params.name - Name of the prompt to retrieve
+       * @param params.args - Optional arguments to populate the prompt template
+       * @param params.version - Optional specific version of the prompt
+       * @returns Promise resolving to the prompt result with messages
+       * @throws {MastraError} If fetching the prompt fails
+       *
+       * @example
+       * ```typescript
+       * const prompt = await mcp.prompts.get({
+       *   serverName: 'weatherServer',
+       *   name: 'forecast',
+       *   args: { city: 'London' },
+       *   version: '1.0'
+       * });
+       * console.log(prompt.messages);
+       * ```
+       */
       get: async ({
         serverName,
         name,
@@ -907,6 +1345,22 @@ To fix this you have three different options:
           );
         }
       },
+      /**
+       * Sets a notification handler for when the prompt list changes on a server.
+       *
+       * @param serverName - Name of the server to monitor
+       * @param handler - Callback function invoked when prompts are added/removed/modified
+       * @returns Promise resolving when handler is registered
+       * @throws {MastraError} If setting up the handler fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.prompts.onListChanged('weatherServer', async () => {
+       *   console.log('Prompt list changed, re-fetching...');
+       *   const prompts = await mcp.prompts.list();
+       * });
+       * ```
+       */
       onListChanged: async (serverName, handler) => {
         try {
           const internalClient = await this.getConnectedClientForServer(serverName);
@@ -937,6 +1391,21 @@ To fix this you have three different options:
     const idNamespace = uuid.v5(`MCPClient`, uuid.v5.DNS);
     return uuid.v5(text, idNamespace);
   }
+  /**
+   * Disconnects from all MCP servers and cleans up resources.
+   *
+   * This method gracefully closes all server connections and clears internal caches.
+   * Safe to call multiple times - subsequent calls will wait for the first disconnect to complete.
+   *
+   * @example
+   * ```typescript
+   * // Cleanup on application shutdown
+   * process.on('SIGTERM', async () => {
+   *   await mcp.disconnect();
+   *   process.exit(0);
+   * });
+   * ```
+   */
   async disconnect() {
     if (this.disconnectPromise) {
       return this.disconnectPromise;
@@ -952,6 +1421,25 @@ To fix this you have three different options:
     })();
     return this.disconnectPromise;
   }
+  /**
+   * Retrieves all tools from all configured servers with namespaced names.
+   *
+   * Tool names are namespaced as `serverName_toolName` to prevent conflicts between servers.
+   * This method is intended to be passed directly to an Agent definition.
+   *
+   * @returns Object mapping namespaced tool names to tool implementations
+   * @throws {MastraError} If retrieving tools fails
+   *
+   * @example
+   * ```typescript
+   * const agent = new Agent({
+   *   name: 'Multi-tool Agent',
+   *   instructions: 'You have access to weather and stock tools.',
+   *   model: openai('gpt-4'),
+   *   tools: await mcp.getTools(), // weather_getWeather, stockPrice_getPrice
+   * });
+   * ```
+   */
   async getTools() {
     this.addToInstanceCache();
     const connectedTools = {};
@@ -973,6 +1461,28 @@ To fix this you have three different options:
     }
     return connectedTools;
   }
+  /**
+   * Returns toolsets organized by server name for dynamic tool injection.
+   *
+   * Unlike getTools(), this returns tools grouped by server without namespacing.
+   * This is intended to be passed dynamically to the generate() or stream() method.
+   *
+   * @returns Object mapping server names to their tool collections
+   * @throws {MastraError} If retrieving toolsets fails
+   *
+   * @example
+   * ```typescript
+   * const agent = new Agent({
+   *   name: 'Dynamic Agent',
+   *   instructions: 'You can use tools dynamically.',
+   *   model: openai('gpt-4'),
+   * });
+   *
+   * const response = await agent.stream(prompt, {
+   *   toolsets: await mcp.getToolsets(), // { weather: {...}, stockPrice: {...} }
+   * });
+   * ```
+   */
   async getToolsets() {
     this.addToInstanceCache();
     const connectedToolsets = {};
@@ -1001,8 +1511,19 @@ To fix this you have three different options:
     return this.resources.list();
   }
   /**
-   * Get the current session IDs for all connected MCP clients using the Streamable HTTP transport.
-   * Returns an object mapping server names to their session IDs.
+   * Gets current session IDs for all connected MCP clients using Streamable HTTP transport.
+   *
+   * Returns an object mapping server names to their session IDs. Only includes servers
+   * that are currently connected via Streamable HTTP transport.
+   *
+   * @returns Object mapping server names to session IDs
+   *
+   * @example
+   * ```typescript
+   * const sessions = mcp.sessionIds;
+   * console.log(sessions);
+   * // { weatherServer: 'abc-123', stockServer: 'def-456' }
+   * ```
    */
   get sessionIds() {
     const sessionIds = {};
@@ -1076,6 +1597,9 @@ To fix this you have three different options:
   }
 };
 var MCPConfiguration = class extends MCPClient {
+  /**
+   * @deprecated Use MCPClient constructor instead
+   */
   constructor(args) {
     super(args);
     this.logger.warn(
@@ -1334,14 +1858,27 @@ var ServerPromptActions = class {
   getLogger;
   getSdkServer;
   clearDefinedPrompts;
+  /**
+   * @internal
+   */
   constructor(dependencies) {
     this.getLogger = dependencies.getLogger;
     this.getSdkServer = dependencies.getSdkServer;
     this.clearDefinedPrompts = dependencies.clearDefinedPrompts;
   }
   /**
-   * Notifies the server that the overall list of available prompts has changed.
-   * This will clear the internal cache of defined prompts and send a list_changed notification to clients.
+   * Notifies clients that the overall list of available prompts has changed.
+   *
+   * This clears the internal prompt cache and sends a `notifications/prompts/list_changed`
+   * message to all clients, prompting them to re-fetch the prompt list.
+   *
+   * @throws {MastraError} If sending the notification fails
+   *
+   * @example
+   * ```typescript
+   * // After adding or modifying prompts
+   * await server.prompts.notifyListChanged();
+   * ```
    */
   async notifyListChanged() {
     this.getLogger().info("Prompt list change externally notified. Clearing definedPrompts and sending notification.");
@@ -1372,6 +1909,9 @@ var ServerResourceActions = class {
   getSdkServer;
   clearDefinedResources;
   clearDefinedResourceTemplates;
+  /**
+   * @internal
+   */
   constructor(dependencies) {
     this.getSubscriptions = dependencies.getSubscriptions;
     this.getLogger = dependencies.getLogger;
@@ -1380,8 +1920,20 @@ var ServerResourceActions = class {
     this.clearDefinedResourceTemplates = dependencies.clearDefinedResourceTemplates;
   }
   /**
-   * Checks if any resources have been updated.
-   * If the resource is subscribed to by clients, an update notification will be sent.
+   * Notifies subscribed clients that a specific resource has been updated.
+   *
+   * If clients are subscribed to the resource URI, they will receive a
+   * `notifications/resources/updated` message to re-fetch the resource content.
+   *
+   * @param params - Notification parameters
+   * @param params.uri - URI of the resource that was updated
+   * @throws {MastraError} If sending the notification fails
+   *
+   * @example
+   * ```typescript
+   * // After updating a file resource
+   * await server.resources.notifyUpdated({ uri: 'file://data.txt' });
+   * ```
    */
   async notifyUpdated({ uri }) {
     if (this.getSubscriptions().has(uri)) {
@@ -1412,8 +1964,18 @@ var ServerResourceActions = class {
     }
   }
   /**
-   * Notifies the server that the overall list of available resources has changed.
-   * This will clear the internal cache of defined resources and send a list_changed notification to clients.
+   * Notifies clients that the overall list of available resources has changed.
+   *
+   * This clears the internal resource cache and sends a `notifications/resources/list_changed`
+   * message to all clients, prompting them to re-fetch the resource list.
+   *
+   * @throws {MastraError} If sending the notification fails
+   *
+   * @example
+   * ```typescript
+   * // After adding a new resource to your resource handler
+   * await server.resources.notifyListChanged();
+   * ```
    */
   async notifyListChanged() {
     this.getLogger().info(
@@ -1458,36 +2020,134 @@ var MCPServer = class extends mcp.MCPServerBase {
   promptOptions;
   subscriptions = /* @__PURE__ */ new Set();
   currentLoggingLevel;
+  /**
+   * Provides methods to notify clients about resource changes.
+   *
+   * @example
+   * ```typescript
+   * // Notify that a specific resource was updated
+   * await server.resources.notifyUpdated({ uri: 'file://data.txt' });
+   *
+   * // Notify that the resource list changed
+   * await server.resources.notifyListChanged();
+   * ```
+   */
   resources;
+  /**
+   * Provides methods to notify clients about prompt changes.
+   *
+   * @example
+   * ```typescript
+   * // Notify that the prompt list changed
+   * await server.prompts.notifyListChanged();
+   * ```
+   */
   prompts;
+  /**
+   * Provides methods for interactive user input collection during tool execution.
+   *
+   * @example
+   * ```typescript
+   * // Within a tool's execute function
+   * const result = await options.elicitation.sendRequest({
+   *   message: 'Please provide your email address',
+   *   requestedSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       email: { type: 'string', format: 'email' }
+   *     },
+   *     required: ['email']
+   *   }
+   * });
+   * ```
+   */
   elicitation;
   /**
-   * Get the current stdio transport.
+   * Gets the stdio transport instance if the server was started using stdio.
+   *
+   * This is primarily for internal checks or testing purposes.
+   *
+   * @returns The stdio transport instance, or undefined if not using stdio transport
    */
   getStdioTransport() {
     return this.stdioTransport;
   }
   /**
-   * Get the current SSE transport.
+   * Gets the SSE transport instance if the server was started using SSE.
+   *
+   * This is primarily for internal checks or testing purposes.
+   *
+   * @returns The SSE transport instance, or undefined if not using SSE transport
    */
   getSseTransport() {
     return this.sseTransport;
   }
   /**
-   * Get the current SSE Hono transport.
+   * Gets the Hono SSE transport instance for a specific session.
+   *
+   * This is primarily for internal checks or testing purposes.
+   *
+   * @param sessionId - The session identifier
+   * @returns The Hono SSE transport instance, or undefined if session not found
    */
   getSseHonoTransport(sessionId) {
     return this.sseHonoTransports.get(sessionId);
   }
   /**
-   * Get the current server instance.
+   * Gets the underlying MCP SDK Server instance.
+   *
+   * This provides access to the low-level server instance for advanced use cases.
+   *
+   * @returns The Server instance from @modelcontextprotocol/sdk
    */
   getServer() {
     return this.server;
   }
   /**
-   * Construct a new MCPServer instance.
-   * @param opts - Configuration options for the server, including registry metadata.
+   * Creates a new MCPServer instance.
+   *
+   * The server exposes tools, agents, and workflows to MCP clients. Agents are automatically
+   * converted to tools named `ask_<agentKey>`, and workflows become tools named `run_<workflowKey>`.
+   *
+   * @param opts - Configuration options for the server
+   * @param opts.name - Descriptive name for the server (e.g., 'My Weather Server')
+   * @param opts.version - Semantic version of the server (e.g., '1.0.0')
+   * @param opts.tools - Object mapping tool names to tool definitions
+   * @param opts.agents - Optional object mapping agent identifiers to Agent instances
+   * @param opts.workflows - Optional object mapping workflow identifiers to Workflow instances
+   * @param opts.resources - Optional resource configuration for exposing data and content
+   * @param opts.prompts - Optional prompt configuration for exposing reusable templates
+   * @param opts.id - Optional unique identifier (generated if not provided)
+   * @param opts.description - Optional description of what the server does
+   *
+   * @example
+   * ```typescript
+   * import { MCPServer } from '@mastra/mcp';
+   * import { Agent } from '@mastra/core/agent';
+   * import { createTool } from '@mastra/core/tools';
+   * import { z } from 'zod';
+   *
+   * const myAgent = new Agent({
+   *   name: 'Helper',
+   *   description: 'A helpful assistant',
+   *   instructions: 'You are helpful.',
+   *   model: openai('gpt-4o-mini'),
+   * });
+   *
+   * const server = new MCPServer({
+   *   name: 'My Server',
+   *   version: '1.0.0',
+   *   tools: {
+   *     weatherTool: createTool({
+   *       id: 'getWeather',
+   *       description: 'Gets weather',
+   *       inputSchema: z.object({ location: z.string() }),
+   *       execute: async ({ context }) => `Sunny in ${context.location}`,
+   *     })
+   *   },
+   *   agents: { myAgent },
+   * });
+   * ```
    */
   constructor(opts) {
     super(opts);
@@ -2091,7 +2751,23 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     return allConvertedTools;
   }
   /**
-   * Start the MCP server using stdio transport (for Windsurf integration).
+   * Starts the MCP server using standard input/output (stdio) transport.
+   *
+   * This is typically used when running the server as a command-line program that MCP clients
+   * spawn as a subprocess (e.g., integration with Windsurf, Cursor, or Claude Desktop).
+   *
+   * @throws {MastraError} If the stdio connection fails
+   *
+   * @example
+   * ```typescript
+   * const server = new MCPServer({
+   *   name: 'My Server',
+   *   version: '1.0.0',
+   *   tools: { weatherTool },
+   * });
+   *
+   * await server.startStdio();
+   * ```
    */
   async startStdio() {
     this.stdioTransport = new stdio_js.StdioServerTransport();
@@ -2115,14 +2791,38 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     this.logger.info("Started MCP Server (stdio)");
   }
   /**
-   * Handles MCP-over-SSE protocol for user-provided HTTP servers.
-   * Call this from your HTTP server for both the SSE and message endpoints.
+   * Integrates the MCP server with an existing HTTP server using Server-Sent Events (SSE).
    *
-   * @param url Parsed URL of the incoming request
-   * @param ssePath Path for establishing the SSE connection (e.g. '/sse')
-   * @param messagePath Path for POSTing client messages (e.g. '/message')
-   * @param req Incoming HTTP request
-   * @param res HTTP response (must support .write/.end)
+   * Call this method from your web server's request handler for both the SSE and message paths.
+   * This enables web-based MCP clients to connect to your server.
+   *
+   * @param options - Configuration for SSE integration
+   * @param options.url - Parsed URL of the incoming request
+   * @param options.ssePath - Path for establishing SSE connection (e.g., '/sse')
+   * @param options.messagePath - Path for POSTing client messages (e.g., '/message')
+   * @param options.req - Incoming HTTP request object
+   * @param options.res - HTTP response object (must support .write/.end)
+   *
+   * @throws {MastraError} If SSE connection setup fails
+   *
+   * @example
+   * ```typescript
+   * import http from 'http';
+   *
+   * const httpServer = http.createServer(async (req, res) => {
+   *   await server.startSSE({
+   *     url: new URL(req.url || '', `http://localhost:1234`),
+   *     ssePath: '/sse',
+   *     messagePath: '/message',
+   *     req,
+   *     res,
+   *   });
+   * });
+   *
+   * httpServer.listen(1234, () => {
+   *   console.log('MCP server listening on http://localhost:1234/sse');
+   * });
+   * ```
    */
   async startSSE({ url, ssePath, messagePath, req, res }) {
     try {
@@ -2164,13 +2864,37 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     }
   }
   /**
-   * Handles MCP-over-SSE protocol for user-provided HTTP servers.
-   * Call this from your HTTP server for both the SSE and message endpoints.
+   * Integrates the MCP server with a Hono web framework using Server-Sent Events (SSE).
+   *
+   * Call this method from your Hono server's request handler for both the SSE and message paths.
+   * This enables Hono-based web applications to expose MCP servers.
+   *
+   * @param options - Configuration for Hono SSE integration
+   * @param options.url - Parsed URL of the incoming request
+   * @param options.ssePath - Path for establishing SSE connection (e.g., '/hono-sse')
+   * @param options.messagePath - Path for POSTing client messages (e.g., '/message')
+   * @param options.context - Hono context object
+   *
+   * @throws {MastraError} If Hono SSE connection setup fails
+   *
+   * @example
+   * ```typescript
+   * import { Hono } from 'hono';
+   *
+   * const app = new Hono();
+   *
+   * app.all('*', async (c) => {
+   *   const url = new URL(c.req.url);
+   *   return await server.startHonoSSE({
+   *     url,
+   *     ssePath: '/hono-sse',
+   *     messagePath: '/message',
+   *     context: c,
+   *   });
+   * });
    *
-   * @param url Parsed URL of the incoming request
-   * @param ssePath Path for establishing the SSE connection (e.g. '/sse')
-   * @param messagePath Path for POSTing client messages (e.g. '/message')
-   * @param context Incoming Hono context
+   * export default app;
+   * ```
    */
   async startHonoSSE({ url, ssePath, messagePath, context }) {
     try {
@@ -2220,14 +2944,46 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     }
   }
   /**
-   * Handles MCP-over-StreamableHTTP protocol for user-provided HTTP servers.
-   * Call this from your HTTP server for the streamable HTTP endpoint.
+   * Integrates the MCP server with an existing HTTP server using streamable HTTP transport.
    *
-   * @param url Parsed URL of the incoming request
-   * @param httpPath Path for establishing the streamable HTTP connection (e.g. '/mcp')
-   * @param req Incoming HTTP request
-   * @param res HTTP response (must support .write/.end)
-   * @param options Optional options to pass to the transport (e.g. sessionIdGenerator)
+   * This is the recommended modern transport method, providing better session management and
+   * reliability compared to SSE. Call this from your HTTP server's request handler.
+   *
+   * @param options - Configuration for HTTP integration
+   * @param options.url - Parsed URL of the incoming request
+   * @param options.httpPath - Path for the MCP endpoint (e.g., '/mcp')
+   * @param options.req - Incoming HTTP request (http.IncomingMessage)
+   * @param options.res - HTTP response object (http.ServerResponse)
+   * @param options.options - Optional transport options
+   * @param options.options.sessionIdGenerator - Function to generate unique session IDs (defaults to randomUUID)
+   * @param options.options.onsessioninitialized - Callback when a new session is initialized
+   * @param options.options.enableJsonResponse - If true, return JSON instead of SSE streaming
+   * @param options.options.eventStore - Event store for message resumability
+   *
+   * @throws {MastraError} If HTTP connection setup fails
+   *
+   * @example
+   * ```typescript
+   * import http from 'http';
+   * import { randomUUID } from 'crypto';
+   *
+   * const httpServer = http.createServer(async (req, res) => {
+   *   await server.startHTTP({
+   *     url: new URL(req.url || '', 'http://localhost:1234'),
+   *     httpPath: '/mcp',
+   *     req,
+   *     res,
+   *     options: {
+   *       sessionIdGenerator: () => randomUUID(),
+   *       onsessioninitialized: (sessionId) => {
+   *         console.log(`New MCP session: ${sessionId}`);
+   *       },
+   *     },
+   *   });
+   * });
+   *
+   * httpServer.listen(1234);
+   * ```
    */
   async startHTTP({
     url,
@@ -2378,6 +3134,27 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       }
     }
   }
+  /**
+   * Establishes the SSE connection for the MCP server.
+   *
+   * This is a lower-level method called internally by `startSSE()`. In most cases,
+   * you should use `startSSE()` instead which handles both connection establishment
+   * and message routing.
+   *
+   * @param params - Connection parameters
+   * @param params.messagePath - Path for POST requests from the client
+   * @param params.res - HTTP response object for the SSE stream
+   * @throws {MastraError} If SSE connection establishment fails
+   *
+   * @example
+   * ```typescript
+   * // Usually called internally by startSSE()
+   * await server.connectSSE({
+   *   messagePath: '/message',
+   *   res: response
+   * });
+   * ```
+   */
   async connectSSE({
     messagePath,
     res
@@ -2410,6 +3187,27 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       throw mastraError;
     }
   }
+  /**
+   * Establishes the Hono SSE connection for the MCP server.
+   *
+   * This is a lower-level method called internally by `startHonoSSE()`. In most cases,
+   * you should use `startHonoSSE()` instead which handles both connection establishment
+   * and message routing.
+   *
+   * @param params - Connection parameters
+   * @param params.messagePath - Path for POST requests from the client
+   * @param params.stream - Hono SSE streaming API object
+   * @throws {MastraError} If Hono SSE connection establishment fails
+   *
+   * @example
+   * ```typescript
+   * // Usually called internally by startHonoSSE()
+   * await server.connectHonoSSE({
+   *   messagePath: '/message',
+   *   stream: sseStream
+   * });
+   * ```
+   */
   async connectHonoSSE({ messagePath, stream: stream2 }) {
     this.logger.debug("Received SSE connection");
     const sseTransport = new SSETransport(messagePath, stream2);
@@ -2451,7 +3249,21 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     }
   }
   /**
-   * Close the MCP server and all its connections
+   * Closes the MCP server and releases all resources.
+   *
+   * This method cleanly shuts down all active transports (stdio, SSE, HTTP) and their
+   * associated connections. Call this when your application is shutting down.
+   *
+   * @throws {MastraError} If closing the server fails
+   *
+   * @example
+   * ```typescript
+   * // Graceful shutdown
+   * process.on('SIGTERM', async () => {
+   *   await server.close();
+   *   process.exit(0);
+   * });
+   * ```
    */
   async close() {
     try {
@@ -2498,8 +3310,19 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     }
   }
   /**
-   * Gets the basic information about the server, conforming to the Server schema.
-   * @returns ServerInfo object.
+   * Gets basic information about the server.
+   *
+   * Returns metadata including server ID, name, description, repository, and version details.
+   * This information conforms to the MCP Server schema.
+   *
+   * @returns Server information object
+   *
+   * @example
+   * ```typescript
+   * const info = server.getServerInfo();
+   * console.log(`${info.name} v${info.version_detail.version}`);
+   * // Output: My Weather Server v1.0.0
+   * ```
    */
   getServerInfo() {
     return {
@@ -2515,8 +3338,19 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     };
   }
   /**
-   * Gets detailed information about the server, conforming to the ServerDetail schema.
-   * @returns ServerDetailInfo object.
+   * Gets detailed information about the server including packaging and deployment metadata.
+   *
+   * Returns extended server information with package details, remotes, and deployment configurations.
+   * This information conforms to the MCP ServerDetail schema.
+   *
+   * @returns Detailed server information object
+   *
+   * @example
+   * ```typescript
+   * const detail = server.getServerDetail();
+   * console.log(detail.package_canonical); // 'npm'
+   * console.log(detail.packages); // Package installation info
+   * ```
    */
   getServerDetail() {
     return {
@@ -2527,9 +3361,21 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     };
   }
   /**
-   * Gets a list of tools provided by this MCP server, including their schemas.
-   * This leverages the same tool information used by the internal ListTools MCP request.
-   * @returns An object containing an array of tool information.
+   * Gets a list of all tools provided by this MCP server with their schemas.
+   *
+   * Returns information about all registered tools including explicit tools, agent-derived tools,
+   * and workflow-derived tools. Includes input/output schemas and tool types.
+   *
+   * @returns Object containing array of tool information
+   *
+   * @example
+   * ```typescript
+   * const toolList = server.getToolListInfo();
+   * toolList.tools.forEach(tool => {
+   *   console.log(`${tool.name}: ${tool.description}`);
+   *   console.log(`Type: ${tool.toolType || 'tool'}`);
+   * });
+   * ```
    */
   getToolListInfo() {
     this.logger.debug(`Getting tool list information for MCPServer '${this.name}'`);
@@ -2546,8 +3392,21 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
   }
   /**
    * Gets information for a specific tool provided by this MCP server.
-   * @param toolId The ID/name of the tool to retrieve.
-   * @returns Tool information (name, description, inputSchema) or undefined if not found.
+   *
+   * Returns detailed information about a single tool including its name, description, schemas, and type.
+   * Returns undefined if the tool is not found.
+   *
+   * @param toolId - The ID/name of the tool to retrieve
+   * @returns Tool information object or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const toolInfo = server.getToolInfo('getWeather');
+   * if (toolInfo) {
+   *   console.log(toolInfo.description);
+   *   console.log(toolInfo.inputSchema);
+   * }
+   * ```
    */
   getToolInfo(toolId) {
     const tool = this.convertedTools[toolId];
@@ -2566,11 +3425,25 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
   }
   /**
    * Executes a specific tool provided by this MCP server.
-   * @param toolId The ID/name of the tool to execute.
-   * @param args The arguments to pass to the tool's execute function.
-   * @param executionContext Optional context for the tool execution.
-   * @returns A promise that resolves to the result of the tool execution.
-   * @throws Error if the tool is not found, validation fails, or execution fails.
+   *
+   * This method validates the tool arguments against the input schema and executes the tool.
+   * If validation fails, returns an error object instead of throwing.
+   *
+   * @param toolId - The ID/name of the tool to execute
+   * @param args - The arguments to pass to the tool's execute function
+   * @param executionContext - Optional context including messages and toolCallId
+   * @returns Promise resolving to the tool execution result
+   * @throws {MastraError} If the tool is not found or execution fails
+   *
+   * @example
+   * ```typescript
+   * const result = await server.executeTool(
+   *   'getWeather',
+   *   { location: 'London' },
+   *   { toolCallId: 'call_123' }
+   * );
+   * console.log(result);
+   * ```
    */
   async executeTool(toolId, args, executionContext) {
     const tool = this.convertedTools[toolId];