@mastra/mcp 0.10.2 → 0.10.3

package/src/client/promptActions.ts

@@ -0,0 +1,70 @@
+import type { IMastraLogger } from "@mastra/core/logger";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import type { GetPromptResult, Prompt } from "@modelcontextprotocol/sdk/types.js";
+import type { InternalMastraMCPClient } from "./client";
+
+interface PromptClientActionsConfig {
+  client: InternalMastraMCPClient;
+  logger: IMastraLogger;
+}
+
+/**
+ * Client-side prompt actions for listing, getting, and subscribing to prompt changes.
+ */
+export class PromptClientActions {
+  private readonly client: InternalMastraMCPClient;
+  private readonly logger: IMastraLogger;
+
+  constructor({ client, logger }: PromptClientActionsConfig) {
+    this.client = client;
+    this.logger = logger;
+  }
+
+  /**
+   * Get all prompts from the connected MCP server.
+   * @returns A list of prompts with their versions.
+   */
+  public async list(): Promise<Prompt[]> {
+    try {
+      const response = await this.client.listPrompts();
+      if (response && response.prompts && Array.isArray(response.prompts)) {
+        return response.prompts.map((prompt) => ({ ...prompt, version: prompt.version || '' }));
+      } else {
+        this.logger.warn(`Prompts response from server ${this.client.name} did not have expected structure.`, {
+          response,
+        });
+        return [];
+      }
+    } catch (e: any) {
+      // MCP Server might not support prompts, so we return an empty array
+      if (e.code === ErrorCode.MethodNotFound) {      
+        return []
+      }
+      this.logger.error(`Error getting prompts from server ${this.client.name}`, {
+        error: e instanceof Error ? e.message : String(e),
+      });
+      throw new Error(
+        `Failed to fetch prompts from server ${this.client.name}: ${e instanceof Error ? e.stack || e.message : String(e)}`,
+      );
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public async get({name, args, version}: {name: string, args?: Record<string, any>, version?: string}): Promise<GetPromptResult> {
+    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.
+   */
+  public async onListChanged(handler: () => void): Promise<void> {
+    this.client.setPromptListChangedNotificationHandler(handler);
+  }
+}

package/src/client/resourceActions.ts

@@ -40,7 +40,6 @@ export class ResourceClientActions {
       this.logger.error(`Error getting resources from server ${this.client.name}`, {
         error: e instanceof Error ? e.message : String(e),
       });
-      console.log('errorheere', e)
       throw new Error(
         `Failed to fetch resources from server ${this.client.name}: ${e instanceof Error ? e.stack || e.message : String(e)}`,
       );
@@ -65,7 +64,6 @@ export class ResourceClientActions {
       }
     } catch (e: any) {
       // MCP Server might not support resources, so we return an empty array
-      console.log({ errorcooode: e.code })
       if (e.code === ErrorCode.MethodNotFound) {      
         return []
       }

package/src/index.ts

@@ -1,4 +1,2 @@
-export type { LoggingLevel, LogMessage, LogHandler, MastraMCPServerDefinition } from './client/client';
-export { MastraMCPClient } from './client/client';
-export * from './client/configuration';
-export * from './server/server';
+export * from './client';
+export * from './server';

package/src/server/index.ts

@@ -0,0 +1,2 @@
+export * from './server';
+export * from './types';

package/src/server/promptActions.ts

@@ -0,0 +1,37 @@
+import type { IMastraLogger } from '@mastra/core/logger';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+interface ServerPromptActionsDependencies {
+  getLogger: () => IMastraLogger;
+  getSdkServer: () => Server;
+  clearDefinedPrompts: () => void;
+}
+
+export class ServerPromptActions {
+  private readonly getLogger: () => IMastraLogger;
+  private readonly getSdkServer: () => Server;
+  private readonly clearDefinedPrompts: () => void;
+
+  constructor(dependencies: ServerPromptActionsDependencies) {
+    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.
+   */
+  public async notifyListChanged(): Promise<void> {
+    this.getLogger().info('Prompt list change externally notified. Clearing definedPrompts and sending notification.');
+    this.clearDefinedPrompts();
+    try {
+      await this.getSdkServer().sendPromptListChanged();
+    } catch (error) {
+      this.getLogger().error('Failed to send prompt list changed notification:', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+}

package/src/server/server.test.ts

@@ -13,6 +13,8 @@ import type {
   ListResourcesResult,
   ReadResourceResult,
   ListResourceTemplatesResult,
+  GetPromptResult,
+  Prompt,
 } from '@modelcontextprotocol/sdk/types.js';
 import { MockLanguageModelV1 } from 'ai/test';
 import { Hono } from 'hono';
@@ -22,7 +24,7 @@ import { weatherTool } from '../__fixtures__/tools';
 import { InternalMastraMCPClient } from '../client/client';
 import { MCPClient } from '../client/configuration';
 import { MCPServer } from './server';
-import type { MCPServerResources, MCPServerResourceContent } from './server';
+import type { MCPServerResources, MCPServerResourceContent } from './types';
 
 const PORT = 9100 + Math.floor(Math.random() * 1000);
 let server: MCPServer;
@@ -607,6 +609,227 @@ describe('MCPServer', () => {
     });
   });
 
+  describe('Prompts', () => {
+    let promptServer: MCPServer;
+    let promptInternalClient: InternalMastraMCPClient;
+    let promptHttpServer: http.Server;
+    const PROMPT_PORT = 9500 + Math.floor(Math.random() * 1000);
+
+    let currentPrompts: Prompt[] = [
+      {
+        name: 'explain-code',
+        version: 'v1',
+        description: 'Explain code v1',
+        arguments: [{ name: 'code', required: true }],
+        getMessages: async (args: any) => [
+          { role: 'user', content: { type: 'text', text: `Explain this code (v1):\n${args.code}` } },
+        ],
+      },
+      {
+        name: 'explain-code',
+        version: 'v2',
+        description: 'Explain code v2',
+        arguments: [{ name: 'code', required: true }],
+        getMessages: async (args: any) => [
+          { role: 'user', content: { type: 'text', text: `Explain this code (v2):\n${args.code}` } },
+        ],
+      },
+      {
+        name: 'summarize',
+        version: 'v1',
+        description: 'Summarize text',
+        arguments: [{ name: 'text', required: true }],
+        getMessages: async (args: any) => [
+          { role: 'user', content: { type: 'text', text: `Summarize this:\n${args.text}` } },
+        ],
+      },
+    ];
+
+    beforeAll(async () => {
+      // Register multiple versions of the same prompt
+
+      promptServer = new MCPServer({
+        name: 'PromptTestServer',
+        version: '1.0.0',
+        tools: {},
+        prompts: {
+          listPrompts: async () => currentPrompts,
+          getPromptMessages: async (params: { name: string; version?: string; args?: any }) => {
+            let prompt;
+            if (params.version) {
+              prompt = currentPrompts.find(p => p.name === params.name && p.version === params.version);
+            } else {
+              // Select the first matching name if no version is provided.
+              prompt = currentPrompts.find(p => p.name === params.name);
+            }
+            if (!prompt)
+              throw new Error(
+                `Prompt "${params.name}"${params.version ? ` (version ${params.version})` : ''} not found`,
+              );
+            return (prompt as any).getMessages(params.args);
+          },
+        },
+      });
+
+      promptHttpServer = http.createServer(async (req: http.IncomingMessage, res: http.ServerResponse) => {
+        const url = new URL(req.url || '', `http://localhost:${PROMPT_PORT}`);
+        await promptServer.startSSE({
+          url,
+          ssePath: '/sse',
+          messagePath: '/messages',
+          req,
+          res,
+        });
+      });
+      await new Promise<void>(resolve => promptHttpServer.listen(PROMPT_PORT, () => resolve()));
+      promptInternalClient = new InternalMastraMCPClient({
+        name: 'prompt-test-internal-client',
+        server: { url: new URL(`http://localhost:${PROMPT_PORT}/sse`) },
+      });
+      await promptInternalClient.connect();
+    });
+
+    afterAll(async () => {
+      await promptInternalClient.disconnect();
+      if (promptHttpServer) {
+        promptHttpServer.closeAllConnections?.();
+        await new Promise<void>((resolve, reject) => {
+          promptHttpServer.close(err => {
+            if (err) return reject(err);
+            resolve();
+          });
+        });
+      }
+      if (promptServer) {
+        await promptServer.close();
+      }
+    });
+
+    it('should send prompt list changed notification when prompts change', async () => {
+      const listChangedPromise = new Promise<void>(resolve => {
+        promptInternalClient.setPromptListChangedNotificationHandler(() => {
+          resolve();
+        });
+      });
+      await promptServer.prompts.notifyListChanged();
+
+      await expect(listChangedPromise).resolves.toBeUndefined(); // Wait for the notification
+    });
+
+    it('should list all prompts with version field', async () => {
+      const result = await promptInternalClient.listPrompts();
+      expect(result).toBeDefined();
+      expect(result.prompts).toBeInstanceOf(Array);
+      // Should contain both explain-code v1 and v2 and summarize v1
+      const explainV1 = result.prompts.find((p: Prompt) => p.name === 'explain-code' && p.version === 'v1');
+      const explainV2 = result.prompts.find((p: Prompt) => p.name === 'explain-code' && p.version === 'v2');
+      const summarizeV1 = result.prompts.find((p: Prompt) => p.name === 'summarize' && p.version === 'v1');
+      expect(explainV1).toBeDefined();
+      expect(explainV2).toBeDefined();
+      expect(summarizeV1).toBeDefined();
+    });
+
+    it('should retrieve prompt by name and version', async () => {
+      const result = await promptInternalClient.getPrompt({
+        name: 'explain-code',
+        args: { code: 'let x = 1;' },
+        version: 'v2',
+      });
+      const prompt = result.prompt as GetPromptResult;
+      expect(prompt).toBeDefined();
+      expect(prompt.name).toBe('explain-code');
+      expect(prompt.version).toBe('v2');
+
+      const messages = result.messages;
+      expect(messages).toBeDefined();
+      expect(messages.length).toBeGreaterThan(0);
+      expect(messages[0].content.text).toContain('(v2)');
+    });
+
+    it('should retrieve prompt by name and default to first version if not specified', async () => {
+      const result = await promptInternalClient.getPrompt({ name: 'explain-code', args: { code: 'let y = 2;' } });
+      expect(result.prompt).toBeDefined();
+      const prompt = result.prompt as GetPromptResult;
+      expect(prompt.name).toBe('explain-code');
+      // Should default to first version (v1)
+      expect(prompt.version).toBe('v1');
+
+      const messages = result.messages;
+      expect(messages).toBeDefined();
+      expect(messages.length).toBeGreaterThan(0);
+      expect(messages[0].content.text).toContain('(v1)');
+    });
+
+    it('should return error if prompt name/version does not exist', async () => {
+      await expect(
+        promptInternalClient.getPrompt({ name: 'explain-code', args: { code: 'foo' }, version: 'v999' }),
+      ).rejects.toThrow();
+    });
+    it('should throw error if required argument is missing', async () => {
+      await expect(
+        promptInternalClient.getPrompt({ name: 'explain-code', args: {} }), // missing 'code'
+      ).rejects.toThrow(/Missing required argument/);
+    });
+
+    it('should succeed if all required arguments are provided', async () => {
+      const result = await promptInternalClient.getPrompt({ name: 'explain-code', args: { code: 'let z = 3;' } });
+      expect(result.prompt).toBeDefined();
+      expect(result.messages[0].content.text).toContain('let z = 3;');
+    });
+    it('should allow prompts with optional arguments', async () => {
+      // Register a prompt with an optional argument
+      currentPrompts = [
+        {
+          name: 'optional-arg-prompt',
+          version: 'v1',
+          description: 'Prompt with optional argument',
+          arguments: [{ name: 'foo', required: false }],
+          getMessages: async (args: any) => [
+            { role: 'user', content: { type: 'text', text: `foo is: ${args.foo ?? 'none'}` } },
+          ],
+        },
+      ];
+      await promptServer.prompts.notifyListChanged();
+      const result = await promptInternalClient.getPrompt({ name: 'optional-arg-prompt', args: {} });
+      expect(result.prompt).toBeDefined();
+      expect(result.messages[0].content.text).toContain('foo is: none');
+    });
+    it('should retrieve prompt with no version field by name only', async () => {
+      currentPrompts = [
+        {
+          name: 'no-version',
+          description: 'Prompt without version',
+          arguments: [],
+          getMessages: async () => [{ role: 'user', content: { type: 'text', text: 'no version' } }],
+        },
+      ];
+      await promptServer.prompts.notifyListChanged();
+      const result = await promptInternalClient.getPrompt({ name: 'no-version', args: {} });
+      const prompt = result.prompt as GetPromptResult;
+      expect(prompt).toBeDefined();
+      expect(prompt.version).toBeUndefined();
+      const messages = result.messages;
+      expect(messages).toBeDefined();
+      expect(messages.length).toBeGreaterThan(0);
+      expect(messages[0].content.text).toContain('no version');
+    });
+    it('should list prompts with required fields', async () => {
+      const result = await promptInternalClient.listPrompts();
+      result.prompts.forEach((p: Prompt) => {
+        expect(p.name).toBeDefined();
+        expect(p.description).toBeDefined();
+        expect(p.arguments).toBeDefined();
+      });
+    });
+    it('should return empty list if no prompts are registered', async () => {
+      currentPrompts = [];
+      await promptServer.prompts.notifyListChanged();
+      const result = await promptInternalClient.listPrompts();
+      expect(result.prompts).toBeInstanceOf(Array);
+      expect(result.prompts.length).toBe(0);
+    });
+  });
+
   describe('MCPServer SSE transport', () => {
     let sseRes: Response | undefined;
     let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;

package/src/server/server.ts

@@ -29,32 +29,30 @@ import {
   ListResourceTemplatesRequestSchema,
   SubscribeRequestSchema,
   UnsubscribeRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  PromptSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
   ResourceContents,
   Resource,
   ResourceTemplate,
   ServerCapabilities,
+  Prompt,
 } from '@modelcontextprotocol/sdk/types.js';
 import type { SSEStreamingApi } from 'hono/streaming';
 import { streamSSE } from 'hono/streaming';
 import { SSETransport } from 'hono-mcp-server-sse-transport';
 import { z } from 'zod';
+import { ServerPromptActions } from './promptActions';
 import { ServerResourceActions } from './resourceActions';
+import type {
+  MCPServerPromptMessagesCallback,
+  MCPServerPrompts,
+  MCPServerResourceContentCallback,
+  MCPServerResources,
+} from './types';
 
-export type MCPServerResourceContentCallback = ({
-  uri,
-}: {
-  uri: string;
-}) => Promise<MCPServerResourceContent | MCPServerResourceContent[]>;
-export type MCPServerResourceContent = { text?: string } | { blob?: string };
-export type MCPServerResources = {
-  listResources: () => Promise<Resource[]>;
-  getResourceContent: MCPServerResourceContentCallback;
-  resourceTemplates?: () => Promise<ResourceTemplate[]>;
-};
-
-export type { Resource, ResourceTemplate };
 export class MCPServer extends MCPServerBase {
   private server: Server;
   private stdioTransport?: StdioServerTransport;
@@ -69,11 +67,17 @@ export class MCPServer extends MCPServerBase {
   private subscribeResourceHandlerIsRegistered: boolean = false;
   private unsubscribeResourceHandlerIsRegistered: boolean = false;
 
+  private listPromptsHandlerIsRegistered: boolean = false;
+  private getPromptHandlerIsRegistered: boolean = false;
+
   private definedResources?: Resource[];
   private definedResourceTemplates?: ResourceTemplate[];
   private resourceOptions?: MCPServerResources;
+  private definedPrompts?: Prompt[];
+  private promptOptions?: MCPServerPrompts;
   private subscriptions: Set<string> = new Set();
   public readonly resources: ServerResourceActions;
+  public readonly prompts: ServerPromptActions;
 
   /**
    * Get the current stdio transport.
@@ -114,9 +118,10 @@ export class MCPServer extends MCPServerBase {
    * Construct a new MCPServer instance.
    * @param opts - Configuration options for the server, including registry metadata.
    */
-  constructor(opts: MCPServerConfig & { resources?: MCPServerResources }) {
+  constructor(opts: MCPServerConfig & { resources?: MCPServerResources; prompts?: MCPServerPrompts }) {
     super(opts);
     this.resourceOptions = opts.resources;
+    this.promptOptions = opts.prompts;
 
     const capabilities: ServerCapabilities = {
       tools: {},
@@ -127,6 +132,10 @@ export class MCPServer extends MCPServerBase {
       capabilities.resources = { subscribe: true, listChanged: true };
     }
 
+    if (opts.prompts) {
+      capabilities.prompts = { listChanged: true };
+    }
+
     this.server = new Server({ name: this.name, version: this.version }, { capabilities });
 
     this.logger.info(
@@ -146,6 +155,13 @@ export class MCPServer extends MCPServerBase {
         this.registerListResourceTemplatesHandler();
       }
     }
+    if (opts.prompts) {
+      this.registerListPromptsHandler();
+      this.registerGetPromptHandler({
+        getPromptMessagesCallback: opts.prompts.getPromptMessages,
+      });
+    }
+
     this.resources = new ServerResourceActions({
       getSubscriptions: () => this.subscriptions,
       getLogger: () => this.logger,
@@ -157,6 +173,14 @@ export class MCPServer extends MCPServerBase {
         this.definedResourceTemplates = undefined;
       },
     });
+
+    this.prompts = new ServerPromptActions({
+      getLogger: () => this.logger,
+      getSdkServer: () => this.server,
+      clearDefinedPrompts: () => {
+        this.definedPrompts = undefined;
+      },
+    });
   }
 
   private convertAgentsToTools(
@@ -654,6 +678,107 @@ export class MCPServer extends MCPServerBase {
     });
   }
 
+  /**
+   * Register the ListPrompts handler.
+   */
+  private registerListPromptsHandler() {
+    if (this.listPromptsHandlerIsRegistered) {
+      return;
+    }
+    this.listPromptsHandlerIsRegistered = true;
+    const capturedPromptOptions = this.promptOptions;
+
+    if (!capturedPromptOptions?.listPrompts) {
+      this.logger.warn('ListPrompts capability not supported by server configuration.');
+      return;
+    }
+
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      this.logger.debug('Handling ListPrompts request');
+      if (this.definedPrompts) {
+        return {
+          prompts: this.definedPrompts?.map(p => ({ ...p, version: p.version ?? undefined })),
+        };
+      } else {
+        try {
+          const prompts = await capturedPromptOptions.listPrompts();
+          // Parse and cache the prompts
+          for (const prompt of prompts) {
+            PromptSchema.parse(prompt);
+          }
+          this.definedPrompts = prompts;
+          this.logger.debug(`Fetched and cached ${this.definedPrompts.length} prompts.`);
+          return {
+            prompts: this.definedPrompts?.map(p => ({ ...p, version: p.version ?? undefined })),
+          };
+        } catch (error) {
+          this.logger.error('Error fetching prompts via listPrompts():', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+          // Re-throw to let the MCP Server SDK handle formatting the error response
+          throw error;
+        }
+      }
+    });
+  }
+
+  /**
+   * Register the GetPrompt handler.
+   */
+  private registerGetPromptHandler({
+    getPromptMessagesCallback,
+  }: {
+    getPromptMessagesCallback?: MCPServerPromptMessagesCallback;
+  }) {
+    if (this.getPromptHandlerIsRegistered) return;
+    this.getPromptHandlerIsRegistered = true;
+    // Accept optional version parameter in prompts/get
+    this.server.setRequestHandler(
+      GetPromptRequestSchema,
+      async (request: { params: { name: string; version?: string; arguments?: any } }) => {
+        const startTime = Date.now();
+        const { name, version, arguments: args } = request.params;
+        if (!this.definedPrompts) {
+          const prompts = await this.promptOptions?.listPrompts?.();
+          if (!prompts) throw new Error('Failed to load prompts');
+          this.definedPrompts = prompts;
+        }
+        // Select prompt by name and version (if provided)
+        let prompt;
+        if (version) {
+          prompt = this.definedPrompts?.find(p => p.name === name && p.version === version);
+        } else {
+          // Select the first matching name if no version is provided.
+          prompt = this.definedPrompts?.find(p => p.name === name);
+        }
+        if (!prompt) throw new Error(`Prompt "${name}"${version ? ` (version ${version})` : ''} not found`);
+        // Validate required arguments
+        if (prompt.arguments) {
+          for (const arg of prompt.arguments) {
+            if (arg.required && (args?.[arg.name] === undefined || args?.[arg.name] === null)) {
+              throw new Error(`Missing required argument: ${arg.name}`);
+            }
+          }
+        }
+        try {
+          let messages: any[] = [];
+          if (getPromptMessagesCallback) {
+            messages = await getPromptMessagesCallback({ name, version, args });
+          }
+          const duration = Date.now() - startTime;
+          this.logger.info(
+            `Prompt '${name}'${version ? ` (version ${version})` : ''} retrieved successfully in ${duration}ms.`,
+          );
+          return { prompt, messages };
+        } catch (error) {
+          const duration = Date.now() - startTime;
+          this.logger.error(`Failed to get content for prompt '${name}' in ${duration}ms`, { error });
+          throw error;
+        }
+      },
+    );
+  }
+
   /**
    * Start the MCP server using stdio transport (for Windsurf integration).
    */

package/src/server/types.ts

@@ -0,0 +1,30 @@
+import type { Prompt, PromptMessage, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
+
+export type MCPServerResourceContentCallback = ({
+  uri,
+}: {
+  uri: string;
+}) => Promise<MCPServerResourceContent | MCPServerResourceContent[]>;
+export type MCPServerResourceContent = { text?: string } | { blob?: string };
+export type MCPServerResources = {
+  listResources: () => Promise<Resource[]>;
+  getResourceContent: MCPServerResourceContentCallback;
+  resourceTemplates?: () => Promise<ResourceTemplate[]>;
+};
+
+export type MCPServerPromptMessagesCallback = ({
+  name,
+  version,
+  args,
+}: {
+  name: string;
+  version?: string;
+  args?: any;
+}) => Promise<PromptMessage[]>;
+
+export type MCPServerPrompts = {
+  listPrompts: () => Promise<Prompt[]>;
+  getPromptMessages?: MCPServerPromptMessagesCallback;
+};
+
+export type { Resource, ResourceTemplate };