@mastra/mcp 0.10.5-alpha.1 → 0.10.5-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp",
-  "version": "0.10.5-alpha.1",
+  "version": "0.10.5-alpha.2",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,7 @@
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5",
     "@internal/lint": "0.0.13",
-    "@mastra/core": "0.10.7-alpha.2"
+    "@mastra/core": "0.10.7-alpha.4"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting",

package/src/client/client.test.ts

@@ -5,7 +5,7 @@ import type { AddressInfo } from 'node:net';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { z } from 'zod';
 
 import { InternalMastraMCPClient } from './client.js';
@@ -208,3 +208,312 @@ describe('MastraMCPClient with Streamable HTTP', () => {
     });
   });
 });
+
+describe('MastraMCPClient - Elicitation Tests', () => {
+  let testServer: {
+    httpServer: HttpServer;
+    mcpServer: McpServer;
+    serverTransport: StreamableHTTPServerTransport;
+    baseUrl: URL;
+  };
+  let client: InternalMastraMCPClient;
+
+  beforeEach(async () => {
+    testServer = await setupTestServer(false);
+    
+    // Add elicitation-enabled tools to the test server
+    testServer.mcpServer.tool(
+      'collectUserInfo',
+      'Collects user information through elicitation',
+      {
+        message: z.string().describe('Message to show to user').default('Please provide your information'),
+      },
+      async ({ message }): Promise<CallToolResult> => {
+        const result = await testServer.mcpServer.server.elicitInput({
+          message: message,
+          requestedSchema: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', title: 'Name' },
+              email: { type: 'string', title: 'Email', format: 'email' },
+            },
+            required: ['name'],
+          },
+        });
+        
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+      },
+    );
+
+    testServer.mcpServer.tool(
+      'collectSensitiveInfo',
+      'Collects sensitive information that might be rejected',
+      {
+        message: z.string().describe('Message to show to user').default('Please provide sensitive information'),
+      },
+      async ({ message }): Promise<CallToolResult> => {
+        const result = await testServer.mcpServer.server.elicitInput({
+          message: message,
+          requestedSchema: {
+            type: 'object',
+            properties: {
+              ssn: { type: 'string', title: 'Social Security Number' },
+              creditCard: { type: 'string', title: 'Credit Card Number' },
+            },
+            required: ['ssn'],
+          },
+        });
+        
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+      },
+    );
+
+    testServer.mcpServer.tool(
+      'collectOptionalInfo',
+      'Collects optional information that might be cancelled',
+      {
+        message: z.string().describe('Message to show to user').default('Optional information request'),
+      },
+      async ({ message }): Promise<CallToolResult> => {
+        const result = await testServer.mcpServer.server.elicitInput({
+          message: message,
+          requestedSchema: {
+            type: 'object',
+            properties: {
+              feedback: { type: 'string', title: 'Feedback' },
+              rating: { type: 'number', title: 'Rating', minimum: 1, maximum: 5 },
+            },
+          },
+        });
+        
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+      },
+    );
+  });
+
+  afterEach(async () => {
+    await client?.disconnect().catch(() => {});
+    await testServer?.mcpServer.close().catch(() => {});
+    await testServer?.serverTransport.close().catch(() => {});
+    testServer?.httpServer.close();
+  });
+
+  it('should handle elicitation request with accept response', async () => {
+    const mockHandler = vi.fn(async (request) => {
+      expect(request.message).toBe('Please provide your information');
+      expect(request.requestedSchema).toBeDefined();
+      expect(request.requestedSchema.properties.name).toBeDefined();
+      expect(request.requestedSchema.properties.email).toBeDefined();
+      
+      return {
+        action: 'accept' as const,
+        content: {
+          name: 'John Doe',
+          email: 'john@example.com',
+        },
+      };
+    });
+
+    client = new InternalMastraMCPClient({
+      name: 'elicitation-accept-client',
+      server: {
+        url: testServer.baseUrl,
+      },
+    });
+    client.elicitation.onRequest(mockHandler);
+    await client.connect();
+
+    // Get the tools and call the elicitation tool
+    const tools = await client.tools();
+    const collectUserInfoTool = tools['collectUserInfo'];
+    expect(collectUserInfoTool).toBeDefined();
+
+    // Call the tool which will trigger elicitation
+    const result = await collectUserInfoTool.execute({ 
+      context: { message: 'Please provide your information' } 
+    });
+
+    console.log('result', result);
+
+    expect(mockHandler).toHaveBeenCalledTimes(1);
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe('text');
+    
+    const elicitationResult = JSON.parse(result.content[0].text);
+    expect(elicitationResult.action).toBe('accept');
+    expect(elicitationResult.content).toEqual({
+      name: 'John Doe',
+      email: 'john@example.com',
+    });
+  });
+
+  it('should handle elicitation request with reject response', async () => {
+    const mockHandler = vi.fn(async (request) => {
+      expect(request.message).toBe('Please provide sensitive information');
+      return { action: 'reject' as const };
+    });
+
+    client = new InternalMastraMCPClient({
+      name: 'elicitation-reject-client',
+      server: {
+        url: testServer.baseUrl,
+      },
+    });
+    client.elicitation.onRequest(mockHandler);
+    await client.connect();
+
+    // Get the tools and call the sensitive info tool
+    const tools = await client.tools();
+    const collectSensitiveInfoTool = tools['collectSensitiveInfo'];
+    expect(collectSensitiveInfoTool).toBeDefined();
+
+    // Call the tool which will trigger elicitation
+    const result = await collectSensitiveInfoTool.execute({ 
+      context: { message: 'Please provide sensitive information' } 
+    });
+
+    expect(mockHandler).toHaveBeenCalledTimes(1);
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe('text');
+    
+    const elicitationResult = JSON.parse(result.content[0].text);
+    expect(elicitationResult.action).toBe('reject');
+  });
+
+  it('should handle elicitation request with cancel response', async () => {
+    const mockHandler = vi.fn(async (_request) => {
+      return { action: 'cancel' as const };
+    });
+
+    client = new InternalMastraMCPClient({
+      name: 'elicitation-cancel-client',
+      server: {
+        url: testServer.baseUrl,
+      },
+    });
+    client.elicitation.onRequest(mockHandler);
+    await client.connect();
+
+    // Get the tools and call the optional info tool
+    const tools = await client.tools();
+    const collectOptionalInfoTool = tools['collectOptionalInfo'];
+    expect(collectOptionalInfoTool).toBeDefined();
+
+    // Call the tool which will trigger elicitation
+    const result = await collectOptionalInfoTool.execute({ 
+      context: { message: 'Optional information request' } 
+    });
+
+    expect(mockHandler).toHaveBeenCalledTimes(1);
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe('text');
+    
+    const elicitationResult = JSON.parse(result.content[0].text);
+    expect(elicitationResult.action).toBe('cancel');
+  });
+
+  it('should return an error when elicitation handler throws error', async () => {
+    const mockHandler = vi.fn(async (_request) => {
+      throw new Error('Handler failed');
+    });
+
+    client = new InternalMastraMCPClient({
+      name: 'elicitation-error-client',
+      server: {
+        url: testServer.baseUrl,
+      },
+    });
+    client.elicitation.onRequest(mockHandler);
+    await client.connect();
+
+    // Get the tools and call a tool that will trigger elicitation
+    const tools = await client.tools();
+    const collectUserInfoTool = tools['collectUserInfo'];
+    expect(collectUserInfoTool).toBeDefined();
+
+    // Call the tool which will trigger elicitation, handler will throw error
+    const result = await collectUserInfoTool.execute({ 
+      context: { message: 'This will cause handler to throw' } 
+    });
+
+    expect(mockHandler).toHaveBeenCalledTimes(1);
+    expect(result.content).toBeDefined();
+
+    expect(result.isError).toBe(true);
+  });
+
+  it('should return an error when client has no elicitation handler', async () => {
+    client = new InternalMastraMCPClient({
+      name: 'no-elicitation-client',
+      server: {
+        url: testServer.baseUrl,
+        // No elicitationHandler provided
+      },
+    });
+    await client.connect();
+
+    // Get the tools and call a tool that will trigger elicitation
+    const tools = await client.tools();
+    const collectUserInfoTool = tools['collectUserInfo'];
+    expect(collectUserInfoTool).toBeDefined();
+
+    // Call the tool which will trigger elicitation, should fail gracefully
+    const result = await collectUserInfoTool.execute({ 
+      context: { message: 'This should fail gracefully' } 
+    });
+
+    expect(result.content).toBeDefined();
+    expect(result.isError).toBe(true);
+  });
+
+  it('should validate elicitation request schema structure', async () => {
+    const mockHandler = vi.fn(async (request) => {
+      // Verify the request has the expected structure
+      expect(request).toHaveProperty('message');
+      expect(request).toHaveProperty('requestedSchema');
+      expect(typeof request.message).toBe('string');
+      expect(typeof request.requestedSchema).toBe('object');
+      expect(request.requestedSchema).toHaveProperty('type', 'object');
+      expect(request.requestedSchema).toHaveProperty('properties');
+
+      return {
+        action: 'accept' as const,
+        content: { validated: true },
+      };
+    });
+
+    client = new InternalMastraMCPClient({
+      name: 'schema-validation-client',
+      server: {
+        url: testServer.baseUrl,
+      },
+    });
+    client.elicitation.onRequest(mockHandler);
+    await client.connect();
+
+    // Get the tools and call a tool that will trigger elicitation
+    const tools = await client.tools();
+    const collectUserInfoTool = tools['collectUserInfo'];
+    expect(collectUserInfoTool).toBeDefined();
+
+    // Call the tool which will trigger elicitation with schema validation
+    const result = await collectUserInfoTool.execute({ 
+      context: { message: 'Schema validation test' } 
+    });
+
+    console.log('result', result);
+
+    expect(mockHandler).toHaveBeenCalledTimes(1);
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe('text');
+    
+    const elicitationResultText = result.content[0].text;
+    expect(elicitationResultText).toContain('Elicitation response content does not match requested schema');
+  });
+});

package/src/client/client.ts

@@ -14,6 +14,8 @@ import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/p
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type {
   ClientCapabilities,
+  ElicitRequest,
+  ElicitResult,
   GetPromptResult,
   ListPromptsResult,
   LoggingLevel,
@@ -28,12 +30,14 @@ import {
   ListPromptsResultSchema,
   GetPromptResultSchema,
   PromptListChangedNotificationSchema,
+  ElicitRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 
 import { asyncExitHook, gracefulExit } from 'exit-hook';
 import { z } from 'zod';
 import { convertJsonSchemaToZod } from 'zod-from-json-schema';
 import type { JSONSchema } from 'zod-from-json-schema';
+import { ElicitationClientActions } from './elicitationActions';
 import { PromptClientActions } from './promptActions';
 import { ResourceClientActions } from './resourceActions';
 
@@ -51,6 +55,9 @@ export interface LogMessage {
 
 export type LogHandler = (logMessage: LogMessage) => void;
 
+// Elicitation handler type
+export type ElicitationHandler = (request: ElicitRequest['params']) => Promise<ElicitResult>;
+
 // Base options common to all server definitions
 type BaseServerOptions = {
   logger?: LogHandler;
@@ -130,7 +137,7 @@ export class InternalMastraMCPClient extends MastraBase {
   private currentOperationContext: RuntimeContext | null = null;
   public readonly resources: ResourceClientActions;
   public readonly prompts: PromptClientActions;
-
+  public readonly elicitation: ElicitationClientActions;
   constructor({
     name,
     version = '1.0.0',
@@ -145,21 +152,25 @@ export class InternalMastraMCPClient extends MastraBase {
     this.enableServerLogs = server.enableServerLogs ?? true;
     this.serverConfig = server;
 
+    const clientCapabilities = { ...capabilities, elicitation: {} };
+
     this.client = new Client(
       {
         name,
         version,
       },
       {
-        capabilities,
+        capabilities: clientCapabilities,
       },
     );
 
     // Set up log message capturing
     this.setupLogging();
 
+
     this.resources = new ResourceClientActions({ client: this, logger: this.logger });
     this.prompts = new PromptClientActions({ client: this, logger: this.logger });
+    this.elicitation = new ElicitationClientActions({ client: this, logger: this.logger });
   }
 
   /**
@@ -450,6 +461,14 @@ export class InternalMastraMCPClient extends MastraBase {
     });
   }
 
+  setElicitationRequestHandler(handler: ElicitationHandler): void {
+    this.log('debug', 'Setting elicitation request handler');
+    this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
+      this.log('debug', `Received elicitation request: ${request.params.message}`);
+      return handler(request.params);
+    });
+  }
+
   private convertInputSchema(
     inputSchema: Awaited<ReturnType<Client['listTools']>>['tools'][0]['inputSchema'] | JSONSchema,
   ): z.ZodType {

package/src/client/configuration.ts

@@ -1,7 +1,7 @@
 import { MastraBase } from '@mastra/core/base';
 import { ErrorCategory, ErrorDomain, MastraError } from '@mastra/core/error';
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import type { Prompt, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
+import type { ElicitRequest, ElicitResult, Prompt, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 import equal from 'fast-deep-equal';
 import { v5 as uuidv5 } from 'uuid';
 import { InternalMastraMCPClient } from './client';
@@ -64,6 +64,26 @@ To fix this you have three different options:
     this.addToInstanceCache();
     return this;
   }
+  public get elicitation() {
+    this.addToInstanceCache();
+    return {
+      onRequest: async (serverName: string, handler: (request: ElicitRequest['params']) => Promise<ElicitResult>) => {
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.elicitation.onRequest(handler);
+        } catch (err) {
+          throw new MastraError({
+            id: 'MCP_CLIENT_ON_REQUEST_ELICITATION_FAILED',
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName,
+            }
+          }, err);
+        }
+      }
+    }
+  }
 
   public get resources() {
     this.addToInstanceCache();
@@ -356,7 +376,7 @@ To fix this you have three different options:
     const existingClient = this.mcpClientsById.get(name);
 
     this.logger.debug(`getConnectedClient ${name} exists: ${exists}`);
-    
+
     if (exists) {
       // This is just to satisfy Typescript since technically you could have this.mcpClientsById.set('someKey', undefined);
       // Should never reach this point basically we always create a new MastraMCPClient instance when we add to the Map.

package/src/client/elicitationActions.ts

@@ -0,0 +1,26 @@
+import type { IMastraLogger } from "@mastra/core/logger";
+import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
+import type { InternalMastraMCPClient } from "./client";
+
+interface ElicitationClientActionsConfig {
+  client: InternalMastraMCPClient;
+  logger: IMastraLogger;
+}
+
+export class ElicitationClientActions {
+  private readonly client: InternalMastraMCPClient;
+  private readonly logger: IMastraLogger;
+
+  constructor({ client, logger }: ElicitationClientActionsConfig) {
+    this.client = client;
+    this.logger = logger;
+  }
+
+  /**
+   * Set a handler for elicitation requests.
+   * @param handler The callback function to handle the elicitation request.
+   */
+  public onRequest(handler: (request: ElicitRequest['params']) => Promise<ElicitResult>): void {
+    this.client.setElicitationRequestHandler(handler);
+  }
+}

package/src/client/index.ts

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