@mastra/mcp-docs-server 0.13.37 → 0.13.38

package/.docs/raw/reference/tools/mcp-client.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MCPClient | Tool Management | Mastra Docs"
+title: "Reference: MCPClient | Tools & MCP | Mastra Docs"
 description: API Reference for MCPClient - A class for managing multiple Model Context Protocol servers and their tools.
 ---
 
@@ -318,15 +318,15 @@ const mcpClient = new MCPClient({
 });
 
 // Set up elicitation handler
-mcpClient.elicitation.onRequest('serverName', async (request) => {
+mcpClient.elicitation.onRequest("serverName", async (request) => {
   // Handle elicitation request from server
-  console.log('Server requests:', request.message);
-  console.log('Schema:', request.requestedSchema);
-  
+  console.log("Server requests:", request.message);
+  console.log("Schema:", request.requestedSchema);
+
   // Return user response
   return {
-    action: 'accept',
-    content: { name: 'John Doe', email: 'john@example.com' }
+    action: "accept",
+    content: { name: "John Doe", email: "john@example.com" },
   };
 });
 ```
@@ -338,41 +338,43 @@ Sets up a handler function that will be called when any connected MCP server sen
 **ElicitationHandler Function:**
 
 The handler function receives a request object with:
+
 - `message`: A human-readable message describing what information is needed
 - `requestedSchema`: A JSON schema defining the structure of the expected response
 
 The handler must return an `ElicitResult` with:
+
 - `action`: One of `'accept'`, `'decline'`, or `'cancel'`
 - `content`: The user's data (only when action is `'accept'`)
 
 **Example:**
 
 ```typescript
-mcpClient.elicitation.onRequest('serverName', async (request) => {
+mcpClient.elicitation.onRequest("serverName", async (request) => {
   console.log(`Server requests: ${request.message}`);
-  
+
   // Example: Simple user input collection
   if (request.requestedSchema.properties.name) {
     // Simulate user accepting and providing data
     return {
-      action: 'accept',
+      action: "accept",
       content: {
-        name: 'Alice Smith',
-        email: 'alice@example.com'
-      }
+        name: "Alice Smith",
+        email: "alice@example.com",
+      },
     };
   }
-  
+
   // Simulate user declining the request
-  return { action: 'decline' };
+  return { action: "decline" };
 });
 ```
 
 **Complete Interactive Example:**
 
 ```typescript
-import { MCPClient } from '@mastra/mcp';
-import { createInterface } from 'readline';
+import { MCPClient } from "@mastra/mcp";
+import { createInterface } from "readline";
 
 const readline = createInterface({
   input: process.stdin,
@@ -380,69 +382,71 @@ const readline = createInterface({
 });
 
 function askQuestion(question: string): Promise<string> {
-  return new Promise(resolve => {
-    readline.question(question, answer => resolve(answer.trim()));
+  return new Promise((resolve) => {
+    readline.question(question, (answer) => resolve(answer.trim()));
   });
 }
 
 const mcpClient = new MCPClient({
   servers: {
     interactiveServer: {
-      url: new URL('http://localhost:3000/mcp'),
+      url: new URL("http://localhost:3000/mcp"),
     },
   },
 });
 
 // Set up interactive elicitation handler
-await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
   console.log(`\n📋 Server Request: ${request.message}`);
-  console.log('Required information:');
-  
+  console.log("Required information:");
+
   const schema = request.requestedSchema;
   const properties = schema.properties || {};
   const required = schema.required || [];
   const content: Record<string, any> = {};
-  
+
   // Collect input for each field
   for (const [fieldName, fieldSchema] of Object.entries(properties)) {
     const field = fieldSchema as any;
     const isRequired = required.includes(fieldName);
-    
+
     let prompt = `${field.title || fieldName}`;
     if (field.description) prompt += ` (${field.description})`;
-    if (isRequired) prompt += ' *required*';
-    prompt += ': ';
-    
+    if (isRequired) prompt += " *required*";
+    prompt += ": ";
+
     const answer = await askQuestion(prompt);
-    
+
     // Handle cancellation
-    if (answer.toLowerCase() === 'cancel') {
-      return { action: 'cancel' };
+    if (answer.toLowerCase() === "cancel") {
+      return { action: "cancel" };
     }
-    
+
     // Validate required fields
-    if (answer === '' && isRequired) {
+    if (answer === "" && isRequired) {
       console.log(`❌ ${fieldName} is required`);
-      return { action: 'decline' };
+      return { action: "decline" };
     }
-    
-    if (answer !== '') {
+
+    if (answer !== "") {
       content[fieldName] = answer;
     }
   }
-  
+
   // Confirm submission
-  console.log('\n📝 You provided:');
+  console.log("\n📝 You provided:");
   console.log(JSON.stringify(content, null, 2));
-  
-  const confirm = await askQuestion('\nSubmit this information? (yes/no/cancel): ');
-  
-  if (confirm.toLowerCase() === 'yes' || confirm.toLowerCase() === 'y') {
-    return { action: 'accept', content };
-  } else if (confirm.toLowerCase() === 'cancel') {
-    return { action: 'cancel' };
+
+  const confirm = await askQuestion(
+    "\nSubmit this information? (yes/no/cancel): ",
+  );
+
+  if (confirm.toLowerCase() === "yes" || confirm.toLowerCase() === "y") {
+    return { action: "accept", content };
+  } else if (confirm.toLowerCase() === "cancel") {
+    return { action: "cancel" };
   } else {
-    return { action: 'decline' };
+    return { action: "decline" };
   }
 });
 ```
@@ -529,27 +533,27 @@ Elicitation is a feature that allows MCP servers to request structured informati
 You must set up an elicitation handler before tools that use elicitation are called:
 
 ```typescript
-import { MCPClient } from '@mastra/mcp';
+import { MCPClient } from "@mastra/mcp";
 
 const mcpClient = new MCPClient({
   servers: {
     interactiveServer: {
-      url: new URL('http://localhost:3000/mcp'),
+      url: new URL("http://localhost:3000/mcp"),
     },
   },
 });
 
 // Set up elicitation handler
-mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
   // Handle the server's request for user input
   console.log(`Server needs: ${request.message}`);
-  
+
   // Your logic to collect user input
   const userData = await collectUserInput(request.requestedSchema);
-  
+
   return {
-    action: 'accept',
-    content: userData
+    action: "accept",
+    content: userData,
   };
 });
 ```
@@ -559,21 +563,23 @@ mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
 Your elicitation handler must return one of three response types:
 
 - **Accept**: User provided data and confirmed submission
+
   ```typescript
   return {
-    action: 'accept',
-    content: { name: 'John Doe', email: 'john@example.com' }
+    action: "accept",
+    content: { name: "John Doe", email: "john@example.com" },
   };
   ```
 
 - **Decline**: User explicitly declined to provide the information
+
   ```typescript
-  return { action: 'decline' };
+  return { action: "decline" };
   ```
 
 - **Cancel**: User dismissed or cancelled the request
   ```typescript
-  return { action: 'cancel' };
+  return { action: "cancel" };
   ```
 
 ### Schema-Based Input Collection
@@ -581,14 +587,14 @@ Your elicitation handler must return one of three response types:
 The `requestedSchema` provides structure for the data the server needs:
 
 ```typescript
-await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
   const { properties, required = [] } = request.requestedSchema;
   const content: Record<string, any> = {};
-  
+
   for (const [fieldName, fieldSchema] of Object.entries(properties || {})) {
     const field = fieldSchema as any;
     const isRequired = required.includes(fieldName);
-    
+
     // Collect input based on field type and requirements
     const value = await promptUser({
       name: fieldName,
@@ -599,13 +605,13 @@ await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
       format: field.format,
       enum: field.enum,
     });
-    
+
     if (value !== null) {
       content[fieldName] = value;
     }
   }
-  
-  return { action: 'accept', content };
+
+  return { action: "accept", content };
 });
 ```
 
@@ -679,7 +685,7 @@ async function checkWeatherPrompt() {
     const weatherPrompts = await mcp.prompts.list();
     if (weatherPrompts.weather && weatherPrompts.weather.length > 0) {
       const currentWeatherPrompt = weatherPrompts.weather.find(
-        (p) => p.name === "current"
+        (p) => p.name === "current",
       );
       if (currentWeatherPrompt) {
         console.log("Weather prompt:", currentWeatherPrompt);

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MCPServer | Exposing Mastra Tools via MCP | Mastra Docs"
+title: "Reference: MCPServer | Tools & MCP | Mastra Docs"
 description: API Reference for MCPServer - A class for exposing Mastra tools and capabilities as a Model Context Protocol server.
 ---
 
@@ -165,7 +165,6 @@ A powerful feature of `MCPServer` is its ability to automatically expose your Ma
 - **Tool Naming**: Each agent is converted into a tool named `ask_<agentKey>`, where `<agentKey>` is the key you used for that agent in the `agents` object. For instance, if you configure `agents: { myAgentKey: myAgentInstance }`, a tool named `ask_myAgentKey` will be created.
 
 - **Tool Functionality**:
-
   - **Description**: The generated tool's description will be in the format: "Ask agent `<AgentName>` a question. Original agent instructions: `<agent description>`".
   - **Input**: The tool expects a single object argument with a `message` property (string): `{ message: "Your question for the agent" }`.
   - **Execution**: When this tool is called, it invokes the `generate()` method of the corresponding agent, passing the provided `query`.
@@ -383,7 +382,7 @@ import http from "http";
 
 const httpServer = http.createServer(async (req, res) => {
   await server.startHTTP({
-    url: new URL(req.url || '', 'http://localhost:1234'),
+    url: new URL(req.url || "", "http://localhost:1234"),
     httpPath: `/mcp`,
     req,
     res,
@@ -403,32 +402,32 @@ Here are the details for the values needed by the `startHTTP` method:
 <PropertiesTable
   content={[
     {
-      name: 'url',
-      type: 'URL',
-      description: 'The web address the user is requesting.',
+      name: "url",
+      type: "URL",
+      description: "The web address the user is requesting.",
     },
     {
-      name: 'httpPath',
-      type: 'string',
+      name: "httpPath",
+      type: "string",
       description:
         "The specific part of the URL where the MCP server will handle HTTP requests (e.g., '/mcp').",
     },
     {
-      name: 'req',
-      type: 'http.IncomingMessage',
-      description: 'The incoming request object from your web server.',
+      name: "req",
+      type: "http.IncomingMessage",
+      description: "The incoming request object from your web server.",
     },
     {
-      name: 'res',
-      type: 'http.ServerResponse',
+      name: "res",
+      type: "http.ServerResponse",
       description:
-        'The response object from your web server, used to send data back.',
+        "The response object from your web server, used to send data back.",
     },
     {
-      name: 'options',
-      type: 'StreamableHTTPServerTransportOptions',
+      name: "options",
+      type: "StreamableHTTPServerTransportOptions",
       description:
-        'Optional configuration for the HTTP transport. See the options table below for more details.',
+        "Optional configuration for the HTTP transport. See the options table below for more details.",
       optional: true,
     },
   ]}
@@ -439,30 +438,30 @@ The `StreamableHTTPServerTransportOptions` object allows you to customize the be
 <PropertiesTable
   content={[
     {
-      name: 'sessionIdGenerator',
-      type: '(() => string) | undefined',
+      name: "sessionIdGenerator",
+      type: "(() => string) | undefined",
       description:
-        'A function that generates a unique session ID. This should be a cryptographically secure, globally unique string. Return `undefined` to disable session management.',
+        "A function that generates a unique session ID. This should be a cryptographically secure, globally unique string. Return `undefined` to disable session management.",
     },
     {
-      name: 'onsessioninitialized',
-      type: '(sessionId: string) => void',
+      name: "onsessioninitialized",
+      type: "(sessionId: string) => void",
       description:
-        'A callback that is invoked when a new session is initialized. This is useful for tracking active MCP sessions.',
+        "A callback that is invoked when a new session is initialized. This is useful for tracking active MCP sessions.",
       optional: true,
     },
     {
-      name: 'enableJsonResponse',
-      type: 'boolean',
+      name: "enableJsonResponse",
+      type: "boolean",
       description:
-        'If `true`, the server will return plain JSON responses instead of using Server-Sent Events (SSE) for streaming. Defaults to `false`.',
+        "If `true`, the server will return plain JSON responses instead of using Server-Sent Events (SSE) for streaming. Defaults to `false`.",
       optional: true,
     },
     {
-      name: 'eventStore',
-      type: 'EventStore',
+      name: "eventStore",
+      type: "EventStore",
       description:
-        'An event store for message resumability. Providing this enables clients to reconnect and resume message streams.',
+        "An event store for message resumability. Providing this enables clients to reconnect and resume message streams.",
       optional: true,
     },
   ]}
@@ -752,13 +751,13 @@ const prompts: Prompt[] = [
   {
     name: "analyze-code",
     description: "Analyze code for improvements",
-    version: "v1"
+    version: "v1",
   },
   {
     name: "analyze-code",
     description: "Analyze code for improvements (new logic)",
-    version: "v2"
-  }
+    version: "v2",
+  },
 ];
 
 const myPromptHandlers: MCPServerPrompts = {
@@ -766,39 +765,46 @@ const myPromptHandlers: MCPServerPrompts = {
   getPromptMessages: async ({ name, version, args }) => {
     if (name === "analyze-code") {
       if (version === "v2") {
-        const prompt = prompts.find(p => p.name === name && p.version === "v2");
+        const prompt = prompts.find(
+          (p) => p.name === name && p.version === "v2",
+        );
         if (!prompt) throw new Error("Prompt version not found");
         return {
           prompt,
           messages: [
             {
               role: "user",
-              content: { type: "text", text: `Analyze this code with the new logic: ${args.code}` }
-            }
-          ]
+              content: {
+                type: "text",
+                text: `Analyze this code with the new logic: ${args.code}`,
+              },
+            },
+          ],
         };
       }
       // Default or v1
-      const prompt = prompts.find(p => p.name === name && p.version === "v1");
+      const prompt = prompts.find((p) => p.name === name && p.version === "v1");
       if (!prompt) throw new Error("Prompt version not found");
       return {
         prompt,
         messages: [
           {
             role: "user",
-            content: { type: "text", text: `Analyze this code: ${args.code}` }
-          }
-        ]
+            content: { type: "text", text: `Analyze this code: ${args.code}` },
+          },
+        ],
       };
     }
     throw new Error("Prompt not found");
-  }
+  },
 };
 
 const serverWithPrompts = new MCPServer({
   name: "Promptful Server",
   version: "1.0.0",
-  tools: { /* ... */ },
+  tools: {
+    /* ... */
+  },
   prompts: myPromptHandlers,
 });
 ```
@@ -849,20 +855,22 @@ When tools are executed within an MCP server context, they receive an additional
 execute: async ({ context }, options) => {
   // context contains the tool's input parameters
   // options contains server capabilities like elicitation and authentication info
-  
+
   // Access authentication information (when available)
   if (options.extra?.authInfo) {
-    console.log('Authenticated request from:', options.extra.authInfo.clientId);
+    console.log("Authenticated request from:", options.extra.authInfo.clientId);
   }
-  
+
   // Use elicitation capabilities
   const result = await options.elicitation.sendRequest({
     message: "Please provide information",
-    requestedSchema: { /* schema */ }
+    requestedSchema: {
+      /* schema */
+    },
   });
-  
+
   return result;
-}
+};
 ```
 
 ### How Elicitation Works
@@ -893,51 +901,54 @@ const server = new MCPServer({
       id: "collectContactInfo",
       description: "Collects user contact information through elicitation",
       inputSchema: z.object({
-        reason: z.string().optional().describe("Reason for collecting contact info"),
+        reason: z
+          .string()
+          .optional()
+          .describe("Reason for collecting contact info"),
       }),
       execute: async ({ context }, options) => {
         const { reason } = context;
-        
+
         // Log session info if available
-        console.log('Request from session:', options.extra?.sessionId);
+        console.log("Request from session:", options.extra?.sessionId);
 
         try {
           // Request user input via elicitation
           const result = await options.elicitation.sendRequest({
-            message: reason 
+            message: reason
               ? `Please provide your contact information. ${reason}`
-              : 'Please provide your contact information',
+              : "Please provide your contact information",
             requestedSchema: {
-              type: 'object',
+              type: "object",
               properties: {
                 name: {
-                  type: 'string',
-                  title: 'Full Name',
-                  description: 'Your full name',
+                  type: "string",
+                  title: "Full Name",
+                  description: "Your full name",
                 },
                 email: {
-                  type: 'string',
-                  title: 'Email Address', 
-                  description: 'Your email address',
-                  format: 'email',
+                  type: "string",
+                  title: "Email Address",
+                  description: "Your email address",
+                  format: "email",
                 },
                 phone: {
-                  type: 'string',
-                  title: 'Phone Number',
-                  description: 'Your phone number (optional)',
+                  type: "string",
+                  title: "Phone Number",
+                  description: "Your phone number (optional)",
                 },
               },
-              required: ['name', 'email'],
+              required: ["name", "email"],
             },
           });
 
           // Handle the user's response
-          if (result.action === 'accept') {
+          if (result.action === "accept") {
             return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
-          } else if (result.action === 'decline') {
-            return 'Contact information collection was declined by the user.';
+          } else if (result.action === "decline") {
+            return "Contact information collection was declined by the user.";
           } else {
-            return 'Contact information collection was cancelled by the user.';
+            return "Contact information collection was cancelled by the user.";
           }
         } catch (error) {
           return `Error collecting contact information: ${error}`;
@@ -1017,7 +1028,7 @@ execute: async ({ context }, options) => {
     message: string,           // Message to display to user
     requestedSchema: object    // JSON schema defining expected response structure
   }): Promise<ElicitResult>
-  
+
   // Access authentication info if needed
   if (options.extra?.authInfo) {
     // Use options.extra.authInfo.token, etc.
@@ -1031,9 +1042,9 @@ The `ElicitResult` type:
 
 ```typescript
 type ElicitResult = {
-  action: 'accept' | 'decline' | 'cancel';
+  action: "accept" | "decline" | "cancel";
   content?: any; // Only present when action is 'accept'
-}
+};
 ```
 
 ## Authentication Context
@@ -1045,29 +1056,31 @@ execute: async ({ context }, options) => {
   if (!options.extra?.authInfo?.token) {
     return "Authentication required";
   }
-  
+
   // Use the auth token
-  const response = await fetch('/api/data', {
+  const response = await fetch("/api/data", {
     headers: { Authorization: `Bearer ${options.extra.authInfo.token}` },
     signal: options.extra.signal,
   });
-  
+
   return response.json();
-}
+};
 ```
 
 The `extra` object contains:
+
 - `authInfo`: Authentication info (when provided by server middleware)
-- `sessionId`: Session identifier  
+- `sessionId`: Session identifier
 - `signal`: AbortSignal for cancellation
 - `sendNotification`/`sendRequest`: MCP protocol functions
 
 > Note: To enable authentication, your HTTP server needs middleware that populates `req.auth` before calling `server.startHTTP()`. For example:
+>
 > ```typescript
 > httpServer.createServer((req, res) => {
 >   // Add auth middleware
 >   req.auth = validateAuthToken(req.headers.authorization);
->   
+>
 >   // Then pass to MCP server
 >   await server.startHTTP({ url, httpPath, req, res });
 > });