@mastra/mcp 0.13.3 → 0.13.4

package/dist/client/configuration.d.ts

@@ -1,24 +1,196 @@
 import { MastraBase } from '@mastra/core/base';
 import type { ElicitRequest, ElicitResult, Prompt, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 import type { MastraMCPServerDefinition } from './client.js';
+/**
+ * Configuration options for creating an MCPClient instance.
+ */
 export interface MCPClientOptions {
+    /** Optional unique identifier to prevent memory leaks when creating multiple instances with identical configurations */
     id?: string;
+    /** Map of server names to their connection configurations (stdio or HTTP-based) */
     servers: Record<string, MastraMCPServerDefinition>;
+    /** Optional global timeout in milliseconds for all servers (default: 60000ms) */
     timeout?: number;
 }
+/**
+ * MCPClient manages multiple MCP server connections and their tools in a Mastra application.
+ *
+ * This class handles connection lifecycle, tool namespacing, and provides access to tools,
+ * resources, prompts, and elicitation across all configured servers.
+ *
+ * @example
+ * ```typescript
+ * import { MCPClient } from '@mastra/mcp';
+ * import { Agent } from '@mastra/core/agent';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const mcp = new MCPClient({
+ *   servers: {
+ *     weather: {
+ *       url: new URL('http://localhost:8080/sse'),
+ *     },
+ *     stockPrice: {
+ *       command: 'npx',
+ *       args: ['tsx', 'stock-price.ts'],
+ *       env: { API_KEY: 'your-api-key' },
+ *     },
+ *   },
+ *   timeout: 30000,
+ * });
+ *
+ * const agent = new Agent({
+ *   name: 'Multi-tool Agent',
+ *   instructions: 'You have access to multiple tools.',
+ *   model: openai('gpt-4'),
+ *   tools: await mcp.getTools(),
+ * });
+ * ```
+ */
 export declare class MCPClient extends MastraBase {
     private serverConfigs;
     private id;
     private defaultTimeout;
     private mcpClientsById;
     private disconnectPromise;
+    /**
+     * 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: MCPClientOptions);
+    /**
+     * 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(): {
+        /**
+         * 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: (serverName: string, handler: (request: ElicitRequest["params"]) => Promise<ElicitResult>) => Promise<void>;
     };
+    /**
+     * 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(): {
+        /**
+         * 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: () => Promise<Record<string, Resource[]>>;
+        /**
+         * 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: () => Promise<Record<string, ResourceTemplate[]>>;
+        /**
+         * 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: (serverName: string, uri: string) => Promise<import("zod").objectOutputType<{
             _meta: import("zod").ZodOptional<import("zod").ZodObject<{}, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{}, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{}, import("zod").ZodTypeAny, "passthrough">>>;
         } & {
@@ -60,15 +232,131 @@ export declare class MCPClient extends MastraBase {
                 blob: import("zod").ZodEffects<import("zod").ZodString, string, string>;
             }>, import("zod").ZodTypeAny, "passthrough">>]>, "many">;
         }, import("zod").ZodTypeAny, "passthrough">>;
+        /**
+         * 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: (serverName: string, uri: string) => Promise<{}>;
+        /**
+         * 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: (serverName: string, uri: string) => Promise<{}>;
+        /**
+         * 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: (serverName: string, handler: (params: {
             uri: string;
         }) => void) => Promise<void>;
+        /**
+         * 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: (serverName: string, handler: () => void) => Promise<void>;
     };
+    /**
+     * 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(): {
+        /**
+         * 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: () => Promise<Record<string, Prompt[]>>;
+        /**
+         * 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: ({ serverName, name, args, version, }: {
             serverName: string;
             name: string;
@@ -143,12 +431,84 @@ export declare class MCPClient extends MastraBase {
             } | undefined;
             description?: string | undefined;
         }>;
+        /**
+         * 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: (serverName: string, handler: () => void) => Promise<void>;
     };
     private addToInstanceCache;
     private makeId;
+    /**
+     * 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);
+     * });
+     * ```
+     */
     disconnect(): Promise<void>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     getTools(): Promise<Record<string, any>>;
+    /**
+     * 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: {...} }
+     * });
+     * ```
+     */
     getToolsets(): Promise<Record<string, Record<string, any>>>;
     /**
      * @deprecated all resource actions have been moved to the this.resources object. Use this.resources.list() instead.
@@ -165,8 +525,19 @@ export declare class MCPClient extends MastraBase {
         mimeType?: string | undefined;
     }[]>>;
     /**
-     * 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(): Record<string, string>;
     private getConnectedClient;
@@ -174,17 +545,41 @@ export declare class MCPClient extends MastraBase {
     private eachClientTools;
 }
 /**
- * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use MCPClientOptions instead.
+ * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use {@link MCPClientOptions} instead.
+ *
+ * This interface has been renamed to MCPClientOptions. The API is identical.
  */
 export interface MCPConfigurationOptions {
+    /** @deprecated Use MCPClientOptions.id instead */
     id?: string;
+    /** @deprecated Use MCPClientOptions.servers instead */
     servers: Record<string, MastraMCPServerDefinition>;
+    /** @deprecated Use MCPClientOptions.timeout instead */
     timeout?: number;
 }
 /**
- * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use MCPClient instead.
+ * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use {@link MCPClient} instead.
+ *
+ * This class has been renamed to MCPClient. The API is identical but the class name changed
+ * for clarity and consistency.
+ *
+ * @example
+ * ```typescript
+ * // Old way (deprecated)
+ * const config = new MCPConfiguration({
+ *   servers: { myServer: { command: 'npx', args: ['tsx', 'server.ts'] } }
+ * });
+ *
+ * // New way (recommended)
+ * const client = new MCPClient({
+ *   servers: { myServer: { command: 'npx', args: ['tsx', 'server.ts'] } }
+ * });
+ * ```
  */
 export declare class MCPConfiguration extends MCPClient {
+    /**
+     * @deprecated Use MCPClient constructor instead
+     */
     constructor(args: MCPClientOptions);
 }
 //# sourceMappingURL=configuration.d.ts.map

package/dist/client/configuration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAI5C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAI1D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAU,SAAQ,UAAU;IACvC,OAAO,CAAC,aAAa,CAAiD;IACtE,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,iBAAiB,CAA8B;gBAE3C,IAAI,EAAE,gBAAgB;IA0ClC,IAAW,WAAW;gCAGY,MAAM,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC;MAmB7G;IAED,IAAW,SAAS;oBAGA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;yBAwB9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;2BAwBvC,MAAM,OAAO,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAmBd,MAAM,OAAO,MAAM;kCAmBjB,MAAM,OAAO,MAAM;gCAmBrB,MAAM,WAAW,CAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI;oCAkB9C,MAAM,WAAW,MAAM,IAAI;MAmBhE;IAED,IAAW,OAAO;oBAGE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;oDA6B9C;YACD,UAAU,EAAE,MAAM,CAAC;YACnB,IAAI,EAAE,MAAM,CAAC;YACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oCAmBiC,MAAM,WAAW,MAAM,IAAI;MAmBhE;IAED,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,MAAM;IAOD,UAAU;IAsBV,QAAQ;IAwBR,WAAW;IAwBxB;;OAEG;IACU,YAAY;;;;;;;;;;;IAIzB;;;OAGG;IACH,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQvC;YAEa,kBAAkB;YAyDlB,2BAA2B;YAQ3B,eAAe;CAe9B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;gBACjC,IAAI,EAAE,gBAAgB;CAMnC"}
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"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"}

package/dist/client/elicitationActions.d.ts

@@ -5,13 +5,57 @@ interface ElicitationClientActionsConfig {
     client: InternalMastraMCPClient;
     logger: IMastraLogger;
 }
+/**
+ * Client-side elicitation actions for handling interactive user input requests.
+ *
+ * Elicitation allows MCP servers to request structured information from users during
+ * tool execution. The client provides a handler that collects user input and returns
+ * it to the server.
+ */
 export declare class ElicitationClientActions {
     private readonly client;
     private readonly logger;
+    /**
+     * @internal
+     */
     constructor({ client, logger }: ElicitationClientActionsConfig);
     /**
-     * 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: (request: ElicitRequest['params']) => Promise<ElicitResult>): void;
 }

package/dist/client/elicitationActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elicitationActions.d.ts","sourceRoot":"","sources":["../../src/client/elicitationActions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD,UAAU,8BAA8B;IACtC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,8BAA8B;IAK9D;;;OAGG;IACI,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;CAG7F"}
+{"version":3,"file":"elicitationActions.d.ts","sourceRoot":"","sources":["../../src/client/elicitationActions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD,UAAU,8BAA8B;IACtC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC;;OAEG;gBACS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,8BAA8B;IAK9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACI,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;CAG7F"}

package/dist/client/promptActions.d.ts

@@ -6,23 +6,62 @@ interface PromptClientActionsConfig {
     logger: IMastraLogger;
 }
 /**
- * Client-side prompt actions for listing, getting, and subscribing to prompt changes.
+ * Client-side prompt actions for interacting with MCP server prompts.
+ *
+ * Provides methods to list, retrieve, and subscribe to prompt templates exposed by an MCP server.
+ * Prompts are reusable message templates that can be parameterized and used for AI interactions.
  */
 export declare class PromptClientActions {
     private readonly client;
     private readonly logger;
+    /**
+     * @internal
+     */
     constructor({ client, logger }: PromptClientActionsConfig);
     /**
-     * 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}`);
+     * });
+     * ```
      */
     list(): Promise<Prompt[]>;
     /**
-     * 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);
+     * ```
      */
     get({ name, args, version, }: {
         name: string;
@@ -30,8 +69,20 @@ export declare class PromptClientActions {
         version?: string;
     }): Promise<GetPromptResult>;
     /**
-     * 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));
+     * });
+     * ```
      */
     onListChanged(handler: () => void): Promise<void>;
 }

package/dist/client/promptActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promptActions.d.ts","sourceRoot":"","sources":["../../src/client/promptActions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD,UAAU,yBAAyB;IACjC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,yBAAyB;IAKzD;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBtC;;;;;;OAMG;IACU,GAAG,CAAC,EACf,IAAI,EACJ,IAAI,EACJ,OAAO,GACR,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,eAAe,CAAC;IAI5B;;;OAGG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAG/D"}
+{"version":3,"file":"promptActions.d.ts","sourceRoot":"","sources":["../../src/client/promptActions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD,UAAU,yBAAyB;IACjC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC;;OAEG;gBACS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,yBAAyB;IAKzD;;;;;;;;;;;;;;;OAeG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBtC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACU,GAAG,CAAC,EACf,IAAI,EACJ,IAAI,EACJ,OAAO,GACR,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,eAAe,CAAC;IAI5B;;;;;;;;;;;;;;;OAeG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAG/D"}