@mastra/mcp 0.4.1-alpha.3 → 0.4.1-alpha.5

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/mcp@0.4.1-alpha.3 build /home/runner/work/mastra/mastra/packages/mcp
+> @mastra/mcp@0.4.1-alpha.5 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
 TSC Build start
-TSC ⚡️ Build success in 16742ms
+TSC ⚡️ Build success in 16456ms
 DTS Build start
 CLI Target: es2022
-Analysis will use the bundled TypeScript version 5.8.2
+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.2
+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 13642ms
+DTS ⚡️ Build success in 14716ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs 203.57 KB
-CJS ⚡️ Build success in 2723ms
-ESM dist/index.js 202.88 KB
-ESM ⚡️ Build success in 2724ms
+CJS dist/index.cjs 205.23 KB
+CJS ⚡️ Build success in 2992ms
+ESM dist/index.js 204.37 KB
+ESM ⚡️ Build success in 2992ms

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp
 
+## 0.4.1-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [e4943b8]
+- Updated dependencies [479f490]
+  - @mastra/core@0.9.1-alpha.4
+
+## 0.4.1-alpha.4
+
+### Patch Changes
+
+- 2526527: We are deprecating the MastraMCPClient class in favour of using MCPClient (formerly MCPConfiguration). MCPClient can handle 1+ MCP servers, whereas MastraMCPClient can only handle a single MCP server. Rather than having two different interfaces to use when using a single MCP vs multiple, we opted to nudge people towards using the interface that is more flexible.
+- a2ccb71: improved mcp config cache
+
 ## 0.4.1-alpha.3
 
 ### Patch Changes

package/README.md

@@ -20,37 +20,59 @@ The client automatically detects the transport type based on your server configu
 ## Usage
 
 ```typescript
-import { MastraMCPClient } from '@mastra/mcp';
+import { MCPClient } from '@mastra/mcp';
 
 // Create a client with a Stdio server
-const stdioClient = new MastraMCPClient({
-  name: 'my-stdio-client',
-  version: '1.0.0', // optional
-  server: {
-    command: 'your-mcp-server-command',
-    args: ['--your', 'args'],
-    env: { API_KEY: 'your-api-key' }, // optional environment variables
+const stdioClient = new MCPClient({
+  servers: {
+    myStdioClient: {
+      command: 'your-mcp-server-command',
+      args: ['--your', 'args'],
+      env: { API_KEY: 'your-api-key' }, // optional environment variables
+      capabilities: {}, // optional ClientCapabilities
+      timeout: 60000, // optional timeout for tool calls in milliseconds
+    },
   },
-  capabilities: {}, // optional ClientCapabilities
-  timeout: 60000, // optional timeout for tool calls in milliseconds
 });
 
 // Create a client with an HTTP server (tries Streamable HTTP, falls back to SSE)
-const httpClient = new MastraMCPClient({
-  name: 'my-http-client',
-  version: '1.0.0',
-  server: {
-    url: new URL('https://your-mcp-server.com/mcp'), // Use the base URL for Streamable HTTP
-    requestInit: {
-      // Optional fetch request configuration
-      headers: { Authorization: 'Bearer your-token' },
+const httpClient = new MCPClient({
+  servers: {
+    myHttpClient: {
+      url: new URL('https://your-mcp-server.com/mcp'), // Use the base URL for Streamable HTTP
+      requestInit: {
+        // Optional fetch request configuration
+        headers: { Authorization: 'Bearer your-token' },
+      },
+      // eventSourceInit is only needed for custom headers with the legacy SSE fallback
+      eventSourceInit: {
+        /* ... */
+      },
     },
-    // eventSourceInit is only needed for custom headers with the legacy SSE fallback
-    eventSourceInit: {
-      /* ... */
+  },
+});
+
+// Or create a client with SSE server
+const sseClient = new MCPClient({
+  servers: {
+    mySseClient: {
+      url: new URL('https://your-mcp-server.com/sse'),
+      requestInit: {
+        headers: { Authorization: 'Bearer your-token' },
+      },
+      eventSourceInit: {
+        fetch(input: Request | URL | string, init?: RequestInit) {
+          const headers = new Headers(init?.headers || {});
+          headers.set('Authorization', 'Bearer your-token');
+          return fetch(input, {
+            ...init,
+            headers,
+          });
+        },
+      },
+      timeout: 60000, // optional timeout for tool calls in milliseconds
     },
   },
-  timeout: 60000, // optional timeout for tool calls in milliseconds
 });
 
 // Connect to the MCP server (using one of the clients above)
@@ -68,12 +90,12 @@ await httpClient.disconnect();
 
 ## Managing Multiple MCP Servers
 
-For applications that need to interact with multiple MCP servers, the `MCPConfiguration` class provides a convenient way to manage multiple server connections and their tools. It also uses the automatic transport detection based on the `server` configuration:
+For applications that need to interact with multiple MCP servers, the `MCPClient` class provides a convenient way to manage multiple server connections and their tools. It also uses the automatic transport detection based on the `server` configuration:
 
 ```typescript
-import { MCPConfiguration } from '@mastra/mcp';
+import { MCPClient } from '@mastra/mcp';
 
-const mcp = new MCPConfiguration({
+const mcp = new MCPClient({
   servers: {
     // Stdio-based server
     stockPrice: {
@@ -106,7 +128,7 @@ const toolsets = await mcp.getToolsets();
 The MCP client provides per-server logging capabilities, allowing you to monitor interactions with each MCP server separately:
 
 ```typescript
-import { MCPConfiguration, LogMessage, LoggingLevel } from '@mastra/mcp';
+import { MCPClient, LogMessage, LoggingLevel } from '@mastra/mcp';
 
 // Define a custom log handler
 const weatherLogger = (logMessage: LogMessage) => {
@@ -118,7 +140,7 @@ const weatherLogger = (logMessage: LogMessage) => {
 };
 
 // Initialize MCP configuration with server-specific loggers
-const mcp = new MCPConfiguration({
+const mcp = new MCPClient({
   servers: {
     weatherService: {
       command: 'npx',
@@ -182,7 +204,7 @@ const createFileLogger = (filePath: string) => {
 };
 
 // Use the factory in configuration
-const mcp = new MCPConfiguration({
+const mcp = new MCPClient({
   servers: {
     weatherService: {
       command: 'npx',
@@ -197,7 +219,7 @@ See the `examples/server-logging.ts` file for comprehensive examples of various
 
 ### Tools vs Toolsets
 
-The MCPConfiguration class provides two ways to access MCP tools:
+The MCPClient class provides two ways to access MCP tools:
 
 #### Tools (`getTools()`)
 
@@ -230,12 +252,12 @@ Use this when:
 - Tool configuration needs to change dynamically
 
 ```typescript
-import { MCPConfiguration } from '@mastra/mcp';
+import { MCPClient } from '@mastra/mcp';
 import { Agent } from '@mastra/core/agent';
 import { openai } from '@ai-sdk/openai';
 
 // Configure MCP servers with user-specific settings before getting toolsets
-const mcp = new MCPConfiguration({
+const mcp = new MCPClient({
   servers: {
     stockPrice: {
       command: 'npx',
@@ -272,7 +294,7 @@ const response = await agent.generate('What is the weather in London?', {
 console.log(response.text);
 ```
 
-The `MCPConfiguration` class automatically:
+The `MCPClient` class automatically:
 
 - Manages connections to multiple MCP servers
 - Namespaces tools to prevent naming conflicts
@@ -288,23 +310,24 @@ The `eventSourceInit` configuration allows you to customize the underlying fetch
 To properly include authentication headers or other custom headers in SSE connections when using the legacy fallback, you need to use both `requestInit` and `eventSourceInit`:
 
 ```typescript
-const sseClient = new MastraMCPClient({
-  name: 'authenticated-sse-client',
-  server: {
-    url: new URL('https://your-mcp-server.com/sse'), // Note the typical /sse path for legacy servers
-    // requestInit alone isn't enough for SSE connections
-    requestInit: {
-      headers: { Authorization: 'Bearer your-token' },
-    },
-    // eventSourceInit is required to include headers in the SSE connection
-    eventSourceInit: {
-      fetch(input: Request | URL | string, init?: RequestInit) {
-        const headers = new Headers(init?.headers || {});
-        headers.set('Authorization', 'Bearer your-token');
-        return fetch(input, {
-          ...init,
-          headers,
-        });
+const sseClient = new MCPClient({
+  servers: {
+    authenticatedSseClient: {
+      url: new URL('https://your-mcp-server.com/sse'), // Note the typical /sse path for legacy servers
+      // requestInit alone isn't enough for SSE connections
+      requestInit: {
+        headers: { Authorization: 'Bearer your-token' },
+      },
+      // eventSourceInit is required to include headers in the SSE connection
+      eventSourceInit: {
+        fetch(input: Request | URL | string, init?: RequestInit) {
+          const headers = new Headers(init?.headers || {});
+          headers.set('Authorization', 'Bearer your-token');
+          return fetch(input, {
+            ...init,
+            headers,
+          });
+        },
       },
     },
   },

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

@@ -40,38 +40,13 @@ declare type HttpServerDefinition = BaseServerOptions & {
     sessionId?: StreamableHTTPClientTransportOptions['sessionId'];
 };
 
-export declare interface Logger {
-    info: (message: string, data?: any) => Promise<void>;
-    warning: (message: string, data?: any) => Promise<void>;
-    error: (message: string, error?: any) => Promise<void>;
-    debug: (message: string, data?: any) => Promise<void>;
-}
-
-export declare const logger: Logger;
-
-export { LoggingLevel }
-export { LoggingLevel as LoggingLevel_alias_1 }
-
-declare type LogHandler = (logMessage: LogMessage) => void;
-export { LogHandler }
-export { LogHandler as LogHandler_alias_1 }
-
-declare interface LogMessage {
-    level: LoggingLevel;
-    message: string;
-    timestamp: Date;
-    serverName: string;
-    details?: Record<string, any>;
-}
-export { LogMessage }
-export { LogMessage as LogMessage_alias_1 }
-
-declare class MastraMCPClient extends MastraBase {
+export declare class InternalMastraMCPClient extends MastraBase {
     name: string;
     private client;
     private readonly timeout;
     private logHandler?;
     private enableServerLogs?;
+    private static hasWarned;
     private serverConfig;
     private transport?;
     constructor({ name, version, server, capabilities, timeout, }: {
@@ -102,6 +77,37 @@ declare class MastraMCPClient extends MastraBase {
     resources(): Promise<ReturnType<Protocol<any, any, any>['request']>>;
     tools(): Promise<Record<string, any>>;
 }
+
+export declare interface Logger {
+    info: (message: string, data?: any) => Promise<void>;
+    warning: (message: string, data?: any) => Promise<void>;
+    error: (message: string, error?: any) => Promise<void>;
+    debug: (message: string, data?: any) => Promise<void>;
+}
+
+export declare const logger: Logger;
+
+export { LoggingLevel }
+export { LoggingLevel as LoggingLevel_alias_1 }
+
+declare type LogHandler = (logMessage: LogMessage) => void;
+export { LogHandler }
+export { LogHandler as LogHandler_alias_1 }
+
+declare interface LogMessage {
+    level: LoggingLevel;
+    message: string;
+    timestamp: Date;
+    serverName: string;
+    details?: Record<string, any>;
+}
+export { LogMessage }
+export { LogMessage as LogMessage_alias_1 }
+
+/**
+ * @deprecated MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead.
+ */
+declare const MastraMCPClient: typeof InternalMastraMCPClient;
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
 
@@ -109,11 +115,13 @@ declare type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefin
 export { MastraMCPServerDefinition }
 export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
 
-declare class MCPConfiguration extends MastraBase {
+declare class MCPClient extends MastraBase {
     private serverConfigs;
     private id;
     private defaultTimeout;
-    constructor(args: MCPConfigurationOptions);
+    private mcpClientsById;
+    private disconnectPromise;
+    constructor(args: MCPClientOptions);
     private addToInstanceCache;
     private makeId;
     disconnect(): Promise<void>;
@@ -124,13 +132,32 @@ declare class MCPConfiguration extends MastraBase {
      * Returns an object mapping server names to their session IDs.
      */
     get sessionIds(): Record<string, string>;
-    private mcpClientsById;
     private getConnectedClient;
     private eachClientTools;
 }
+export { MCPClient }
+export { MCPClient as MCPClient_alias_1 }
+
+declare interface MCPClientOptions {
+    id?: string;
+    servers: Record<string, MastraMCPServerDefinition>;
+    timeout?: number;
+}
+export { MCPClientOptions }
+export { MCPClientOptions as MCPClientOptions_alias_1 }
+
+/**
+ * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use MCPClient instead.
+ */
+declare class MCPConfiguration extends MCPClient {
+    constructor(args: MCPClientOptions);
+}
 export { MCPConfiguration }
 export { MCPConfiguration as MCPConfiguration_alias_1 }
 
+/**
+ * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use MCPClientOptions instead.
+ */
 declare interface MCPConfigurationOptions {
     id?: string;
     servers: Record<string, MastraMCPServerDefinition>;

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

@@ -40,38 +40,13 @@ declare type HttpServerDefinition = BaseServerOptions & {
     sessionId?: StreamableHTTPClientTransportOptions['sessionId'];
 };
 
-export declare interface Logger {
-    info: (message: string, data?: any) => Promise<void>;
-    warning: (message: string, data?: any) => Promise<void>;
-    error: (message: string, error?: any) => Promise<void>;
-    debug: (message: string, data?: any) => Promise<void>;
-}
-
-export declare const logger: Logger;
-
-export { LoggingLevel }
-export { LoggingLevel as LoggingLevel_alias_1 }
-
-declare type LogHandler = (logMessage: LogMessage) => void;
-export { LogHandler }
-export { LogHandler as LogHandler_alias_1 }
-
-declare interface LogMessage {
-    level: LoggingLevel;
-    message: string;
-    timestamp: Date;
-    serverName: string;
-    details?: Record<string, any>;
-}
-export { LogMessage }
-export { LogMessage as LogMessage_alias_1 }
-
-declare class MastraMCPClient extends MastraBase {
+export declare class InternalMastraMCPClient extends MastraBase {
     name: string;
     private client;
     private readonly timeout;
     private logHandler?;
     private enableServerLogs?;
+    private static hasWarned;
     private serverConfig;
     private transport?;
     constructor({ name, version, server, capabilities, timeout, }: {
@@ -102,6 +77,37 @@ declare class MastraMCPClient extends MastraBase {
     resources(): Promise<ReturnType<Protocol<any, any, any>['request']>>;
     tools(): Promise<Record<string, any>>;
 }
+
+export declare interface Logger {
+    info: (message: string, data?: any) => Promise<void>;
+    warning: (message: string, data?: any) => Promise<void>;
+    error: (message: string, error?: any) => Promise<void>;
+    debug: (message: string, data?: any) => Promise<void>;
+}
+
+export declare const logger: Logger;
+
+export { LoggingLevel }
+export { LoggingLevel as LoggingLevel_alias_1 }
+
+declare type LogHandler = (logMessage: LogMessage) => void;
+export { LogHandler }
+export { LogHandler as LogHandler_alias_1 }
+
+declare interface LogMessage {
+    level: LoggingLevel;
+    message: string;
+    timestamp: Date;
+    serverName: string;
+    details?: Record<string, any>;
+}
+export { LogMessage }
+export { LogMessage as LogMessage_alias_1 }
+
+/**
+ * @deprecated MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead.
+ */
+declare const MastraMCPClient: typeof InternalMastraMCPClient;
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
 
@@ -109,11 +115,13 @@ declare type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefin
 export { MastraMCPServerDefinition }
 export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
 
-declare class MCPConfiguration extends MastraBase {
+declare class MCPClient extends MastraBase {
     private serverConfigs;
     private id;
     private defaultTimeout;
-    constructor(args: MCPConfigurationOptions);
+    private mcpClientsById;
+    private disconnectPromise;
+    constructor(args: MCPClientOptions);
     private addToInstanceCache;
     private makeId;
     disconnect(): Promise<void>;
@@ -124,13 +132,32 @@ declare class MCPConfiguration extends MastraBase {
      * Returns an object mapping server names to their session IDs.
      */
     get sessionIds(): Record<string, string>;
-    private mcpClientsById;
     private getConnectedClient;
     private eachClientTools;
 }
+export { MCPClient }
+export { MCPClient as MCPClient_alias_1 }
+
+declare interface MCPClientOptions {
+    id?: string;
+    servers: Record<string, MastraMCPServerDefinition>;
+    timeout?: number;
+}
+export { MCPClientOptions }
+export { MCPClientOptions as MCPClientOptions_alias_1 }
+
+/**
+ * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use MCPClient instead.
+ */
+declare class MCPConfiguration extends MCPClient {
+    constructor(args: MCPClientOptions);
+}
 export { MCPConfiguration }
 export { MCPConfiguration as MCPConfiguration_alias_1 }
 
+/**
+ * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use MCPClientOptions instead.
+ */
 declare interface MCPConfigurationOptions {
     id?: string;
     servers: Record<string, MastraMCPServerDefinition>;