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

package/src/configuration.ts

@@ -1,66 +1,100 @@
 import { MastraBase } from '@mastra/core/base';
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import equal from 'fast-deep-equal';
 import { v5 as uuidv5 } from 'uuid';
-import { MastraMCPClient } from './client';
+import { InternalMastraMCPClient } from './client';
 import type { MastraMCPServerDefinition } from './client';
 
-const mastraMCPConfigurationInstances = new Map<string, InstanceType<typeof MCPConfiguration>>();
+const mcpClientInstances = new Map<string, InstanceType<typeof MCPClient>>();
 
-export interface MCPConfigurationOptions {
+export interface MCPClientOptions {
   id?: string;
   servers: Record<string, MastraMCPServerDefinition>;
   timeout?: number; // Optional global timeout
 }
 
-export class MCPConfiguration extends MastraBase {
+export class MCPClient extends MastraBase {
   private serverConfigs: Record<string, MastraMCPServerDefinition> = {};
   private id: string;
   private defaultTimeout: number;
+  private mcpClientsById = new Map<string, InternalMastraMCPClient>();
+  private disconnectPromise: Promise<void> | null = null;
 
-  constructor(args: MCPConfigurationOptions) {
-    super({ name: 'MCPConfiguration' });
+  constructor(args: MCPClientOptions) {
+    super({ name: 'MCPClient' });
     this.defaultTimeout = args.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
     this.serverConfigs = args.servers;
     this.id = args.id ?? this.makeId();
 
+    if (args.id) {
+      this.id = args.id;
+      const cached = mcpClientInstances.get(this.id);
+
+      if (cached && !equal(cached.serverConfigs, args.servers)) {
+        const existingInstance = mcpClientInstances.get(this.id);
+        if (existingInstance) {
+          void existingInstance.disconnect();
+        }
+      }
+    } else {
+      this.id = this.makeId();
+    }
+
     // to prevent memory leaks return the same MCP server instance when configured the same way multiple times
-    const existingInstance = mastraMCPConfigurationInstances.get(this.id);
+    const existingInstance = mcpClientInstances.get(this.id);
     if (existingInstance) {
       if (!args.id) {
-        throw new Error(`MCPConfiguration was initialized multiple times with the same configuration options.
+        throw new Error(`MCPClient was initialized multiple times with the same configuration options.
 
 This error is intended to prevent memory leaks.
 
 To fix this you have three different options:
-1. If you need multiple MCPConfiguration class instances with identical server configurations, set an id when configuring: new MCPConfiguration({ id: "my-unique-id" })
-2. Call "await configuration.disconnect()" after you're done using the configuration and before you recreate another instance with the same options. If the identical MCPConfiguration instance is already closed at the time of re-creating it, you will not see this error.
-3. If you only need one instance of MCPConfiguration in your app, refactor your code so it's only created one time (ex. move it out of a loop into a higher scope code block)
+1. If you need multiple MCPClient class instances with identical server configurations, set an id when configuring: new MCPClient({ id: "my-unique-id" })
+2. Call "await client.disconnect()" after you're done using the client and before you recreate another instance with the same options. If the identical MCPClient instance is already closed at the time of re-creating it, you will not see this error.
+3. If you only need one instance of MCPClient in your app, refactor your code so it's only created one time (ex. move it out of a loop into a higher scope code block)
 `);
       }
       return existingInstance;
     }
+
+    mcpClientInstances.set(this.id, this);
     this.addToInstanceCache();
     return this;
   }
 
   private addToInstanceCache() {
-    if (!mastraMCPConfigurationInstances.has(this.id)) {
-      mastraMCPConfigurationInstances.set(this.id, this);
+    if (!mcpClientInstances.has(this.id)) {
+      mcpClientInstances.set(this.id, this);
     }
   }
 
   private makeId() {
     const text = JSON.stringify(this.serverConfigs).normalize('NFKC');
-    const idNamespace = uuidv5(`MCPConfiguration`, uuidv5.DNS);
+    const idNamespace = uuidv5(`MCPClient`, uuidv5.DNS);
 
     return uuidv5(text, idNamespace);
   }
 
   public async disconnect() {
-    mastraMCPConfigurationInstances.delete(this.id);
+    // Helps to prevent race condition
+    // If there is already a disconnect ongoing, return the existing promise.
+    if (this.disconnectPromise) {
+      return this.disconnectPromise;
+    }
 
-    await Promise.all(Array.from(this.mcpClientsById.values()).map(client => client.disconnect()));
-    this.mcpClientsById.clear();
+    this.disconnectPromise = (async () => {
+      try {
+        mcpClientInstances.delete(this.id);
+
+        // Disconnect all clients in the cache
+        await Promise.all(Array.from(this.mcpClientsById.values()).map(client => client.disconnect()));
+        this.mcpClientsById.clear();
+      } finally {
+        this.disconnectPromise = null;
+      }
+    })();
+
+    return this.disconnectPromise;
   }
 
   public async getTools() {
@@ -103,32 +137,42 @@ To fix this you have three different options:
     return sessionIds;
   }
 
-  private mcpClientsById = new Map<string, MastraMCPClient>();
   private async getConnectedClient(name: string, config: MastraMCPServerDefinition) {
+    // Helps to prevent race condition.
+    // If we want to call connect() we need to wait for the disconnect to complete first if any is ongoing.
+    if (this.disconnectPromise) {
+      await this.disconnectPromise;
+    }
+
     const exists = this.mcpClientsById.has(name);
+    const existingClient = this.mcpClientsById.get(name);
 
     if (exists) {
-      const mcpClient = this.mcpClientsById.get(name)!;
-      await mcpClient.connect();
-
-      return mcpClient;
+      // 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.
+      if (!existingClient) {
+        throw new Error(`Client ${name} exists but is undefined`);
+      }
+      await existingClient.connect();
+      return existingClient;
     }
 
     this.logger.debug(`Connecting to ${name} MCP server`);
 
     // Create client with server configuration including log handler
-    const mcpClient = new MastraMCPClient({
+    const mcpClient = new InternalMastraMCPClient({
       name,
       server: config,
       timeout: config.timeout ?? this.defaultTimeout,
     });
 
     this.mcpClientsById.set(name, mcpClient);
+
     try {
       await mcpClient.connect();
     } catch (e) {
       this.mcpClientsById.delete(name);
-      this.logger.error(`MCPConfiguration errored connecting to MCP server ${name}`, {
+      this.logger.error(`MCPClient errored connecting to MCP server ${name}`, {
         error: e instanceof Error ? e.message : String(e),
       });
       throw new Error(
@@ -145,7 +189,7 @@ To fix this you have three different options:
     cb: (input: {
       serverName: string;
       tools: Record<string, any>; // <- any because we don't have proper tool schemas
-      client: InstanceType<typeof MastraMCPClient>;
+      client: InstanceType<typeof InternalMastraMCPClient>;
     }) => Promise<void>,
   ) {
     await Promise.all(
@@ -157,3 +201,24 @@ To fix this you have three different options:
     );
   }
 }
+
+/**
+ * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use MCPClientOptions instead.
+ */
+export interface MCPConfigurationOptions {
+  id?: string;
+  servers: Record<string, MastraMCPServerDefinition>;
+  timeout?: number; // Optional global timeout
+}
+
+/**
+ * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use MCPClient instead.
+ */
+export class MCPConfiguration extends MCPClient {
+  constructor(args: MCPClientOptions) {
+    super(args);
+    this.logger.warn(
+      `MCPConfiguration has been renamed to MCPClient and MCPConfiguration is deprecated. The API is identical but the MCPConfiguration export will be removed in the future. Update your imports now to prevent future errors.`,
+    );
+  }
+}

package/src/index.ts

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

package/src/server-logging.test.ts

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
 import type { LogMessage } from './client';
-import { MCPConfiguration } from './configuration';
+import { MCPClient } from './configuration';
 
 // Increase test timeout for server operations
 vi.setConfig({ testTimeout: 80000, hookTimeout: 80000 });
@@ -58,7 +58,7 @@ describe('MCP Server Logging', () => {
     const weatherLogHandler = vi.fn();
     const stockLogHandler = vi.fn();
 
-    const config = new MCPConfiguration({
+    const config = new MCPClient({
       id: 'server-log-test',
       servers: {
         weather: {
@@ -116,7 +116,7 @@ describe('MCP Server Logging', () => {
     });
 
     // Intentionally use a non-existent command to generate errors
-    const config = new MCPConfiguration({
+    const config = new MCPClient({
       id: 'error-log-test',
       servers: {
         badServer: {
@@ -153,7 +153,7 @@ describe('MCP Server Logging', () => {
       console.log(formatted);
     };
 
-    const config = new MCPConfiguration({
+    const config = new MCPClient({
       id: 'console-log-test',
       servers: {
         echoServer: {

package/src/server.test.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { describe, it, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
 import { weatherTool } from './__fixtures__/tools';
-import { MCPConfiguration } from './configuration';
+import { MCPClient } from './configuration';
 import { MCPServer } from './server';
 
 const PORT = 9100 + Math.floor(Math.random() * 1000);
@@ -94,7 +94,7 @@ describe('MCPServer', () => {
       expect(server.getStdioTransport()).toBeInstanceOf(StdioServerTransport);
     });
     it('should use stdio transport to get tools', async () => {
-      const existingConfig = new MCPConfiguration({
+      const existingConfig = new MCPClient({
         servers: {
           weather: {
             command: 'npx',