@mastra/mcp-docs-server 0.13.2-alpha.1 → 0.13.2-alpha.3

package/.docs/raw/reference/deployer/vercel.mdx

@@ -21,52 +21,10 @@ import { VercelDeployer } from "@mastra/deployer-vercel";
 
 const mastra = new Mastra({
   // ...
-  deployer: new VercelDeployer({
-    teamSlug: "your-team-slug",
-    projectName: "your-project-name",
-    token: "your-vercel-token",
-  })
+  deployer: new VercelDeployer()
 });
 ```
 
-## Parameters
-
-### Constructor Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "teamSlug",
-      type: "string",
-      description: "Your Vercel team slug",
-      isOptional: false,
-    },
-    {
-      name: "projectName",
-      type: "string",
-      description:
-        "Name of your Vercel project (will be created if it doesn't exist).",
-      isOptional: false,
-    },
-    {
-      name: "token",
-      type: "string",
-      description: "Your Vercel authentication token.",
-      isOptional: false,
-    },
-  ]}
-/>
-
-### Environment Variables
-
-The VercelDeployer handles environment variables from multiple sources:
-
-1. **Environment Files**: Variables from `.env.production` and `.env` files.
-2. **Configuration**: Variables passed through the Mastra configuration.
-3. **Vercel Dashboard**: Variables can also be managed through Vercel's web interface.
-
-The deployer automatically synchronizes environment variables between your local development environment and Vercel's environment variable system, ensuring consistency across all deployment environments (production, preview, and development).
-
 ## Lint Mastra Project
 
 Lint your Mastra project to make sure it's fine to build
@@ -83,54 +41,26 @@ To build your Mastra project for Vercel deployment:
 npx mastra build
 ```
 
-The build process generates the following output structure in the `.mastra/output` directory:
+The build process generates the following output structure in the `.vercel/output` directory:
 
 ```
-.mastra/output/
-├── vercel.json     # Vercel configuration
+.vercel/output/functions/index.func
 └── index.mjs       # Application entry point
 ```
 
-### Vercel Configuration
-
-The VercelDeployer automatically generates a `vercel.json` configuration file in `.mastra/output` with the following settings:
-
-```json
-{
-  "version": 2,
-  "installCommand": "npm install --omit=dev",
-  "builds": [
-    {
-      "src": "index.mjs",
-      "use": "@vercel/node",
-      "config": {
-        "includeFiles": ["**"]
-      }
-    }
-  ],
-  "routes": [
-    {
-      "src": "/(.*)",
-      "dest": "index.mjs"
-    }
-  ]
-}
-```
-
 ## Deployment Options
 
-After building, you can deploy your Mastra application `.mastra/output` to Vercel using any of these methods:
+After building, you can deploy your Mastra application to Vercel using any of these methods:
 
 1. **Vercel CLI**: Deploy directly using Vercel's official CLI tool
 
    - Install the CLI: `npm install -g vercel`
-   - Navigate to the output directory: `cd .mastra/output`
-   - Deploy to preview environment: `vercel`
-   - For production deployment: `vercel --prod`
+   - Deploy to preview environment: `vercel --prebuilt`
+   - For production deployment: `vercel --prod --prebuilt`
 
 2. **Vercel Dashboard**: Connect your Git repository or drag-and-drop the build output through the Vercel dashboard
 
-> You can also run `vercel dev` in your output directory `.mastra/output` to test your Mastra application locally.
+> You can also run `vercel dev` in your project directory to test your Mastra application locally. (Make sure you configured your dev command to `mastra dev`)
 
 ## Platform Documentation
 

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

@@ -308,6 +308,145 @@ const { prompt, messages } = await mcpClient.prompts.get({
 });
 ```
 
+### `elicitation` Property
+
+The `MCPClient` instance has an `elicitation` property that provides access to elicitation-related operations. Elicitation allows MCP servers to request structured information from users.
+
+```typescript
+const mcpClient = new MCPClient({
+  /* ...servers configuration... */
+});
+
+// Set up elicitation handler
+mcpClient.elicitation.onRequest('serverName', async (request) => {
+  // Handle elicitation request from server
+  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' }
+  };
+});
+```
+
+#### `elicitation.onRequest(serverName: string, handler: ElicitationHandler)`
+
+Sets up a handler function that will be called when any connected MCP server sends an elicitation request. The handler receives the request and must return a response.
+
+**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'`, `'reject'`, or `'cancel'`
+- `content`: The user's data (only when action is `'accept'`)
+
+**Example:**
+
+```typescript
+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',
+      content: {
+        name: 'Alice Smith',
+        email: 'alice@example.com'
+      }
+    };
+  }
+  
+  // Simulate user rejecting the request
+  return { action: 'reject' };
+});
+```
+
+**Complete Interactive Example:**
+
+```typescript
+import { MCPClient } from '@mastra/mcp';
+import { createInterface } from 'readline';
+
+const readline = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function askQuestion(question: string): Promise<string> {
+  return new Promise(resolve => {
+    readline.question(question, answer => resolve(answer.trim()));
+  });
+}
+
+const mcpClient = new MCPClient({
+  servers: {
+    interactiveServer: {
+      url: new URL('http://localhost:3000/mcp'),
+    },
+  },
+});
+
+// Set up interactive elicitation handler
+await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+  console.log(`\n📋 Server Request: ${request.message}`);
+  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 += ': ';
+    
+    const answer = await askQuestion(prompt);
+    
+    // Handle cancellation
+    if (answer.toLowerCase() === 'cancel') {
+      return { action: 'cancel' };
+    }
+    
+    // Validate required fields
+    if (answer === '' && isRequired) {
+      console.log(`❌ ${fieldName} is required`);
+      return { action: 'reject' };
+    }
+    
+    if (answer !== '') {
+      content[fieldName] = answer;
+    }
+  }
+  
+  // Confirm submission
+  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' };
+  } else {
+    return { action: 'reject' };
+  }
+});
+```
+
 #### `prompts.list()`
 
 Retrieves all available prompts from all connected MCP servers, grouped by server name.
@@ -373,6 +512,111 @@ mcpClient.prompts.onListChanged("myWeatherServer", () => {
 });
 ```
 
+## Elicitation
+
+Elicitation is a feature that allows MCP servers to request structured information from users. When a server needs additional data, it can send an elicitation request that the client handles by prompting the user. A common example is during a tool call.
+
+### How Elicitation Works
+
+1. **Server Request**: An MCP server tool calls `server.elicitation.sendRequest()` with a message and schema
+2. **Client Handler**: Your elicitation handler function is called with the request
+3. **User Interaction**: Your handler collects user input (via UI, CLI, etc.)
+4. **Response**: Your handler returns the user's response (accept/reject/cancel)
+5. **Tool Continuation**: The server tool receives the response and continues execution
+
+### Setting Up Elicitation
+
+You must set up an elicitation handler before tools that use elicitation are called:
+
+```typescript
+import { MCPClient } from '@mastra/mcp';
+
+const mcpClient = new MCPClient({
+  servers: {
+    interactiveServer: {
+      url: new URL('http://localhost:3000/mcp'),
+    },
+  },
+});
+
+// Set up elicitation handler
+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
+  };
+});
+```
+
+### Response Types
+
+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' }
+  };
+  ```
+
+- **Reject**: User explicitly declined to provide the information
+  ```typescript
+  return { action: 'reject' };
+  ```
+
+- **Cancel**: User dismissed or cancelled the request
+  ```typescript
+  return { action: 'cancel' };
+  ```
+
+### Schema-Based Input Collection
+
+The `requestedSchema` provides structure for the data the server needs:
+
+```typescript
+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,
+      title: field.title,
+      description: field.description,
+      type: field.type,
+      required: isRequired,
+      format: field.format,
+      enum: field.enum,
+    });
+    
+    if (value !== null) {
+      content[fieldName] = value;
+    }
+  }
+  
+  return { action: 'accept', content };
+});
+```
+
+### Best Practices
+
+- **Always handle elicitation**: Set up your handler before calling tools that might use elicitation
+- **Validate input**: Check that required fields are provided
+- **Respect user choice**: Handle reject and cancel responses gracefully
+- **Clear UI**: Make it obvious what information is being requested and why
+- **Security**: Never auto-accept requests for sensitive information
+
 ## Examples
 
 ### Static Tool Configuration

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

@@ -833,6 +833,192 @@ For practical examples of setting up and deploying an MCPServer, see the [Deploy
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 
+## Elicitation
+
+### What is Elicitation?
+
+Elicitation is a feature in the Model Context Protocol (MCP) that allows servers to request structured information from users. This enables interactive workflows where servers can collect additional data dynamically.
+
+The `MCPServer` class automatically includes elicitation capabilities. Tools receive an `options` parameter in their `execute` function that includes an `elicitation.sendRequest()` method for requesting user input.
+
+### Tool Execution Signature
+
+When tools are executed within an MCP server context, they receive an additional `options` parameter:
+
+```typescript
+execute: async ({ context }, options) => {
+  // context contains the tool's input parameters
+  // options contains server capabilities like elicitation
+  
+  const result = await options.elicitation.sendRequest({
+    message: "Please provide information",
+    requestedSchema: { /* schema */ }
+  });
+  
+  return result;
+}
+```
+
+### How Elicitation Works
+
+A common use case is during tool execution. When a tool needs user input, it can use the elicitation functionality provided through the tool's execution options:
+
+1. The tool calls `options.elicitation.sendRequest()` with a message and schema
+2. The request is sent to the connected MCP client
+3. The client presents the request to the user (via UI, command line, etc.)
+4. The user provides input, rejects, or cancels the request
+5. The client sends the response back to the server
+6. The tool receives the response and continues execution
+
+### Using Elicitation in Tools
+
+Here's an example of a tool that uses elicitation to collect user contact information:
+
+```typescript
+import { MCPServer } from "@mastra/mcp";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const server = new MCPServer({
+  name: "Interactive Server",
+  version: "1.0.0",
+  tools: {
+    collectContactInfo: createTool({
+      id: "collectContactInfo",
+      description: "Collects user contact information through elicitation",
+      inputSchema: z.object({
+        reason: z.string().optional().describe("Reason for collecting contact info"),
+      }),
+      execute: async ({ context }, options) => {
+        const { reason } = context;
+
+        try {
+          // Request user input via elicitation through the options parameter
+          const result = await options.elicitation.sendRequest({
+            message: reason 
+              ? `Please provide your contact information. ${reason}`
+              : 'Please provide your contact information',
+            requestedSchema: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  title: 'Full Name',
+                  description: 'Your full name',
+                },
+                email: {
+                  type: 'string',
+                  title: 'Email Address', 
+                  description: 'Your email address',
+                  format: 'email',
+                },
+                phone: {
+                  type: 'string',
+                  title: 'Phone Number',
+                  description: 'Your phone number (optional)',
+                },
+              },
+              required: ['name', 'email'],
+            },
+          });
+
+          // Handle the user's response
+          if (result.action === 'accept') {
+            return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
+          } else if (result.action === 'reject') {
+            return 'Contact information collection was declined by the user.';
+          } else {
+            return 'Contact information collection was cancelled by the user.';
+          }
+        } catch (error) {
+          return `Error collecting contact information: ${error}`;
+        }
+      },
+    }),
+  },
+});
+```
+
+### Elicitation Request Schema
+
+The `requestedSchema` must be a flat object with primitive properties only. Supported types include:
+
+- **String**: `{ type: 'string', title: 'Display Name', description: 'Help text' }`
+- **Number**: `{ type: 'number', minimum: 0, maximum: 100 }`
+- **Boolean**: `{ type: 'boolean', default: false }`
+- **Enum**: `{ type: 'string', enum: ['option1', 'option2'] }`
+
+Example schema:
+
+```typescript
+{
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      title: 'Full Name',
+      description: 'Your complete name',
+    },
+    age: {
+      type: 'number',
+      title: 'Age',
+      minimum: 18,
+      maximum: 120,
+    },
+    newsletter: {
+      type: 'boolean',
+      title: 'Subscribe to Newsletter',
+      default: false,
+    },
+  },
+  required: ['name'],
+}
+```
+
+### Response Actions
+
+Users can respond to elicitation requests in three ways:
+
+1. **Accept** (`action: 'accept'`): User provided data and confirmed submission
+   - Contains `content` field with the submitted data
+2. **Reject** (`action: 'reject'`): User explicitly declined to provide information
+   - No content field
+3. **Cancel** (`action: 'cancel'`): User dismissed the request without deciding
+   - No content field
+
+Tools should handle all three response types appropriately.
+
+### Security Considerations
+
+- **Never request sensitive information** like passwords, SSNs, or credit card numbers
+- Validate all user input against the provided schema
+- Handle rejection and cancellation gracefully
+- Provide clear reasons for data collection
+- Respect user privacy and preferences
+
+### Tool Execution API
+
+The elicitation functionality is available through the `options` parameter in tool execution:
+
+```typescript
+// Within a tool's execute function
+options.elicitation.sendRequest({
+  message: string,           // Message to display to user
+  requestedSchema: object    // JSON schema defining expected response structure
+}): Promise<ElicitResult>
+```
+
+Note that elicitation is **session-aware** when using HTTP-based transports (SSE or HTTP). This means that when multiple clients are connected to the same server, elicitation requests are routed to the correct client session that initiated the tool execution.
+
+The `ElicitResult` type:
+
+```typescript
+type ElicitResult = {
+  action: 'accept' | 'reject' | 'cancel';
+  content?: any; // Only present when action is 'accept'
+}
+```
+
 ## Related Information
 
 - For connecting to MCP servers in Mastra, see the [MCPClient documentation](./mcp-client).

package/.docs/raw/reference/workflows/create-run.mdx

@@ -31,7 +31,7 @@ const mastra = new Mastra({
   },
 });
 
-const run = mastra.getWorkflow("myWorkflow").createRun();
+const run = await mastra.getWorkflow("myWorkflow").createRunAsync();
 ```
 
 ## Parameters

package/.docs/raw/reference/workflows/resume.mdx

@@ -10,7 +10,7 @@ The `.resume()` method resumes a suspended workflow run with new data, allowing
 ## Usage
 
 ```typescript
-const run = counterWorkflow.createRun();
+const run = await counterWorkflow.createRunAsync();
 const result = await run.start({ inputData: { startValue: 0 } });
 
 if (result.status === "suspended") {

package/.docs/raw/reference/workflows/start.mdx

@@ -10,7 +10,7 @@ The `.start()` method starts a workflow run with input data, allowing you to exe
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Start the workflow with input data
 const result = await run.start({

package/.docs/raw/reference/workflows/stream.mdx

@@ -10,7 +10,7 @@ The `.stream()` method allows you to monitor the execution of a workflow run, pr
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Add a stream to monitor execution
 const result = run.stream({ inputData: {...} });

package/.docs/raw/reference/workflows/watch.mdx

@@ -10,7 +10,7 @@ The `.watch()` method allows you to monitor the execution of a workflow run, pro
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Add a watcher to monitor execution
 run.watch(event => {

package/.docs/raw/reference/workflows/workflow.mdx

@@ -31,7 +31,7 @@ const mastra = new Mastra({
   },
 });
 
-const run = mastra.getWorkflow("myWorkflow").createRun();
+const run = await mastra.getWorkflow("myWorkflow").createRunAsync();
 ```
 
 ## API Reference
@@ -99,7 +99,11 @@ Validates and finalizes the workflow configuration. Must be called after adding
 
 #### `createRun()`
 
-Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+Deprecated. Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+
+#### `createRunAsync()`
+
+Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID. Stores a pending workflow run snapshot into storage.
 
 #### `execute()`
 

package/.docs/raw/workflows/control-flow.mdx

@@ -126,6 +126,47 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
+### Early exit
+
+You can bail out of a workflow execution successfully by calling `bail()` in a step. This returns whatever payload is passed to the `bail()` function as the result of the workflow.
+
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail, inputData }) => {
+    return bail({ result: 'bailed' });
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+Unsuccessful bails happen through throwing an error in the step.
+
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail, inputData }) => {
+    throw new Error('bailed');
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
 #### Example Run Instance
 
 The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
@@ -133,7 +174,7 @@ The following example demonstrates how to start a run with multiple inputs. Each
 ```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.start({
   inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]