@mastra/mcp 0.14.2 → 1.0.0-beta.1

package/dist/index.js

@@ -1,29 +1,29 @@
-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 { 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 { 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 { 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 { RuntimeContext } from '@mastra/core/runtime-context';
+import { RequestContext } from '@mastra/core/request-context';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 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/client.ts
+// src/client/configuration.ts
 
 // src/client/elicitationActions.ts
 var ElicitationClientActions = class {
@@ -447,7 +447,7 @@ var InternalMastraMCPClient = class extends MastraBase {
         timestamp: /* @__PURE__ */ new Date(),
         serverName: this.name,
         details,
-        runtimeContext: this.currentOperationContext
+        requestContext: this.currentOperationContext
       });
     }
   }
@@ -777,15 +777,15 @@ var InternalMastraMCPClient = class extends MastraBase {
           description: tool.description || "",
           inputSchema: await this.convertInputSchema(tool.inputSchema),
           outputSchema: await this.convertOutputSchema(tool.outputSchema),
-          execute: async ({ context, runtimeContext }) => {
+          execute: async (input, context) => {
             const previousContext = this.currentOperationContext;
-            this.currentOperationContext = runtimeContext || null;
+            this.currentOperationContext = context?.requestContext || null;
             try {
-              this.log("debug", `Executing tool: ${tool.name}`, { toolArgs: context });
+              this.log("debug", `Executing tool: ${tool.name}`, { toolArgs: input });
               const res = await this.client.callTool(
                 {
                   name: tool.name,
-                  arguments: context
+                  arguments: input
                 },
                 CallToolResultSchema,
                 {
@@ -797,7 +797,7 @@ var InternalMastraMCPClient = class extends MastraBase {
             } catch (e) {
               this.log("error", `Error calling tool: ${tool.name}`, {
                 error: e instanceof Error ? e.stack : JSON.stringify(e, null, 2),
-                toolArgs: context
+                toolArgs: input
               });
               throw e;
             } finally {
@@ -818,19 +818,8 @@ var InternalMastraMCPClient = class extends MastraBase {
     return toolsRes;
   }
 };
-var MastraMCPClient = class extends InternalMastraMCPClient {
-  constructor(args) {
-    super(args);
-    throw new MastraError(
-      {
-        id: "MASTRA_MCP_CLIENT_DEPRECATED",
-        domain: ErrorDomain.MCP,
-        category: ErrorCategory.USER,
-        text: "[DEPRECATION] MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead."
-      }
-    );
-  }
-};
+
+// src/client/configuration.ts
 var mcpClientInstances = /* @__PURE__ */ new Map();
 var MCPClient = class extends MastraBase {
   serverConfigs = {};
@@ -1431,14 +1420,15 @@ To fix this you have three different options:
    * @example
    * ```typescript
    * const agent = new Agent({
+   *   id: 'multi-tool-agent',
    *   name: 'Multi-tool Agent',
    *   instructions: 'You have access to weather and stock tools.',
    *   model: 'openai/gpt-4',
-   *   tools: await mcp.getTools(), // weather_getWeather, stockPrice_getPrice
+   *   tools: await mcp.listTools(), // weather_getWeather, stockPrice_getPrice
    * });
    * ```
    */
-  async getTools() {
+  async listTools() {
     this.addToInstanceCache();
     const connectedTools = {};
     try {
@@ -1462,7 +1452,7 @@ To fix this you have three different options:
   /**
    * Returns toolsets organized by server name for dynamic tool injection.
    *
-   * Unlike getTools(), this returns tools grouped by server without namespacing.
+   * Unlike listTools(), this returns tools grouped by server without namespacing.
    * This is intended to be passed dynamically to the generate() or stream() method.
    *
    * @returns Object mapping server names to their tool collections
@@ -1471,17 +1461,18 @@ To fix this you have three different options:
    * @example
    * ```typescript
    * const agent = new Agent({
+   *   id: 'dynamic-agent',
    *   name: 'Dynamic Agent',
    *   instructions: 'You can use tools dynamically.',
    *   model: 'openai/gpt-4',
    * });
    *
    * const response = await agent.stream(prompt, {
-   *   toolsets: await mcp.getToolsets(), // { weather: {...}, stockPrice: {...} }
+   *   toolsets: await mcp.listToolsets(), // { weather: {...}, stockPrice: {...} }
    * });
    * ```
    */
-  async getToolsets() {
+  async listToolsets() {
     this.addToInstanceCache();
     const connectedToolsets = {};
     try {
@@ -1502,12 +1493,6 @@ To fix this you have three different options:
     }
     return connectedToolsets;
   }
-  /**
-   * @deprecated all resource actions have been moved to the this.resources object. Use this.resources.list() instead.
-   */
-  async getResources() {
-    return this.resources.list();
-  }
   /**
    * Gets current session IDs for all connected MCP clients using Streamable HTTP transport.
    *
@@ -1594,24 +1579,8 @@ To fix this you have three different options:
     );
   }
 };
-var MCPConfiguration = class extends MCPClient {
-  /**
-   * @deprecated Use MCPClient constructor instead
-   */
-  constructor(args) {
-    super(args);
-    throw new MastraError(
-      {
-        id: "MCP_CLIENT_CONFIGURATION_DEPRECATED",
-        domain: ErrorDomain.MCP,
-        category: ErrorCategory.USER,
-        text: "[DEPRECATION] 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/hono@4.10.1/node_modules/hono/dist/utils/stream.js
+// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/utils/stream.js
 var StreamingApi = class {
   writer;
   encoder;
@@ -1678,7 +1647,7 @@ var StreamingApi = class {
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.10.1/node_modules/hono/dist/helper/streaming/utils.js
+// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/helper/streaming/utils.js
 var isOldBunVersion = () => {
   const version = typeof Bun !== "undefined" ? Bun.version : void 0;
   if (version === void 0) {
@@ -1689,7 +1658,7 @@ var isOldBunVersion = () => {
   return result;
 };
 
-// ../../node_modules/.pnpm/hono@4.10.1/node_modules/hono/dist/utils/html.js
+// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/utils/html.js
 var HtmlEscapedCallbackPhase = {
   Stringify: 1};
 var resolveCallback = async (str, phase, preserveCallbacks, context, buffer) => {
@@ -1720,7 +1689,7 @@ var resolveCallback = async (str, phase, preserveCallbacks, context, buffer) =>
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.10.1/node_modules/hono/dist/helper/streaming/sse.js
+// ../../node_modules/.pnpm/hono@4.10.3/node_modules/hono/dist/helper/streaming/sse.js
 var SSEStreamingApi = class extends StreamingApi {
   constructor(writable, readable) {
     super(writable, readable);
@@ -2131,7 +2100,8 @@ var MCPServer = class extends MCPServerBase {
    * import { z } from 'zod';
    *
    * const myAgent = new Agent({
-   *   name: 'Helper',
+   *   id: 'helper',
+   *   name: 'Helper Agent',
    *   description: 'A helpful assistant',
    *   instructions: 'You are helpful.',
    *   model: 'openai/gpt-4o-mini',
@@ -2145,7 +2115,7 @@ var MCPServer = class extends MCPServerBase {
    *       id: 'getWeather',
    *       description: 'Gets weather',
    *       inputSchema: z.object({ location: z.string() }),
-   *       execute: async ({ context }) => `Sunny in ${context.location}`,
+   *       execute: async (inputData) => `Sunny in ${inputData.location}`,
    *     })
    *   },
    *   agents: { myAgent },
@@ -2242,7 +2212,7 @@ var MCPServer = class extends MCPServerBase {
       return {
         tools: Object.values(this.convertedTools).map((tool) => {
           const toolSpec = {
-            name: tool.name,
+            name: tool.id || "unknown",
             description: tool.description,
             inputSchema: tool.parameters.jsonSchema
           };
@@ -2301,12 +2271,23 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             return this.handleElicitationRequest(request2, serverInstance);
           }
         };
-        const result = await tool.execute(validation?.value ?? request.params.arguments ?? {}, {
+        const mcpOptions = {
           messages: [],
           toolCallId: "",
-          elicitation: sessionElicitation,
-          extra
-        });
+          // Pass MCP-specific context through the mcp property
+          mcp: {
+            elicitation: sessionElicitation,
+            extra
+          },
+          // @ts-ignore this is to let people know that the elicitation and extra keys are now nested under mcp.elicitation and mcp.extra in tool arguments
+          get elicitation() {
+            throw new Error(`The "elicitation" key is now nested under "mcp.elicitation" in tool arguments`);
+          },
+          get extra() {
+            throw new Error(`The "extra" key is now nested under "mcp.extra" in tool arguments`);
+          }
+        };
+        const result = await tool.execute(validation?.value ?? request.params.arguments ?? {}, mcpOptions);
         this.logger.debug(`CallTool: Tool '${request.params.name}' executed successfully with result:`, result);
         const duration = Date.now() - startTime;
         this.logger.info(`Tool '${request.params.name}' executed successfully in ${duration}ms.`);
@@ -2582,12 +2563,19 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
         inputSchema: z.object({
           message: z.string().describe("The question or input for the agent.")
         }),
-        execute: async ({ context, runtimeContext, tracingContext }) => {
+        execute: async (inputData, context) => {
           this.logger.debug(
-            `Executing agent tool '${agentToolName}' for agent '${agent.name}' with message: "${context.message}"`
+            `Executing agent tool '${agentToolName}' for agent '${agent.name}' with message: "${inputData.message}"`
           );
           try {
-            const response = await agent.generate(context.message, { runtimeContext, tracingContext });
+            const proxiedContext = context?.requestContext || new RequestContext();
+            if (context?.mcp?.extra) {
+              proxiedContext.set("mcp.extra", context.mcp.extra);
+            }
+            const response = await agent.generate(inputData.message, {
+              ...context ?? {},
+              requestContext: proxiedContext
+            });
             return response;
           } catch (error) {
             this.logger.error(`Error executing agent tool '${agentToolName}' for agent '${agent.name}':`, error);
@@ -2599,17 +2587,17 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
         name: agentToolName,
         logger: this.logger,
         mastra: this.mastra,
-        runtimeContext: new RuntimeContext(),
+        requestContext: new RequestContext(),
         tracingContext: {},
         description: agentToolDefinition.description
       };
       const coreTool = makeCoreTool(agentToolDefinition, options);
       agentTools[agentToolName] = {
-        name: agentToolName,
-        description: coreTool.description,
-        parameters: coreTool.parameters,
-        execute: coreTool.execute,
-        toolType: "agent"
+        ...coreTool,
+        id: agentToolName,
+        mcp: {
+          toolType: "agent"
+        }
       };
       this.logger.info(`Registered agent '${agent.name}' (key: '${agentKey}') as tool: '${agentToolName}'`);
     }
@@ -2645,14 +2633,18 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
         id: workflowToolName,
         description: `Run workflow '${workflowKey}'. Workflow description: ${workflowDescription}`,
         inputSchema: workflow.inputSchema,
-        execute: async ({ context, runtimeContext, tracingContext }) => {
+        execute: async (inputData, context) => {
           this.logger.debug(
             `Executing workflow tool '${workflowToolName}' for workflow '${workflow.id}' with input:`,
-            context
+            inputData
           );
           try {
-            const run2 = await workflow.createRunAsync({ runId: runtimeContext?.get("runId") });
-            const response = await run2.start({ inputData: context, runtimeContext, tracingContext });
+            const run2 = await workflow.createRun({ runId: context?.requestContext?.get("runId") });
+            const response = await run2.start({
+              inputData,
+              requestContext: context?.requestContext,
+              tracingContext: context?.tracingContext
+            });
             return response;
           } catch (error) {
             this.logger.error(
@@ -2667,18 +2659,17 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
         name: workflowToolName,
         logger: this.logger,
         mastra: this.mastra,
-        runtimeContext: new RuntimeContext(),
+        requestContext: new RequestContext(),
         tracingContext: {},
         description: workflowToolDefinition.description
       };
       const coreTool = makeCoreTool(workflowToolDefinition, options);
       workflowTools[workflowToolName] = {
-        name: workflowToolName,
-        description: coreTool.description,
-        parameters: coreTool.parameters,
-        outputSchema: coreTool.outputSchema,
-        execute: coreTool.execute,
-        toolType: "workflow"
+        ...coreTool,
+        id: workflowToolName,
+        mcp: {
+          toolType: "workflow"
+        }
       };
       this.logger.info(`Registered workflow '${workflow.id}' (key: '${workflowKey}') as tool: '${workflowToolName}'`);
     }
@@ -2706,7 +2697,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       }
       const options = {
         name: toolName,
-        runtimeContext: new RuntimeContext(),
+        requestContext: new RequestContext(),
         tracingContext: {},
         mastra: this.mastra,
         logger: this.logger,
@@ -2714,11 +2705,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       };
       const coreTool = makeCoreTool(toolInstance, options);
       definedConvertedTools[toolName] = {
-        name: toolName,
-        description: coreTool.description,
-        parameters: coreTool.parameters,
-        outputSchema: coreTool.outputSchema,
-        execute: coreTool.execute
+        ...coreTool,
+        id: toolName
       };
       this.logger.info(`Registered explicit tool: '${toolName}'`);
     }
@@ -2962,6 +2950,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    * @param options.options.onsessioninitialized - Callback when a new session is initialized
    * @param options.options.enableJsonResponse - If true, return JSON instead of SSE streaming
    * @param options.options.eventStore - Event store for message resumability
+   * @param options.options.serverless - If true, run in stateless mode without session management (ideal for serverless environments)
    *
    * @throws {MastraError} If HTTP connection setup fails
    *
@@ -2987,6 +2976,25 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    *
    * httpServer.listen(1234);
    * ```
+   *
+   * @example Serverless mode (Cloudflare Workers, Vercel Edge, etc.)
+   * ```typescript
+   * export default {
+   *   async fetch(request: Request) {
+   *     const url = new URL(request.url);
+   *     if (url.pathname === '/mcp') {
+   *       await server.startHTTP({
+   *         url,
+   *         httpPath: '/mcp',
+   *         req: request,
+   *         res: response,
+   *         options: { serverless: true },
+   *       });
+   *     }
+   *     return new Response('Not found', { status: 404 });
+   *   },
+   * };
+   * ```
    */
   async startHTTP({
     url,
@@ -3002,6 +3010,11 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       res.end();
       return;
     }
+    if (options?.serverless) {
+      this.logger.debug("startHTTP: Running in serverless (stateless) mode");
+      await this.handleServerlessRequest(req, res);
+      return;
+    }
     const sessionId = req.headers["mcp-session-id"];
     let transport;
     this.logger.debug(
@@ -3137,6 +3150,74 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       }
     }
   }
+  /**
+   * Handles a stateless, serverless HTTP request without session management.
+   *
+   * This method bypasses all session/transport state and handles each request independently.
+   * For serverless environments (Cloudflare Workers, Vercel Edge, etc.) where
+   * persistent connections and session state cannot be maintained across requests.
+   *
+   * Each request gets a fresh transport and server instance that are discarded after the response.
+   *
+   * @param req - Incoming HTTP request
+   * @param res - HTTP response object
+   * @private
+   */
+  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;
+      this.logger.debug(`handleServerlessRequest: Processing ${req.method} request`, {
+        method: body?.method,
+        id: body?.id
+      });
+      const transientServer = this.createServerInstance();
+      const tempTransport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: void 0,
+        enableJsonResponse: true
+      });
+      await transientServer.connect(tempTransport);
+      await tempTransport.handleRequest(req, res, body);
+      this.logger.debug(`handleServerlessRequest: Completed ${body?.method} request`, { id: body?.id });
+    } catch (error) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_SERVERLESS_REQUEST_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          text: "Failed to handle serverless MCP request"
+        },
+        error
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("handleServerlessRequest: Error handling request:", { error: mastraError });
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: "Internal server error",
+              data: error instanceof Error ? error.message : String(error)
+            },
+            id: null
+          })
+        );
+      }
+    }
+  }
   /**
    * Establishes the SSE connection for the MCP server.
    *
@@ -3385,11 +3466,11 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     return {
       tools: Object.entries(this.convertedTools).map(([toolId, tool]) => ({
         id: toolId,
-        name: tool.name,
+        name: tool.id || toolId,
         description: tool.description,
         inputSchema: tool.parameters?.jsonSchema || tool.parameters,
         outputSchema: tool.outputSchema?.jsonSchema || tool.outputSchema,
-        toolType: tool.toolType
+        toolType: tool.mcp?.toolType
       }))
     };
   }
@@ -3419,11 +3500,11 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     }
     this.logger.debug(`Getting info for tool '${toolId}' on MCPServer '${this.name}'`);
     return {
-      name: tool.name,
+      name: tool.id || toolId,
       description: tool.description,
       inputSchema: tool.parameters?.jsonSchema || tool.parameters,
       outputSchema: tool.outputSchema?.jsonSchema || tool.outputSchema,
-      toolType: tool.toolType
+      toolType: tool.mcp?.toolType
     };
   }
   /**
@@ -3527,6 +3608,6 @@ Provided arguments: ${JSON.stringify(args, null, 2)}`,
   }
 };
 
-export { MCPClient, MCPConfiguration, MCPServer, MastraMCPClient };
+export { MCPClient, MCPServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map