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

package/dist/index.js

@@ -4,9 +4,11 @@ import { jsonSchemaToModel } from '@mastra/core/utils';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { ListResourcesResultSchema, CallToolResultSchema, ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { asyncExitHook, gracefulExit } from 'exit-hook';
+import equal from 'fast-deep-equal';
 import { v5 } from 'uuid';
 import { isVercelTool, isZodType, resolveSerializedZodOutput } from '@mastra/core';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -4093,13 +4095,15 @@ function convertLogLevelToLoggerMethod(level) {
       return "info";
   }
 }
-var MastraMCPClient = class extends MastraBase {
+var InternalMastraMCPClient = class _InternalMastraMCPClient extends MastraBase {
   name;
-  transport;
   client;
   timeout;
   logHandler;
   enableServerLogs;
+  static hasWarned = false;
+  serverConfig;
+  transport;
   constructor({
     name,
     version = "1.0.0",
@@ -4108,23 +4112,17 @@ var MastraMCPClient = class extends MastraBase {
     timeout = DEFAULT_REQUEST_TIMEOUT_MSEC
   }) {
     super({ name: "MastraMCPClient" });
+    if (!_InternalMastraMCPClient.hasWarned) {
+      console.warn(
+        "[DEPRECATION] MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead."
+      );
+      _InternalMastraMCPClient.hasWarned = true;
+    }
     this.name = name;
     this.timeout = timeout;
     this.logHandler = server.logger;
     this.enableServerLogs = server.enableServerLogs ?? true;
-    const { logger: logger3, enableServerLogs, ...serverConfig } = server;
-    if (`url` in serverConfig) {
-      this.transport = new SSEClientTransport(serverConfig.url, {
-        requestInit: serverConfig.requestInit,
-        eventSourceInit: serverConfig.eventSourceInit
-      });
-    } else {
-      this.transport = new StdioClientTransport({
-        ...serverConfig,
-        // without ...getDefaultEnvironment() commands like npx will fail because there will be no PATH env var
-        env: { ...getDefaultEnvironment(), ...serverConfig.env || {} }
-      });
-    }
+    this.serverConfig = server;
     this.client = new Client(
       {
         name,
@@ -4144,11 +4142,12 @@ var MastraMCPClient = class extends MastraBase {
    */
   log(level, message, details) {
     const loggerMethod = convertLogLevelToLoggerMethod(level);
-    this.logger[loggerMethod](message, details);
+    const msg = `[${this.name}] ${message}`;
+    this.logger[loggerMethod](msg, details);
     if (this.logHandler) {
       this.logHandler({
         level,
-        message,
+        message: msg,
         timestamp: /* @__PURE__ */ new Date(),
         serverName: this.name,
         details
@@ -4171,44 +4170,121 @@ var MastraMCPClient = class extends MastraBase {
       );
     }
   }
+  async connectStdio(command) {
+    this.log("debug", `Using Stdio transport for command: ${command}`);
+    try {
+      this.transport = new StdioClientTransport({
+        command,
+        args: this.serverConfig.args,
+        env: { ...getDefaultEnvironment(), ...this.serverConfig.env || {} }
+      });
+      await this.client.connect(this.transport, { timeout: this.serverConfig.timeout ?? this.timeout });
+      this.log("debug", `Successfully connected to MCP server via Stdio`);
+    } catch (e) {
+      this.log("error", e instanceof Error ? e.stack || e.message : JSON.stringify(e));
+      throw e;
+    }
+  }
+  async connectHttp(url) {
+    const { requestInit, eventSourceInit } = this.serverConfig;
+    this.log("debug", `Attempting to connect to URL: ${url}`);
+    let shouldTrySSE = url.pathname.endsWith(`/sse`);
+    if (!shouldTrySSE) {
+      try {
+        this.log("debug", "Trying Streamable HTTP transport...");
+        const streamableTransport = new StreamableHTTPClientTransport(url, {
+          requestInit,
+          reconnectionOptions: this.serverConfig.reconnectionOptions,
+          sessionId: this.serverConfig.sessionId
+        });
+        await this.client.connect(streamableTransport, {
+          timeout: (
+            // this is hardcoded to 3s because the long default timeout would be extremely slow for sse backwards compat (60s)
+            3e3
+          )
+        });
+        this.transport = streamableTransport;
+        this.log("debug", "Successfully connected using Streamable HTTP transport.");
+      } catch (error) {
+        this.log("debug", `Streamable HTTP transport failed: ${error}`);
+        shouldTrySSE = true;
+      }
+    }
+    if (shouldTrySSE) {
+      this.log("debug", "Falling back to deprecated HTTP+SSE transport...");
+      try {
+        const sseTransport = new SSEClientTransport(url, { requestInit, eventSourceInit });
+        await this.client.connect(sseTransport, { timeout: this.serverConfig.timeout ?? this.timeout });
+        this.transport = sseTransport;
+        this.log("debug", "Successfully connected using deprecated HTTP+SSE transport.");
+      } catch (sseError) {
+        this.log(
+          "error",
+          `Failed to connect with SSE transport after failing to connect to Streamable HTTP transport first. SSE error: ${sseError}`
+        );
+        throw new Error("Could not connect to server with any available HTTP transport");
+      }
+    }
+  }
   isConnected = false;
   async connect() {
     if (this.isConnected) return;
+    const { command, url } = this.serverConfig;
+    if (command) {
+      await this.connectStdio(command);
+    } else if (url) {
+      await this.connectHttp(url);
+    } else {
+      throw new Error("Server configuration must include either a command or a url.");
+    }
+    this.isConnected = true;
+    const originalOnClose = this.client.onclose;
+    this.client.onclose = () => {
+      this.log("debug", `MCP server connection closed`);
+      this.isConnected = false;
+      if (typeof originalOnClose === `function`) {
+        originalOnClose();
+      }
+    };
+    asyncExitHook(
+      async () => {
+        this.log("debug", `Disconnecting MCP server during exit`);
+        await this.disconnect();
+      },
+      { wait: 5e3 }
+    );
+    process.on("SIGTERM", () => gracefulExit());
+    this.log("debug", `Successfully connected to MCP server`);
+  }
+  /**
+   * Get the current session ID if using the Streamable HTTP transport.
+   * Returns undefined if not connected or not using Streamable HTTP.
+   */
+  get sessionId() {
+    if (this.transport instanceof StreamableHTTPClientTransport) {
+      return this.transport.sessionId;
+    }
+    return void 0;
+  }
+  async disconnect() {
+    if (!this.transport) {
+      this.log("debug", "Disconnect called but no transport was connected.");
+      return;
+    }
+    this.log("debug", `Disconnecting from MCP server`);
     try {
-      this.log("debug", `Connecting to MCP server`);
-      await this.client.connect(this.transport, {
-        timeout: this.timeout
-      });
-      this.isConnected = true;
-      const originalOnClose = this.client.onclose;
-      this.client.onclose = () => {
-        this.log("debug", `MCP server connection closed`);
-        this.isConnected = false;
-        if (typeof originalOnClose === `function`) {
-          originalOnClose();
-        }
-      };
-      asyncExitHook(
-        async () => {
-          this.log("debug", `Disconnecting MCP server during exit`);
-          await this.disconnect();
-        },
-        { wait: 5e3 }
-      );
-      process.on("SIGTERM", () => gracefulExit());
-      this.log("info", `Successfully connected to MCP server`);
+      await this.transport.close();
+      this.log("debug", "Successfully disconnected from MCP server");
     } catch (e) {
-      this.log("error", `Failed connecting to MCP server`, {
+      this.log("error", "Error during MCP server disconnect", {
         error: e instanceof Error ? e.stack : JSON.stringify(e, null, 2)
       });
-      this.isConnected = false;
       throw e;
+    } finally {
+      this.transport = void 0;
+      this.isConnected = false;
     }
   }
-  async disconnect() {
-    this.log("debug", `Disconnecting from MCP server`);
-    return await this.client.close();
-  }
   // TODO: do the type magic to return the right method type. Right now we get infinitely deep infered type errors from Zod without using "any"
   async resources() {
     this.log("debug", `Requesting resources from MCP server`);
@@ -4258,48 +4334,74 @@ var MastraMCPClient = class extends MastraBase {
     return toolsRes;
   }
 };
-var mastraMCPConfigurationInstances = /* @__PURE__ */ new Map();
-var MCPConfiguration = class extends MastraBase {
+var MastraMCPClient = InternalMastraMCPClient;
+var mcpClientInstances = /* @__PURE__ */ new Map();
+var MCPClient = class extends MastraBase {
   serverConfigs = {};
   id;
   defaultTimeout;
+  mcpClientsById = /* @__PURE__ */ new Map();
+  disconnectPromise = null;
   constructor(args) {
-    super({ name: "MCPConfiguration" });
+    super({ name: "MCPClient" });
     this.defaultTimeout = args.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
     this.serverConfigs = args.servers;
     this.id = args.id ?? this.makeId();
-    const existingInstance = mastraMCPConfigurationInstances.get(this.id);
+    if (args.id) {
+      this.id = args.id;
+      const cached = mcpClientInstances.get(this.id);
+      if (cached && !equal(cached.serverConfigs, args.servers)) {
+        const existingInstance2 = mcpClientInstances.get(this.id);
+        if (existingInstance2) {
+          void existingInstance2.disconnect();
+        }
+      }
+    } else {
+      this.id = this.makeId();
+    }
+    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;
   }
   addToInstanceCache() {
-    if (!mastraMCPConfigurationInstances.has(this.id)) {
-      mastraMCPConfigurationInstances.set(this.id, this);
+    if (!mcpClientInstances.has(this.id)) {
+      mcpClientInstances.set(this.id, this);
     }
   }
   makeId() {
     const text = JSON.stringify(this.serverConfigs).normalize("NFKC");
-    const idNamespace = v5(`MCPConfiguration`, v5.DNS);
+    const idNamespace = v5(`MCPClient`, v5.DNS);
     return v5(text, idNamespace);
   }
   async disconnect() {
-    mastraMCPConfigurationInstances.delete(this.id);
-    await Promise.all(Array.from(this.mcpClientsById.values()).map((client) => client.disconnect()));
-    this.mcpClientsById.clear();
+    if (this.disconnectPromise) {
+      return this.disconnectPromise;
+    }
+    this.disconnectPromise = (async () => {
+      try {
+        mcpClientInstances.delete(this.id);
+        await Promise.all(Array.from(this.mcpClientsById.values()).map((client) => client.disconnect()));
+        this.mcpClientsById.clear();
+      } finally {
+        this.disconnectPromise = null;
+      }
+    })();
+    return this.disconnectPromise;
   }
   async getTools() {
     this.addToInstanceCache();
@@ -4321,16 +4423,34 @@ To fix this you have three different options:
     });
     return connectedToolsets;
   }
-  mcpClientsById = /* @__PURE__ */ new Map();
+  /**
+   * Get the current session IDs for all connected MCP clients using the Streamable HTTP transport.
+   * Returns an object mapping server names to their session IDs.
+   */
+  get sessionIds() {
+    const sessionIds = {};
+    for (const [serverName, client] of this.mcpClientsById.entries()) {
+      if (client.sessionId) {
+        sessionIds[serverName] = client.sessionId;
+      }
+    }
+    return sessionIds;
+  }
   async getConnectedClient(name, config) {
+    if (this.disconnectPromise) {
+      await this.disconnectPromise;
+    }
     const exists = this.mcpClientsById.has(name);
+    const existingClient = this.mcpClientsById.get(name);
     if (exists) {
-      const mcpClient2 = this.mcpClientsById.get(name);
-      await mcpClient2.connect();
-      return mcpClient2;
+      if (!existingClient) {
+        throw new Error(`Client ${name} exists but is undefined`);
+      }
+      await existingClient.connect();
+      return existingClient;
     }
     this.logger.debug(`Connecting to ${name} MCP server`);
-    const mcpClient = new MastraMCPClient({
+    const mcpClient = new InternalMastraMCPClient({
       name,
       server: config,
       timeout: config.timeout ?? this.defaultTimeout
@@ -4340,10 +4460,12 @@ To fix this you have three different options:
       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(`Failed to connect to MCP server ${name}: ${e instanceof Error ? e.message : String(e)}`);
+      throw new Error(
+        `Failed to connect to MCP server ${name}: ${e instanceof Error ? e.stack || e.message : String(e)}`
+      );
     }
     this.logger.debug(`Connected to ${name} MCP server`);
     return mcpClient;
@@ -4358,6 +4480,14 @@ To fix this you have three different options:
     );
   }
 };
+var MCPConfiguration = class extends MCPClient {
+  constructor(args) {
+    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.`
+    );
+  }
+};
 
 // ../../node_modules/.pnpm/json-schema-to-zod@2.6.0/node_modules/json-schema-to-zod/dist/esm/parsers/parseAnyOf.js
 var parseAnyOf = (schema, refs) => {
@@ -6478,4 +6608,4 @@ var MCPServer = class {
   }
 };
 
-export { MCPConfiguration, MCPServer, MastraMCPClient };
+export { MCPClient, MCPConfiguration, MCPServer, MastraMCPClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp",
-  "version": "0.4.1-alpha.2",
+  "version": "0.4.1-alpha.4",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -22,11 +22,12 @@
   "author": "",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@modelcontextprotocol/sdk": "^1.10.2",
     "date-fns": "^4.1.0",
     "exit-hook": "^4.0.0",
+    "fast-deep-equal": "^3.1.3",
     "uuid": "^11.1.0",
-    "@mastra/core": "^0.9.1-alpha.2"
+    "@mastra/core": "^0.9.1-alpha.3"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^1.1.15",

package/src/client.test.ts

@@ -1,49 +1,137 @@
-import { anthropic } from '@ai-sdk/anthropic';
-import { Agent } from '@mastra/core/agent';
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import type { Server as HttpServer } from 'node:http';
+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 { z } from 'zod';
 
 import { MastraMCPClient } from './client.js';
 
-const everArtClient = new MastraMCPClient({
-  name: 'everart',
-  server: {
-    command: '/usr/local/bin/docker',
-    args: ['run', '-i', '--rm', '--network=host', '-e', 'EVERART_API_KEY', 'mcp/everart'],
-    env: {
-      EVERART_API_KEY: process.env.EVERART_API_KEY!,
+async function setupTestServer(withSessionManagement: boolean) {
+  const httpServer: HttpServer = createServer();
+  const mcpServer = new McpServer(
+    { name: 'test-http-server', version: '1.0.0' },
+    {
+      capabilities: {
+        logging: {},
+        tools: {},
+      },
     },
-  },
-});
+  );
 
-const agent = new Agent({
-  name: 'everart',
-  instructions: 'You are my artist. Include the url in your response.',
-  model: anthropic('claude-3-5-sonnet-20241022'),
-});
+  mcpServer.tool(
+    'greet',
+    'A simple greeting tool',
+    {
+      name: z.string().describe('Name to greet').default('World'),
+    },
+    async ({ name }): Promise<CallToolResult> => {
+      return {
+        content: [{ type: 'text', text: `Hello, ${name}!` }],
+      };
+    },
+  );
 
-describe.skip('MastraMCPClient', () => {
-  beforeAll(async () => {
-    await everArtClient.connect();
+  const serverTransport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: withSessionManagement ? () => randomUUID() : undefined,
   });
 
-  afterAll(async () => {
-    await everArtClient.disconnect();
+  await mcpServer.connect(serverTransport);
+
+  httpServer.on('request', async (req, res) => {
+    await serverTransport.handleRequest(req, res);
   });
 
-  it('Converting tools into Mastra', async () => {
-    const list = await everArtClient.resources();
+  const baseUrl = await new Promise<URL>(resolve => {
+    httpServer.listen(0, '127.0.0.1', () => {
+      const addr = httpServer.address() as AddressInfo;
+      resolve(new URL(`http://127.0.0.1:${addr.port}/mcp`));
+    });
+  });
 
-    expect(list.resources.length).toBeGreaterThan(0);
+  return { httpServer, mcpServer, serverTransport, baseUrl };
+}
 
-    // The MCP server tools are now available to your Mastra Agents
-    const tools = await everArtClient.tools();
+describe('MastraMCPClient with Streamable HTTP', () => {
+  let testServer: {
+    httpServer: HttpServer;
+    mcpServer: McpServer;
+    serverTransport: StreamableHTTPServerTransport;
+    baseUrl: URL;
+  };
+  let client: MastraMCPClient;
 
-    await agent.generate('Can you make me a picture of a dog?', {
-      toolsets: {
-        everart: tools,
-      },
+  describe('Stateless Mode', () => {
+    beforeEach(async () => {
+      testServer = await setupTestServer(false);
+      client = new MastraMCPClient({
+        name: 'test-stateless-client',
+        server: {
+          url: testServer.baseUrl,
+        },
+      });
+      await client.connect();
+    });
+
+    afterEach(async () => {
+      await client?.disconnect().catch(() => {});
+      await testServer?.mcpServer.close().catch(() => {});
+      await testServer?.serverTransport.close().catch(() => {});
+      testServer?.httpServer.close();
+    });
+
+    it('should connect and list tools', async () => {
+      const tools = await client.tools();
+      expect(tools).toHaveProperty('greet');
+      expect(tools.greet.description).toBe('A simple greeting tool');
     });
 
-    expect(Object.keys(tools).length).toBeGreaterThan(0);
-  }, 50000);
+    it('should call a tool', async () => {
+      const tools = await client.tools();
+      const result = await tools.greet.execute({ context: { name: 'Stateless' } });
+      expect(result).toEqual({ content: [{ type: 'text', text: 'Hello, Stateless!' }] });
+    });
+  });
+
+  describe('Stateful Mode', () => {
+    beforeEach(async () => {
+      testServer = await setupTestServer(true);
+      client = new MastraMCPClient({
+        name: 'test-stateful-client',
+        server: {
+          url: testServer.baseUrl,
+        },
+      });
+      await client.connect();
+    });
+
+    afterEach(async () => {
+      await client?.disconnect().catch(() => {});
+      await testServer?.mcpServer.close().catch(() => {});
+      await testServer?.serverTransport.close().catch(() => {});
+      testServer?.httpServer.close();
+    });
+
+    it('should connect and list tools', async () => {
+      const tools = await client.tools();
+      expect(tools).toHaveProperty('greet');
+    });
+
+    it('should capture the session ID after connecting', async () => {
+      // The setupTestServer(true) is configured for stateful mode
+      // The client should capture the session ID from the server's response
+      expect(client.sessionId).toBeDefined();
+      expect(typeof client.sessionId).toBe('string');
+      expect(client.sessionId?.length).toBeGreaterThan(0);
+    });
+
+    it('should call a tool', async () => {
+      const tools = await client.tools();
+      const result = await tools.greet.execute({ context: { name: 'Stateful' } });
+      expect(result).toEqual({ content: [{ type: 'text', text: 'Hello, Stateful!' }] });
+    });
+  });
 });