@mastra/mcp 0.10.2 → 0.10.3

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/mcp@0.10.2-alpha.1 build /home/runner/work/mastra/mastra/packages/mcp
+> @mastra/mcp@0.10.3-alpha.0 build /home/runner/work/mastra/mastra/packages/mcp
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
-CLI tsup v8.4.0
+CLI tsup v8.5.0
 TSC Build start
-TSC ⚡️ Build success in 18165ms
+TSC ⚡️ Build success in 20606ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 17929ms
+DTS ⚡️ Build success in 18907ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js 58.42 KB
-ESM ⚡️ Build success in 582ms
-CJS dist/index.cjs 58.63 KB
-CJS ⚡️ Build success in 807ms
+ESM dist/index.js 67.20 KB
+ESM ⚡️ Build success in 1481ms
+CJS dist/index.cjs 67.33 KB
+CJS ⚡️ Build success in 1481ms

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @mastra/mcp
 
+## 0.10.3
+
+### Patch Changes
+
+- fc579cd: [MASTRA-3554] Support MCP prompts for MCPServer and MCPClient
+- Updated dependencies [d1ed912]
+- Updated dependencies [f6fd25f]
+- Updated dependencies [dffb67b]
+- Updated dependencies [f1f1f1b]
+- Updated dependencies [925ab94]
+- Updated dependencies [f9816ae]
+- Updated dependencies [82090c1]
+- Updated dependencies [1b443fd]
+- Updated dependencies [ce97900]
+- Updated dependencies [f1309d3]
+- Updated dependencies [14a2566]
+- Updated dependencies [f7f8293]
+- Updated dependencies [48eddb9]
+  - @mastra/core@0.10.4
+
+## 0.10.3-alpha.0
+
+### Patch Changes
+
+- fc579cd: [MASTRA-3554] Support MCP prompts for MCPServer and MCPClient
+- Updated dependencies [f6fd25f]
+- Updated dependencies [dffb67b]
+- Updated dependencies [f1309d3]
+- Updated dependencies [f7f8293]
+  - @mastra/core@0.10.4-alpha.1
+
 ## 0.10.2
 
 ### Patch Changes

package/README.md

@@ -346,6 +346,38 @@ if (resources.weather) {
 
 The `getResources()` method handles errors gracefully - if a server fails or doesn't support resources, it will be omitted from the results without causing the entire operation to fail.
 
+## Prompts
+
+MCP servers can also expose prompts, which represent structured message templates or conversational context for agents.
+
+### Listing Prompts
+
+```typescript
+const prompts = await mcp.prompts.list();
+console.log(prompts.weather); // [ { name: 'current', ... }, ... ]
+```
+
+### Getting a Prompt and Messages
+
+```typescript
+const { prompt, messages } = await mcp.prompts.get({ serverName: 'weather', name: 'current' });
+console.log(prompt); // { name: 'current', version: 'v1', ... }
+console.log(messages); // [ { role: 'assistant', content: { type: 'text', text: '...' } }, ... ]
+```
+
+### Handling Prompt List Change Notifications
+
+```typescript
+mcp.prompts.onListChanged({
+  serverName: 'weather',
+  handler: () => {
+    // Refresh prompt list or update UI
+  },
+});
+```
+
+Prompt notifications are delivered via SSE or compatible transports. Register handlers before expecting notifications.
+
 ## SSE Authentication and Headers (Legacy Fallback)
 
 When the client falls back to using the legacy SSE (Server-Sent Events) transport and you need to include authentication or custom headers, you need to configure headers in a specific way. The standard `requestInit` headers won't work alone because SSE connections using the browser's `EventSource` API don't support custom headers directly.

package/dist/_tsup-dts-rollup.d.cts

@@ -1,8 +1,10 @@
 import { Agent } from '@mastra/core/agent';
 import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
 import type { ConvertedTool } from '@mastra/core/mcp';
+import type { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
 import type * as http from 'node:http';
 import type { IMastraLogger } from '@mastra/core/logger';
+import type { ListPromptsResult } from '@modelcontextprotocol/sdk/types.js';
 import { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
 import { MastraBase } from '@mastra/core/base';
 import { MCPServerBase } from '@mastra/core/mcp';
@@ -13,6 +15,8 @@ import type { MCPToolType } from '@mastra/core/mcp';
 import { objectInputType } from 'zod';
 import { objectOutputType } from 'zod';
 import { objectUtil } from 'zod';
+import type { Prompt } from '@modelcontextprotocol/sdk/types.js';
+import type { PromptMessage } from '@modelcontextprotocol/sdk/types.js';
 import type { Resource } from '@modelcontextprotocol/sdk/types.js';
 import type { ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 import { ResourceUpdatedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -70,6 +74,7 @@ export declare class InternalMastraMCPClient extends MastraBase {
     private transport?;
     private currentOperationContext;
     readonly resources: ResourceClientActions;
+    readonly prompts: PromptClientActions;
     constructor({ name, version, server, capabilities, timeout, }: InternalMastraMCPClientOptions);
     /**
      * Log a message at the specified level
@@ -170,6 +175,26 @@ export declare class InternalMastraMCPClient extends MastraBase {
             mimeType: z.ZodOptional<z.ZodString>;
         }, z.ZodTypeAny, "passthrough">>, "many">;
     }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Fetch the list of available prompts from the MCP server.
+     */
+    listPrompts(): Promise<ListPromptsResult>;
+    /**
+     * Get a prompt and its dynamic messages from the server.
+     * @param name The prompt name
+     * @param args Arguments for the prompt
+     * @param version (optional) The prompt version to retrieve
+     */
+    getPrompt({ name, args, version }: {
+        name: string;
+        args?: Record<string, any>;
+        version?: string;
+    }): Promise<GetPromptResult>;
+    /**
+     * Register a handler to be called when the prompt list changes on the server.
+     * Use this to refresh cached prompt lists in the client/UI if needed.
+     */
+    setPromptListChangedNotificationHandler(handler: () => void): void;
     setResourceUpdatedNotificationHandler(handler: (params: z.infer<typeof ResourceUpdatedNotificationSchema>['params']) => void): void;
     setResourceListChangedNotificationHandler(handler: () => void): void;
     private convertInputSchema;
@@ -186,10 +211,12 @@ export declare type InternalMastraMCPClientOptions = {
 
 export { LoggingLevel }
 export { LoggingLevel as LoggingLevel_alias_1 }
+export { LoggingLevel as LoggingLevel_alias_2 }
 
 declare type LogHandler = (logMessage: LogMessage) => void;
 export { LogHandler }
 export { LogHandler as LogHandler_alias_1 }
+export { LogHandler as LogHandler_alias_2 }
 
 declare interface LogMessage {
     level: LoggingLevel;
@@ -201,6 +228,7 @@ declare interface LogMessage {
 }
 export { LogMessage }
 export { LogMessage as LogMessage_alias_1 }
+export { LogMessage as LogMessage_alias_2 }
 
 /**
  * @deprecated MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead.
@@ -210,10 +238,12 @@ declare class MastraMCPClient extends InternalMastraMCPClient {
 }
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
+export { MastraMCPClient as MastraMCPClient_alias_2 }
 
 declare type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefinition;
 export { MastraMCPServerDefinition }
 export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
+export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_2 }
 
 declare class MCPClient extends MastraBase {
     private serverConfigs;
@@ -267,6 +297,55 @@ declare class MCPClient extends MastraBase {
         }) => void) => Promise<void>;
         onListChanged: (serverName: string, handler: () => void) => Promise<void>;
     };
+    get prompts(): {
+        list: () => Promise<Record<string, Prompt[]>>;
+        get: ({ serverName, name, args, version }: {
+            serverName: string;
+            name: string;
+            args?: Record<string, any>;
+            version?: string;
+        }) => Promise<{
+            [x: string]: unknown;
+            messages: {
+                [x: string]: unknown;
+                role: "user" | "assistant";
+                content: {
+                    [x: string]: unknown;
+                    type: "text";
+                    text: string;
+                } | {
+                    [x: string]: unknown;
+                    type: "image";
+                    data: string;
+                    mimeType: string;
+                } | {
+                    [x: string]: unknown;
+                    type: "audio";
+                    data: string;
+                    mimeType: string;
+                } | {
+                    [x: string]: unknown;
+                    type: "resource";
+                    resource: {
+                        [x: string]: unknown;
+                        text: string;
+                        uri: string;
+                        mimeType?: string | undefined;
+                    } | {
+                        [x: string]: unknown;
+                        uri: string;
+                        blob: string;
+                        mimeType?: string | undefined;
+                    };
+                };
+            }[];
+            description?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        }>;
+        onListChanged: (serverName: string, handler: () => void) => Promise<void>;
+    };
     private addToInstanceCache;
     private makeId;
     disconnect(): Promise<void>;
@@ -277,8 +356,8 @@ declare class MCPClient extends MastraBase {
      */
     getResources(): Promise<Record<string, {
         [x: string]: unknown;
-        uri: string;
         name: string;
+        uri: string;
         description?: string | undefined;
         mimeType?: string | undefined;
     }[]>>;
@@ -293,6 +372,7 @@ declare class MCPClient extends MastraBase {
 }
 export { MCPClient }
 export { MCPClient as MCPClient_alias_1 }
+export { MCPClient as MCPClient_alias_2 }
 
 declare interface MCPClientOptions {
     id?: string;
@@ -301,6 +381,7 @@ declare interface MCPClientOptions {
 }
 export { MCPClientOptions }
 export { MCPClientOptions as MCPClientOptions_alias_1 }
+export { MCPClientOptions as MCPClientOptions_alias_2 }
 
 /**
  * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use MCPClient instead.
@@ -310,6 +391,7 @@ declare class MCPConfiguration extends MCPClient {
 }
 export { MCPConfiguration }
 export { MCPConfiguration as MCPConfiguration_alias_1 }
+export { MCPConfiguration as MCPConfiguration_alias_2 }
 
 /**
  * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use MCPClientOptions instead.
@@ -321,6 +403,7 @@ declare interface MCPConfigurationOptions {
 }
 export { MCPConfigurationOptions }
 export { MCPConfigurationOptions as MCPConfigurationOptions_alias_1 }
+export { MCPConfigurationOptions as MCPConfigurationOptions_alias_2 }
 
 declare class MCPServer extends MCPServerBase {
     private server;
@@ -335,11 +418,16 @@ declare class MCPServer extends MCPServerBase {
     private listResourceTemplatesHandlerIsRegistered;
     private subscribeResourceHandlerIsRegistered;
     private unsubscribeResourceHandlerIsRegistered;
+    private listPromptsHandlerIsRegistered;
+    private getPromptHandlerIsRegistered;
     private definedResources?;
     private definedResourceTemplates?;
     private resourceOptions?;
+    private definedPrompts?;
+    private promptOptions?;
     private subscriptions;
     readonly resources: ServerResourceActions;
+    readonly prompts: ServerPromptActions;
     /**
      * Get the current stdio transport.
      */
@@ -366,6 +454,7 @@ declare class MCPServer extends MCPServerBase {
      */
     constructor(opts: MCPServerConfig & {
         resources?: MCPServerResources;
+        prompts?: MCPServerPrompts;
     });
     private convertAgentsToTools;
     private convertWorkflowsToTools;
@@ -406,6 +495,14 @@ declare class MCPServer extends MCPServerBase {
      * Register the UnsubscribeResource handler.
      */
     private registerUnsubscribeResourceHandler;
+    /**
+     * Register the ListPrompts handler.
+     */
+    private registerListPromptsHandler;
+    /**
+     * Register the GetPrompt handler.
+     */
+    private registerGetPromptHandler;
     /**
      * Start the MCP server using stdio transport (for Windsurf integration).
      */
@@ -509,9 +606,27 @@ declare class MCPServer extends MCPServerBase {
 }
 export { MCPServer }
 export { MCPServer as MCPServer_alias_1 }
+export { MCPServer as MCPServer_alias_2 }
 
 export declare const mcpServerName = "firecrawl-mcp-fixture";
 
+declare type MCPServerPromptMessagesCallback = ({ name, version, args, }: {
+    name: string;
+    version?: string;
+    args?: any;
+}) => Promise<PromptMessage[]>;
+export { MCPServerPromptMessagesCallback }
+export { MCPServerPromptMessagesCallback as MCPServerPromptMessagesCallback_alias_1 }
+export { MCPServerPromptMessagesCallback as MCPServerPromptMessagesCallback_alias_2 }
+
+declare type MCPServerPrompts = {
+    listPrompts: () => Promise<Prompt[]>;
+    getPromptMessages?: MCPServerPromptMessagesCallback;
+};
+export { MCPServerPrompts }
+export { MCPServerPrompts as MCPServerPrompts_alias_1 }
+export { MCPServerPrompts as MCPServerPrompts_alias_2 }
+
 declare type MCPServerResourceContent = {
     text?: string;
 } | {
@@ -519,12 +634,14 @@ declare type MCPServerResourceContent = {
 };
 export { MCPServerResourceContent }
 export { MCPServerResourceContent as MCPServerResourceContent_alias_1 }
+export { MCPServerResourceContent as MCPServerResourceContent_alias_2 }
 
 declare type MCPServerResourceContentCallback = ({ uri, }: {
     uri: string;
 }) => Promise<MCPServerResourceContent | MCPServerResourceContent[]>;
 export { MCPServerResourceContentCallback }
 export { MCPServerResourceContentCallback as MCPServerResourceContentCallback_alias_1 }
+export { MCPServerResourceContentCallback as MCPServerResourceContentCallback_alias_2 }
 
 declare type MCPServerResources = {
     listResources: () => Promise<Resource[]>;
@@ -533,9 +650,47 @@ declare type MCPServerResources = {
 };
 export { MCPServerResources }
 export { MCPServerResources as MCPServerResources_alias_1 }
+export { MCPServerResources as MCPServerResources_alias_2 }
+
+/**
+ * Client-side prompt actions for listing, getting, and subscribing to prompt changes.
+ */
+export declare class PromptClientActions {
+    private readonly client;
+    private readonly logger;
+    constructor({ client, logger }: PromptClientActionsConfig);
+    /**
+     * Get all prompts from the connected MCP server.
+     * @returns A list of prompts with their versions.
+     */
+    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.
+     */
+    get({ name, args, version }: {
+        name: string;
+        args?: Record<string, any>;
+        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.
+     */
+    onListChanged(handler: () => void): Promise<void>;
+}
+
+declare interface PromptClientActionsConfig {
+    client: InternalMastraMCPClient;
+    logger: IMastraLogger;
+}
 
 export { Resource }
 export { Resource as Resource_alias_1 }
+export { Resource as Resource_alias_2 }
 
 export declare class ResourceClientActions {
     private readonly client;
@@ -622,6 +777,7 @@ declare interface ResourceClientActionsConfig {
 
 export { ResourceTemplate }
 export { ResourceTemplate as ResourceTemplate_alias_1 }
+export { ResourceTemplate as ResourceTemplate_alias_2 }
 
 export declare const server: Server<{
     method: string;
@@ -649,6 +805,24 @@ export declare const server: Server<{
 
 export declare const server_alias_1: MCPServer;
 
+export declare class ServerPromptActions {
+    private readonly getLogger;
+    private readonly getSdkServer;
+    private readonly clearDefinedPrompts;
+    constructor(dependencies: ServerPromptActionsDependencies);
+    /**
+     * 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.
+     */
+    notifyListChanged(): Promise<void>;
+}
+
+declare interface ServerPromptActionsDependencies {
+    getLogger: () => IMastraLogger;
+    getSdkServer: () => Server;
+    clearDefinedPrompts: () => void;
+}
+
 export declare class ServerResourceActions {
     private readonly getSubscriptions;
     private readonly getLogger;