@mastra/mcp 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/index.js

@@ -1,20 +1,20 @@
+import $RefParser from '@apidevtools/json-schema-ref-parser';
 import { MastraBase } from '@mastra/core/base';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import equal from 'fast-deep-equal';
-import { v5 } from 'uuid';
-import $RefParser from '@apidevtools/json-schema-ref-parser';
 import { createTool } from '@mastra/core/tools';
-import { makeCoreTool, isZodType } from '@mastra/core/utils';
+import { isZodType, makeCoreTool } 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 { ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, CallToolResultSchema, JSONRPCMessageSchema, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ListRootsRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, ProgressNotificationSchema, ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, CallToolResultSchema, ErrorCode, JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
 import { asyncExitHook, gracefulExit } from 'exit-hook';
 import { z } from 'zod';
 import { convertJsonSchemaToZod } from 'zod-from-json-schema';
 import { convertJsonSchemaToZod as convertJsonSchemaToZod$1 } from 'zod-from-json-schema-v3';
+import equal from 'fast-deep-equal';
+import { v5 } from 'uuid';
 import { randomUUID } from 'crypto';
 import { MCPServerBase } from '@mastra/core/mcp';
 import { RequestContext } from '@mastra/core/request-context';
@@ -23,9 +23,9 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
-// src/client/configuration.ts
+// src/client/client.ts
 
-// src/client/elicitationActions.ts
+// src/client/actions/elicitation.ts
 var ElicitationClientActions = class {
   client;
   logger;
@@ -78,6 +78,23 @@ var ElicitationClientActions = class {
     this.client.setElicitationRequestHandler(handler);
   }
 };
+
+// src/client/actions/progress.ts
+var ProgressClientActions = class {
+  client;
+  logger;
+  constructor({ client, logger }) {
+    this.client = client;
+    this.logger = logger;
+  }
+  /**
+   * Set a notification handler for progress updates.
+   * @param handler The callback function to handle progress notifications.
+   */
+  onUpdate(handler) {
+    this.client.setProgressNotificationHandler(handler);
+  }
+};
 var PromptClientActions = class {
   client;
   logger;
@@ -391,15 +408,21 @@ var InternalMastraMCPClient = class extends MastraBase {
   timeout;
   logHandler;
   enableServerLogs;
+  enableProgressTracking;
   serverConfig;
   transport;
   currentOperationContext = null;
+  exitHookUnsubscribe;
+  sigTermHandler;
+  _roots;
   /** Provides access to resource operations (list, read, subscribe, etc.) */
   resources;
   /** Provides access to prompt operations (list, get, notifications) */
   prompts;
   /** Provides access to elicitation operations (request handling) */
   elicitation;
+  /** Provides access to progress operations (notifications) */
+  progress;
   /**
    * @internal
    */
@@ -416,7 +439,15 @@ var InternalMastraMCPClient = class extends MastraBase {
     this.logHandler = server.logger;
     this.enableServerLogs = server.enableServerLogs ?? true;
     this.serverConfig = server;
-    const clientCapabilities = { ...capabilities, elicitation: {} };
+    this.enableProgressTracking = !!server.enableProgressTracking;
+    this._roots = server.roots ?? [];
+    const hasRoots = this._roots.length > 0 || !!capabilities.roots;
+    const clientCapabilities = {
+      ...capabilities,
+      elicitation: {},
+      // Auto-enable roots capability if roots are provided
+      ...hasRoots ? { roots: { listChanged: true, ...capabilities.roots ?? {} } } : {}
+    };
     this.client = new Client(
       {
         name,
@@ -427,9 +458,13 @@ var InternalMastraMCPClient = class extends MastraBase {
       }
     );
     this.setupLogging();
+    if (hasRoots) {
+      this.setupRootsHandler();
+    }
     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 });
+    this.progress = new ProgressClientActions({ client: this, logger: this.logger });
   }
   /**
    * Log a message at the specified level
@@ -468,6 +503,63 @@ var InternalMastraMCPClient = class extends MastraBase {
       );
     }
   }
+  /**
+   * Set up handler for roots/list requests from the server.
+   *
+   * Per MCP spec (https://modelcontextprotocol.io/specification/2025-11-25/client/roots):
+   * When a server sends a roots/list request, the client responds with the configured roots.
+   */
+  setupRootsHandler() {
+    this.log("debug", "Setting up roots/list request handler");
+    this.client.setRequestHandler(ListRootsRequestSchema, async () => {
+      this.log("debug", `Responding to roots/list request with ${this._roots.length} roots`);
+      return { roots: this._roots };
+    });
+  }
+  /**
+   * Get the currently configured roots.
+   *
+   * @returns Array of configured filesystem roots
+   */
+  get roots() {
+    return [...this._roots];
+  }
+  /**
+   * Update the list of filesystem roots and notify the server.
+   *
+   * Per MCP spec, when roots change, the client sends a `notifications/roots/list_changed`
+   * notification to inform the server that it should re-fetch the roots list.
+   *
+   * @param roots - New list of filesystem roots
+   *
+   * @example
+   * ```typescript
+   * await client.setRoots([
+   *   { uri: 'file:///home/user/projects', name: 'Projects' },
+   *   { uri: 'file:///tmp', name: 'Temp' }
+   * ]);
+   * ```
+   */
+  async setRoots(roots) {
+    this.log("debug", `Updating roots to ${roots.length} entries`);
+    this._roots = [...roots];
+    await this.sendRootsListChanged();
+  }
+  /**
+   * Send a roots/list_changed notification to the server.
+   *
+   * Per MCP spec, clients that support `listChanged` MUST send this notification
+   * when the list of roots changes. The server will then call roots/list to get
+   * the updated list.
+   */
+  async sendRootsListChanged() {
+    if (!this.transport) {
+      this.log("debug", "Cannot send roots/list_changed: not connected");
+      return;
+    }
+    this.log("debug", "Sending notifications/roots/list_changed");
+    await this.client.notification({ method: "notifications/roots/list_changed" });
+  }
   async connectStdio(command) {
     this.log("debug", `Using Stdio transport for command: ${command}`);
     try {
@@ -561,14 +653,19 @@ var InternalMastraMCPClient = class extends MastraBase {
         reject(e);
       }
     });
-    asyncExitHook(
-      async () => {
-        this.log("debug", `Disconnecting MCP server during exit`);
-        await this.disconnect();
-      },
-      { wait: 5e3 }
-    );
-    process.on("SIGTERM", () => gracefulExit());
+    if (!this.exitHookUnsubscribe) {
+      this.exitHookUnsubscribe = asyncExitHook(
+        async () => {
+          this.log("debug", `Disconnecting MCP server during exit`);
+          await this.disconnect();
+        },
+        { wait: 5e3 }
+      );
+    }
+    if (!this.sigTermHandler) {
+      this.sigTermHandler = () => gracefulExit();
+      process.on("SIGTERM", this.sigTermHandler);
+    }
     this.log("debug", `Successfully connected to MCP server`);
     return this.isConnected;
   }
@@ -603,8 +700,63 @@ var InternalMastraMCPClient = class extends MastraBase {
       throw e;
     } finally {
       this.transport = void 0;
-      this.isConnected = Promise.resolve(false);
+      this.isConnected = null;
+      if (this.exitHookUnsubscribe) {
+        this.exitHookUnsubscribe();
+        this.exitHookUnsubscribe = void 0;
+      }
+      if (this.sigTermHandler) {
+        process.off("SIGTERM", this.sigTermHandler);
+        this.sigTermHandler = void 0;
+      }
+    }
+  }
+  /**
+   * Checks if an error indicates a session invalidation that requires reconnection.
+   * 
+   * Common session-related errors include:
+   * - "No valid session ID provided" (HTTP 400)
+   * - "Server not initialized" (HTTP 400)
+   * - Connection refused errors
+   * 
+   * @param error - The error to check
+   * @returns true if the error indicates a session problem requiring reconnection
+   * 
+   * @internal
+   */
+  isSessionError(error) {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const errorMessage = error.message.toLowerCase();
+    return errorMessage.includes("no valid session") || errorMessage.includes("session") || errorMessage.includes("server not initialized") || errorMessage.includes("http 400") || errorMessage.includes("http 401") || errorMessage.includes("http 403") || errorMessage.includes("econnrefused") || errorMessage.includes("fetch failed") || errorMessage.includes("connection refused");
+  }
+  /**
+   * Forces a reconnection to the MCP server by disconnecting and reconnecting.
+   * 
+   * This is useful when the session becomes invalid (e.g., after server restart)
+   * and the client needs to establish a fresh connection.
+   * 
+   * @returns Promise resolving when reconnection is complete
+   * @throws {Error} If reconnection fails
+   * 
+   * @internal
+   */
+  async forceReconnect() {
+    this.log("debug", "Forcing reconnection to MCP server...");
+    try {
+      if (this.transport) {
+        await this.transport.close();
+      }
+    } catch (e) {
+      this.log("debug", "Error during force disconnect (ignored)", {
+        error: e instanceof Error ? e.message : String(e)
+      });
     }
+    this.transport = void 0;
+    this.isConnected = null;
+    await this.connect();
+    this.log("debug", "Successfully reconnected to MCP server");
   }
   async listResources() {
     this.log("debug", `Requesting resources from MCP server`);
@@ -692,6 +844,12 @@ var InternalMastraMCPClient = class extends MastraBase {
       return handler(request.params);
     });
   }
+  setProgressNotificationHandler(handler) {
+    this.log("debug", "Setting progress notification handler");
+    this.client.setNotificationHandler(ProgressNotificationSchema, (notification) => {
+      handler(notification.params);
+    });
+  }
   async convertInputSchema(inputSchema) {
     if (isZodType(inputSchema)) {
       return inputSchema;
@@ -765,7 +923,7 @@ var InternalMastraMCPClient = class extends MastraBase {
   }
   async tools() {
     this.log("debug", `Requesting tools from MCP server`);
-    const { tools } = await this.client.listTools({ timeout: this.timeout });
+    const { tools } = await this.client.listTools({}, { timeout: this.timeout });
     const toolsRes = {};
     for (const tool of tools) {
       this.log("debug", `Processing tool: ${tool.name}`);
@@ -778,12 +936,14 @@ var InternalMastraMCPClient = class extends MastraBase {
           execute: async (input, context) => {
             const previousContext = this.currentOperationContext;
             this.currentOperationContext = context?.requestContext || null;
-            try {
-              this.log("debug", `Executing tool: ${tool.name}`, { toolArgs: input });
+            const executeToolCall = async () => {
+              this.log("debug", `Executing tool: ${tool.name}`, { toolArgs: input, runId: context?.runId });
               const res = await this.client.callTool(
                 {
                   name: tool.name,
-                  arguments: input
+                  arguments: input,
+                  // Use runId as progress token if available, otherwise generate a random UUID
+                  ...this.enableProgressTracking ? { _meta: { progressToken: context?.runId || crypto.randomUUID() } } : {}
                 },
                 CallToolResultSchema,
                 {
@@ -791,8 +951,31 @@ var InternalMastraMCPClient = class extends MastraBase {
                 }
               );
               this.log("debug", `Tool executed successfully: ${tool.name}`);
+              if (res.structuredContent !== void 0) {
+                return res.structuredContent;
+              }
               return res;
+            };
+            try {
+              return await executeToolCall();
             } catch (e) {
+              if (this.isSessionError(e)) {
+                this.log("debug", `Session error detected for tool ${tool.name}, attempting reconnection...`, {
+                  error: e instanceof Error ? e.message : String(e)
+                });
+                try {
+                  await this.forceReconnect();
+                  this.log("debug", `Retrying tool ${tool.name} after reconnection...`);
+                  return await executeToolCall();
+                } catch (reconnectError) {
+                  this.log("error", `Reconnection or retry failed for tool ${tool.name}`, {
+                    originalError: e instanceof Error ? e.message : String(e),
+                    reconnectError: reconnectError instanceof Error ? reconnectError.stack : String(reconnectError),
+                    toolArgs: input
+                  });
+                  throw e;
+                }
+              }
               this.log("error", `Error calling tool: ${tool.name}`, {
                 error: e instanceof Error ? e.stack : JSON.stringify(e, null, 2),
                 toolArgs: input
@@ -816,8 +999,6 @@ var InternalMastraMCPClient = class extends MastraBase {
     return toolsRes;
   }
 };
-
-// src/client/configuration.ts
 var mcpClientInstances = /* @__PURE__ */ new Map();
 var MCPClient = class extends MastraBase {
   serverConfigs = {};
@@ -890,6 +1071,48 @@ To fix this you have three different options:
     this.addToInstanceCache();
     return this;
   }
+  /**
+   * Provides access to progress-related operations for tracking long-running operations.
+   *
+   * Progress tracking allows MCP servers to send updates about the status of ongoing operations,
+   * providing real-time feedback to users about task completion and current state.
+   *
+   * @example
+   * ```typescript
+   * // Set up handler for progress updates from a server
+   * await mcp.progress.onUpdate('serverName', (params) => {
+   *   console.log(`Progress: ${params.progress}%`);
+   *   console.log(`Status: ${params.message}`);
+   *   
+   *   if (params.total) {
+   *     console.log(`Completed ${params.progress} of ${params.total} items`);
+   *   }
+   * });
+   * ```
+   */
+  get progress() {
+    this.addToInstanceCache();
+    return {
+      onUpdate: async (serverName, handler) => {
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.progress.onUpdate(handler);
+        } catch (err) {
+          throw new MastraError(
+            {
+              id: "MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED",
+              domain: ErrorDomain.MCP,
+              category: ErrorCategory.THIRD_PARTY,
+              details: {
+                serverName
+              }
+            },
+            err
+          );
+        }
+      }
+    };
+  }
   /**
    * Provides access to elicitation-related operations for interactive user input collection.
    *
@@ -2180,6 +2403,41 @@ var MCPServer = class extends MCPServerBase {
     this.logger.debug(`Received elicitation response: ${JSON.stringify(response)}`);
     return response;
   }
+  /**
+   * Reads and parses the JSON body from an HTTP request.
+   * If the request body was already parsed by middleware (e.g., express.json()),
+   * it uses the pre-parsed body from req.body. Otherwise, it reads from the stream.
+   *
+   * This allows the MCP server to work with Express apps that use express.json()
+   * globally without requiring special route exclusions.
+   *
+   * @param req - The incoming HTTP request
+   * @param options - Optional configuration
+   * @param options.preParsedOnly - If true, only return pre-parsed body from middleware,
+   *   returning undefined if not available. This allows the caller to fall back to
+   *   their own body reading logic (e.g., SDK's getRawBody with size limits).
+   */
+  async readJsonBody(req, options) {
+    const reqWithBody = req;
+    if (reqWithBody.body !== void 0) {
+      return reqWithBody.body;
+    }
+    if (options?.preParsedOnly) {
+      return void 0;
+    }
+    return new Promise((resolve, reject) => {
+      let data = "";
+      req.on("data", (chunk) => data += chunk);
+      req.on("end", () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (e) {
+          reject(e);
+        }
+      });
+      req.on("error", reject);
+    });
+  }
   /**
    * Creates a new Server instance configured with all handlers for HTTP sessions.
    * Each HTTP client connection gets its own Server instance to avoid routing conflicts.
@@ -2568,7 +2826,9 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           try {
             const proxiedContext = context?.requestContext || new RequestContext();
             if (context?.mcp?.extra) {
-              proxiedContext.set("mcp.extra", context.mcp.extra);
+              Object.entries(context.mcp.extra).forEach(([key, value]) => {
+                proxiedContext.set(key, value);
+              });
             }
             const response = await agent.generate(inputData.message, {
               ...context ?? {},
@@ -2637,10 +2897,16 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             inputData
           );
           try {
-            const run2 = await workflow.createRun({ runId: context?.requestContext?.get("runId") });
+            const proxiedContext = context?.requestContext || new RequestContext();
+            if (context?.mcp?.extra) {
+              Object.entries(context.mcp.extra).forEach(([key, value]) => {
+                proxiedContext.set(key, value);
+              });
+            }
+            const run2 = await workflow.createRun({ runId: proxiedContext?.get("runId") });
             const response = await run2.start({
               inputData,
-              requestContext: context?.requestContext,
+              requestContext: proxiedContext,
               tracingContext: context?.tracingContext
             });
             return response;
@@ -2796,7 +3062,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    *
    * @example
    * ```typescript
-   * import http from 'http';
+   * import http from 'node:http';
    *
    * const httpServer = http.createServer(async (req, res) => {
    *   await server.startSSE({
@@ -2827,7 +3093,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           res.end("SSE connection not established");
           return;
         }
-        await this.sseTransport.handlePostMessage(req, res);
+        const parsedBody = await this.readJsonBody(req, { preParsedOnly: true });
+        await this.sseTransport.handlePostMessage(req, res, parsedBody);
       } else {
         this.logger.debug("Unknown path:", { path: url.pathname });
         res.writeHead(404);
@@ -2954,8 +3221,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    *
    * @example
    * ```typescript
-   * import http from 'http';
-   * import { randomUUID } from 'crypto';
+   * import http from 'node:http';
+   * import { randomUUID } from 'node:crypto';
    *
    * const httpServer = http.createServer(async (req, res) => {
    *   await server.startHTTP({
@@ -2999,7 +3266,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     httpPath,
     req,
     res,
-    options = { sessionIdGenerator: () => randomUUID() }
+    options
   }) {
     this.logger.debug(`startHTTP: Received ${req.method} request to ${url.pathname}`);
     if (url.pathname !== httpPath) {
@@ -3008,11 +3275,18 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       res.end();
       return;
     }
-    if (options?.serverless) {
-      this.logger.debug("startHTTP: Running in serverless (stateless) mode");
+    const isStatelessMode = options?.serverless || options && "sessionIdGenerator" in options && options.sessionIdGenerator === void 0;
+    if (isStatelessMode) {
+      this.logger.debug("startHTTP: Running in stateless mode (serverless or sessionIdGenerator: undefined)");
       await this.handleServerlessRequest(req, res);
       return;
     }
+    const mergedOptions = {
+      sessionIdGenerator: () => randomUUID(),
+      // default: enabled
+      ...options
+      // user-provided overrides default
+    };
     const sessionId = req.headers["mcp-session-id"];
     let transport;
     this.logger.debug(
@@ -3027,40 +3301,18 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             `startHTTP: Handling GET request for existing session ${sessionId}. Calling transport.handleRequest.`
           );
         }
-        const body = req.method === "POST" ? await new Promise((resolve, reject) => {
-          let data = "";
-          req.on("data", (chunk) => data += chunk);
-          req.on("end", () => {
-            try {
-              resolve(JSON.parse(data));
-            } catch (e) {
-              reject(e);
-            }
-          });
-          req.on("error", reject);
-        }) : void 0;
+        const body = req.method === "POST" ? await this.readJsonBody(req) : void 0;
         await transport.handleRequest(req, res, body);
       } else {
         this.logger.debug(`startHTTP: No existing Streamable HTTP session ID found. ${req.method}`);
         if (req.method === "POST") {
-          const body = await new Promise((resolve, reject) => {
-            let data = "";
-            req.on("data", (chunk) => data += chunk);
-            req.on("end", () => {
-              try {
-                resolve(JSON.parse(data));
-              } catch (e) {
-                reject(e);
-              }
-            });
-            req.on("error", reject);
-          });
+          const body = await this.readJsonBody(req);
           const { isInitializeRequest } = await import('@modelcontextprotocol/sdk/types.js');
           if (isInitializeRequest(body)) {
             this.logger.debug("startHTTP: Received Streamable HTTP initialize request, creating new transport.");
             transport = new StreamableHTTPServerTransport({
-              ...options,
-              sessionIdGenerator: () => randomUUID(),
+              ...mergedOptions,
+              sessionIdGenerator: mergedOptions.sessionIdGenerator,
               onsessioninitialized: (id) => {
                 this.streamableHTTPTransports.set(id, transport);
               }
@@ -3164,18 +3416,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
   async handleServerlessRequest(req, res) {
     try {
       this.logger.debug(`handleServerlessRequest: Received ${req.method} request`);
-      const body = req.method === "POST" ? await new Promise((resolve, reject) => {
-        let data = "";
-        req.on("data", (chunk) => data += chunk);
-        req.on("end", () => {
-          try {
-            resolve(JSON.parse(data));
-          } catch (e) {
-            reject(new Error(`Invalid JSON in request body: ${e instanceof Error ? e.message : String(e)}`));
-          }
-        });
-        req.on("error", reject);
-      }) : void 0;
+      const body = req.method === "POST" ? await this.readJsonBody(req) : void 0;
       this.logger.debug(`handleServerlessRequest: Processing ${req.method} request`, {
         method: body?.method,
         id: body?.id
@@ -3606,6 +3847,6 @@ Provided arguments: ${JSON.stringify(args, null, 2)}`,
   }
 };
 
-export { MCPClient, MCPServer };
+export { InternalMastraMCPClient, MCPClient, MCPServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map