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

package/.docs/organized/code-examples/agent.md

@@ -50,21 +50,147 @@
 ### client.ts
 ```typescript
 import { MCPClient } from '@mastra/mcp';
+// import type { ElicitationHandler } from '@mastra/mcp';
+import { createInterface } from 'readline';
+
+// Create readline interface for user input
+const readline = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// Helper function to prompt user for input
+function askQuestion(question: string): Promise<string> {
+  return new Promise(resolve => {
+    readline.question(question, answer => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+// Elicitation handler that prompts the user for input
+const elicitationHandler = async request => {
+  console.log('\n🔔 Elicitation Request Received:');
+  console.log(`Message: ${request.message}`);
+  console.log('Requested Schema:');
+  console.log(JSON.stringify(request.requestedSchema, null, 2));
+
+  const schema = request.requestedSchema;
+  const properties = schema.properties;
+  const required = schema.required || [];
+
+  console.log('\nPlease provide the following information:');
+
+  const content: Record<string, unknown> = {};
+
+  // Collect input for each field
+  for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+    const field = fieldSchema as {
+      type?: string;
+      title?: string;
+      description?: string;
+      format?: string;
+    };
+
+    const isRequired = required.includes(fieldName);
+    let prompt = `${field.title || fieldName}`;
+
+    // Add helpful information to the prompt
+    if (field.description) {
+      prompt += ` (${field.description})`;
+    }
+    if (field.format) {
+      prompt += ` [format: ${field.format}]`;
+    }
+    if (isRequired) {
+      prompt += ' *required*';
+    }
+
+    prompt += ': ';
+
+    const answer = await askQuestion(prompt);
+
+    // Check for cancellation
+    if (answer.toLowerCase() === 'cancel' || answer.toLowerCase() === 'c') {
+      return { action: 'cancel' as const };
+    }
+
+    // Handle empty responses
+    if (answer === '' && isRequired) {
+      console.log(`❌ Error: ${fieldName} is required`);
+      return { action: 'reject' as const };
+    } else if (answer !== '') {
+      content[fieldName] = answer;
+    }
+  }
+
+  // Show the collected data and ask for confirmation
+  console.log('\n✅ Collected data:');
+  console.log(JSON.stringify(content, null, 2));
+
+  const confirmAnswer = await askQuestion('\nSubmit this information? (yes/no/cancel): ');
+
+  if (confirmAnswer.toLowerCase() === 'yes' || confirmAnswer.toLowerCase() === 'y') {
+    return {
+      action: 'accept' as const,
+      content,
+    };
+  } else if (confirmAnswer.toLowerCase() === 'cancel' || confirmAnswer.toLowerCase() === 'c') {
+    return { action: 'cancel' as const };
+  } else {
+    return { action: 'reject' as const };
+  }
+};
 
 async function main() {
   const mcpClient = new MCPClient({
     servers: {
-      myMcpServer: {
-        url: new URL('http://localhost:4111/api/mcp/myMcpServer/mcp'),
+      myMcpServerTwo: {
+        url: new URL('http://localhost:4111/api/mcp/myMcpServerTwo/mcp'),
       },
     },
   });
 
-  const tools = await mcpClient.getTools();
-  console.log('Tools:', tools);
+  mcpClient.elicitation.onRequest('myMcpServerTwo', elicitationHandler);
+
+  try {
+    console.log('Connecting to MCP server...');
+    const tools = await mcpClient.getTools();
+    console.log('Available tools:', Object.keys(tools));
+
+    // Test the elicitation functionality
+    console.log('\n🧪 Testing elicitation functionality...');
+
+    // Find the collectContactInfo tool
+    const collectContactInfoTool = tools['myMcpServerTwo_collectContactInfo'];
+    if (collectContactInfoTool) {
+      console.log('\nCalling collectContactInfo tool...');
+
+      try {
+        const result = await collectContactInfoTool.execute({
+          context: {
+            reason: 'We need your contact information to send you updates about our service.',
+          },
+        });
+
+        console.log('\n📋 Tool Result:');
+        console.log(result);
+      } catch (error) {
+        console.error('❌ Error calling collectContactInfo tool:', error);
+      }
+    } else {
+      console.log('❌ collectContactInfo tool not found');
+      console.log('Available tools:', Object.keys(tools));
+    }
+  } catch (error) {
+    console.error('❌ Error:', error);
+  } finally {
+    readline.close();
+    await mcpClient.disconnect();
+  }
 }
 
-main();
+main().catch(console.error);
 
 ```
 
@@ -664,6 +790,57 @@ export const myMcpServerTwo = new MCPServer({
         return `Hello, ${context.name}! Welcome to the MCP server.`;
       },
     }),
+    collectContactInfo: createTool({
+      id: 'collectContactInfo',
+      description: 'Collects user contact information through elicitation.',
+      inputSchema: z.object({
+        reason: z.string().optional().describe('Optional reason for collecting contact info'),
+      }),
+      execute: async ({ context }, options) => {
+        const { reason } = context;
+
+        try {
+          // Use the session-aware elicitation functionality
+          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'],
+            },
+          });
+
+          if (result.action === 'accept') {
+            return `Thank you! 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}`;
+        }
+      },
+    }),
   },
 });
 

package/.docs/organized/code-examples/assistant-ui.md

@@ -30,7 +30,7 @@
     "@types/node": "^20.17.57",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "eslint": "^8.57.1",
+    "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",

package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md

@@ -39,7 +39,7 @@
     "@types/node": "^20.17.57",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
-    "eslint": "^8.57.1",
+    "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",

package/.docs/organized/code-examples/bird-checker-with-nextjs.md

@@ -38,7 +38,7 @@
     "@types/node": "^20.17.57",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
-    "eslint": "^8.57.1",
+    "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",

package/.docs/organized/code-examples/crypto-chatbot.md

@@ -91,8 +91,8 @@
     "drizzle-kit": "^0.31.0",
     "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-import-resolver-typescript": "^3.10.1",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-import-resolver-typescript": "^4.4.3",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-tailwindcss": "^3.18.0",
     "postcss": "^8.5.3",

package/.docs/organized/code-examples/openapi-spec-writer.md

@@ -41,7 +41,7 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "eslint": "^8.57.1",
+    "eslint": "^9.29.0",
     "eslint-config-next": "15.3.3",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",

package/.docs/raw/agents/using-tools-and-mcp.mdx

@@ -75,8 +75,6 @@ Once you have a server you want to use with your agent, import the Mastra `MCPCl
 
 ```typescript filename="src/mastra/mcp.ts" {1,7-16}
 import { MCPClient } from "@mastra/mcp";
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 
 // Configure MCPClient to connect to your server(s)
 export const mcp = new MCPClient({
@@ -96,7 +94,10 @@ export const mcp = new MCPClient({
 Then connect your agent to the server tools:
 
 ```typescript filename="src/mastra/agents/mcpAgent.ts" {7}
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
 import { mcp } from "../mcp";
+
 // Create an agent and add tools from the MCP client
 const agent = new Agent({
   name: "Agent with MCP Tools",

package/.docs/raw/course/01-first-agent/04-project-structure.md

@@ -4,9 +4,14 @@ Let's check that your project has the correct structure. You should have:
 
 1. A `src/mastra` directory that contains:
    - `index.ts` - The main entry point for your Mastra project
-   - `agents/index.ts` - Where your agents are defined
-   - `tools/index.ts` - Where your tools are defined
+   - `agents/` - Directory containing individual agent files
+   - `tools/` - Directory containing individual tool files
+   - `workflows/` - Directory containing individual workflow files
 
-If these files exist, you're ready to start building your agent!
+If the CLI created your project, you should see files like:
+
+- `agents/weather-agent.ts` - Example weather agent
+- `tools/weather-tool.ts` - Example weather tool
+- `workflows/weather-workflow.ts` - Example weather workflow
 
 This structure is important because it follows the Mastra convention for organizing your code. The `index.ts` file is the main entry point for your Mastra project, while the `agents` and `tools` directories contain the definitions for your agents and tools, respectively.

package/.docs/raw/course/01-first-agent/07-creating-your-agent.md

@@ -1,11 +1,13 @@
 # Creating Your Agent
 
-Let's create a simple agent that will help users analyze financial transaction data. We'll start by modifying the `agents/index.ts` file.
+Let's create a simple agent that will help users analyze financial transaction data. We'll create a new file called `agents/financial-agent.ts`.
 
-First, make sure you have the necessary imports at the top of your file:
+First, create the new agent file at src/mastra/agents/financial-agent.ts
+
+Now add the necessary imports at the top of your file:
 
 ```typescript
-import { Agent } from "@mastra/core";
+import { Agent } from "@mastra/core/agent";
 import { openai } from "@ai-sdk/openai";
 // We'll import our tool in a later step
 ```

package/.docs/raw/course/01-first-agent/08-exporting-your-agent.md

@@ -1,18 +1,32 @@
 # Exporting Your Agent
 
-To make your agent available to the playground, you need to export it through the Mastra class in your `src/mastra/index.ts` file:
+To make your agent available to the playground, you need to export it through the Mastra class in your `src/mastra/index.ts` file.
+
+First, import the necessary dependencies and your agent:
 
 ```typescript
-import { Mastra } from "@mastra/core";
-import { financialAgent } from "./agents";
+import { Mastra } from "@mastra/core/mastra";
+import { PinoLogger } from "@mastra/loggers";
+import { LibSQLStore } from "@mastra/libsql";
+import { financialAgent } from "./agents/financial-agent";
 
-export const mastra: Mastra = new Mastra({
+export const mastra = new Mastra({
   agents: {
     financialAgent,
   },
+  storage: new LibSQLStore({
+    url: ":memory:",
+  }),
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
 });
 ```
 
-This creates a new Mastra instance that includes your financial agent, making it available to the playground and any other parts of your application.
+This creates a new Mastra instance that includes:
+- Your financial agent
+- In-memory storage for development
+- A logger for debugging and monitoring
 
-The Mastra class is the main entry point for your Mastra project. It's responsible for registering your agents and making them available to the rest of your application. By adding your agent to the Mastra instance, you're telling Mastra that this agent should be available for use.
+The Mastra class is the main entry point for your Mastra project. It's responsible for registering your agents and configuring the core services like storage and logging.

package/.docs/raw/course/01-first-agent/11-creating-transactions-tool.md

@@ -1,11 +1,13 @@
 # Creating the getTransactions Tool
 
-Let's create a tool that fetches transaction data from a Google Sheet. We'll add this to your `tools/index.ts` file.
+Let's create a tool that fetches transaction data from a Google Sheet. We'll create a new file called `tools/get-transactions-tool.ts`.
 
-First, make sure you have the necessary imports:
+First, create the new tool file at src/mastra/tools/get-transactions-tool.ts
+
+Now add the necessary imports:
 
 ```typescript
-import { createTool } from "@mastra/core";
+import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 ```
 

package/.docs/raw/course/01-first-agent/12-connecting-tool-to-agent.md

@@ -1,11 +1,11 @@
 # Connecting the Tool to Your Agent
 
-Now that we've created our tool, we need to connect it to our agent. Go back to your `agents/index.ts` file and update it:
+Now that we've created our tool, we need to connect it to our agent. Go back to your `agents/financial-agent.ts` file and update it:
 
 1. Import the tool:
 
 ```typescript
-import { getTransactionsTool } from "../tools";
+import { getTransactionsTool } from "../tools/get-transactions-tool";
 ```
 
 2. Add the tool to your agent:

package/.docs/raw/course/04-workflows/01-introduction-to-workflows.md

@@ -0,0 +1,44 @@
+# Introduction to Workflows
+
+Welcome to the fourth lesson of the Mastra course! In this lesson, you'll learn about Mastra Workflows - a powerful way to orchestrate complex sequences of operations.
+
+## What are Workflows?
+
+Workflows in Mastra let you chain together multiple operations in a predictable, type-safe manner. Think of them as a recipe that breaks down complex tasks into smaller, manageable steps.
+
+Instead of writing one big function that does everything, workflows let you:
+
+- Break complex operations into smaller, reusable steps
+- Define clear inputs and outputs for each step
+- Chain steps together with automatic data validation
+- Handle errors gracefully at each step
+
+## Simple Example
+
+Without workflows, you might write:
+
+```typescript
+async function processContent(text: string) {
+  // All logic in one function - hard to test and reuse
+  const validated = validateText(text);
+  const enhanced = enhanceText(validated);
+  const summarized = summarizeText(enhanced);
+  return summarized;
+}
+```
+
+With workflows, the same logic becomes modular and reusable with tracing built in at every step.
+
+```typescript
+export const contentWorkflow = createWorkflow({...})
+  .then(validateStep)
+  .then(enhanceStep)
+  .then(summarizeStep)
+  .commit();
+```
+
+## What You'll Build
+
+In this lesson, you'll create a content processing workflow that validates, enhances, and summarizes text content using multiple connected steps.
+
+Let's start by understanding the basic building blocks!

package/.docs/raw/course/04-workflows/02-understanding-steps.md

@@ -0,0 +1,53 @@
+# Understanding Steps
+
+Steps are the building blocks of workflows. Each step is a self-contained unit that takes some input, processes it, and produces an output.
+
+## What is a Step?
+
+A step has three main parts:
+
+1. **Input Schema** - what data it expects to receive
+2. **Output Schema** - what data it will produce
+3. **Execute Function** - the logic that transforms input to output
+
+## Step Structure
+
+Every step follows this pattern:
+
+```typescript
+const myStep = createStep({
+  id: "unique-step-name",
+  description: "What this step does",
+  inputSchema: z.object({
+    // Define expected input structure
+  }),
+  outputSchema: z.object({
+    // Define output structure
+  }),
+  execute: async ({ inputData }) => {
+    // Your logic here
+    return {
+      // Return data matching output schema
+    };
+  },
+});
+```
+
+## Why Use Schemas?
+
+Schemas provide several benefits:
+
+- **Type Safety**: TypeScript knows exactly what data flows between steps
+- **Runtime Validation**: Invalid data is caught immediately with helpful error messages
+- **Documentation**: Schemas serve as living documentation of your workflow
+- **Debugging**: Clear contracts make it easy to identify issues
+
+## Key Benefits
+
+- **Reusable**: Steps can be used in multiple workflows
+- **Testable**: Each step can be tested in isolation
+- **Composable**: Steps can be combined in different ways
+- **Reliable**: Schemas catch data flow issues early
+- **Traceable**: Every step is traced so you can see the flow of data
+
+Next, you'll create your first step!

package/.docs/raw/course/04-workflows/03-creating-your-first-step.md

@@ -0,0 +1,57 @@
+# Creating Your First Step
+
+Let's create your first workflow step! We'll build a step that validates text content.
+
+## Setting Up
+
+First, create a new file for your workflow in the `src/mastra/workflows` directory. Let's name this file `content-workflow.ts`
+
+## Creating a Validation Step
+
+Add this code to your workflow file:
+
+```typescript
+import { createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const validateContentStep = createStep({
+  id: "validate-content",
+  description: "Validates incoming text content",
+  inputSchema: z.object({
+    content: z.string().min(1, "Content cannot be empty"),
+    type: z.enum(["article", "blog", "social"]).default("article"),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    isValid: z.boolean(),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type } = inputData;
+
+    const wordCount = content.trim().split(/\s+/).length;
+    const isValid = wordCount >= 5; // Minimum 5 words
+
+    if (!isValid) {
+      throw new Error(`Content too short: ${wordCount} words`);
+    }
+
+    return {
+      content: content.trim(),
+      type,
+      wordCount,
+      isValid,
+    };
+  },
+});
+```
+
+## Understanding the Code
+
+- **ID**: Unique identifier for this step
+- **Input Schema**: Expects `content` (string) and optional `type`
+- **Output Schema**: Returns content, type, word count, and validation status
+- **Execute**: Contains the validation logic
+
+Your first step is ready! Next, you'll test it to make sure it works correctly.

package/.docs/raw/course/04-workflows/04-creating-a-second-step.md

@@ -0,0 +1,58 @@
+# Creating a Second Step
+
+Now let's create a second step that enhances the validated content with metadata.
+
+## The Enhancement Step
+
+Add this step to your workflow file:
+
+```typescript
+const enhanceContentStep = createStep({
+  id: "enhance-content",
+  description: "Adds metadata to validated content",
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    isValid: z.boolean(),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    metadata: z.object({
+      readingTime: z.number(),
+      difficulty: z.enum(["easy", "medium", "hard"]),
+      processedAt: z.string(),
+    }),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type, wordCount } = inputData;
+
+    // Calculate reading time (200 words per minute)
+    const readingTime = Math.ceil(wordCount / 200);
+
+    // Determine difficulty based on word count
+    let difficulty: "easy" | "medium" | "hard" = "easy";
+    if (wordCount > 100) difficulty = "medium";
+    if (wordCount > 300) difficulty = "hard";
+
+    return {
+      content,
+      type,
+      wordCount,
+      metadata: {
+        readingTime,
+        difficulty,
+        processedAt: new Date().toISOString(),
+      },
+    };
+  },
+});
+```
+
+## Notice the Input Schema
+
+The input schema of this step matches the output schema of the previous step. This is important for chaining steps together!
+
+Your second step is ready! Next, you'll learn how to chain these steps together into a complete workflow.

package/.docs/raw/course/04-workflows/05-chaining-steps-together.md

@@ -0,0 +1,56 @@
+# Chaining Steps Together
+
+Now you'll learn how to chain your steps together to create a complete workflow.
+
+## Creating the Workflow
+
+Add this workflow definition to your file:
+
+```typescript
+import { createWorkflow } from "@mastra/core/workflows";
+
+export const contentWorkflow = createWorkflow({
+  id: "content-processing-workflow",
+  description: "Validates and enhances content",
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(["article", "blog", "social"]).default("article")
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    metadata: z.object({
+      readingTime: z.number(),
+      difficulty: z.enum(["easy", "medium", "hard"]),
+      processedAt: z.string()
+    })
+  })
+})
+  .then(validateContentStep)
+  .then(enhanceContentStep)
+  .commit();
+```
+
+## Understanding the Workflow
+
+- **Input Schema**: Defines what data the workflow expects
+- **Output Schema**: Defines what the workflow will return
+- **Steps**: Chained using `.then()` in the order they should execute
+- **Commit**: Finalizes the workflow definition
+
+## How Data Flows
+
+1. Workflow receives input matching the input schema
+2. First step processes input and outputs validated data
+3. Second step receives the first step's output as its input
+4. Workflow returns the final step's output
+
+## Schema Validation
+
+The workflow automatically validates:
+- Input data matches the workflow's input schema
+- Each step's output matches the next step's input schema
+- Final output matches the workflow's output schema
+
+Your workflow is now ready to run! Next, you'll test the complete workflow.