@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/course/04-workflows/08-running-workflows-programmatically.md

@@ -0,0 +1,73 @@
+# Running Workflows Programmatically
+
+Learn how to execute your workflows from code, which is essential for integrating them into applications.
+
+## Creating a Workflow Runner
+
+Create a new file to test programmatic execution:
+
+```typescript
+// src/run-workflow.ts
+import { mastra } from './mastra'
+
+async function runContentWorkflow() {
+  console.log('🚀 Running workflow programmatically...\n')
+
+  try {
+    // Get the workflow instance
+    const workflow = mastra.getWorkflow('contentWorkflow')
+
+    if (!workflow) {
+      throw new Error('Workflow not found')
+    }
+
+    // Create a run instance
+    const run = await workflow.createRun()
+
+    // Execute with test data
+    const result = await run.start({
+      inputData: {
+        content:
+          'Climate change is one of the most pressing challenges of our time, requiring immediate action from governments, businesses, and individuals worldwide.',
+        type: 'blog',
+      },
+    })
+
+    if (result.status === 'success') {
+      console.log('✅ Success!')
+      console.log('📊 Reading time:', result.result.metadata.readingTime, 'minutes')
+      console.log('🎯 Difficulty:', result.result.metadata.difficulty)
+      console.log('📅 Processed at:', result.result.metadata.processedAt)
+    }
+  } catch (error) {
+    console.error('❌ Error:', (error as Error).message)
+  }
+}
+
+// Run the workflow
+runContentWorkflow()
+```
+
+## Running the Code
+
+Execute your workflow runner:
+
+```bash
+npx tsx src/run-workflow.ts
+```
+
+## Key Methods
+
+- **`mastra.getWorkflow(id)`**: Gets a registered workflow by ID
+- **`workflow.createRun()`**: Creates a new execution instance
+- **`run.start(inputData)`**: Executes the workflow with provided data
+
+## Return Value
+
+The `start()` method returns:
+
+- **`success`**: Boolean indicating if workflow completed successfully
+- **`result`**: The final output from the workflow
+- **`executionTime`**: How long the workflow took to run
+
+Your workflow can now be run from anywhere in your application! Next, you'll learn about error handling.

package/.docs/course/04-workflows/09-adding-a-third-step.md

@@ -0,0 +1,68 @@
+# Adding a Third Step
+
+Let's extend your workflow by adding a third step that generates a summary of the content.
+
+## Creating the Summary Step
+
+Add this new step to your workflow file:
+
+```typescript
+const generateSummaryStep = createStep({
+  id: 'generate-summary',
+  description: 'Creates a summary of the content',
+  inputSchema: 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(),
+    }),
+  }),
+  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(),
+    }),
+    summary: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type, wordCount, metadata } = inputData
+
+    // Create a simple summary from first sentence
+    const sentences = content.split(/[.!?]+/).filter(s => s.trim().length > 0)
+    const firstSentence = sentences[0]?.trim() + '.'
+
+    // Generate summary based on content length
+    let summary = firstSentence
+    if (wordCount > 50) {
+      summary += ` This ${type} contains ${wordCount} words and takes approximately ${metadata.readingTime} minute(s) to read.`
+    }
+
+    console.log(`📝 Generated summary: ${summary.length} characters`)
+
+    return {
+      content,
+      type,
+      wordCount,
+      metadata,
+      summary,
+    }
+  },
+})
+```
+
+## Understanding the Pattern
+
+Notice how this step:
+
+- Takes the output from the previous step as input
+- Adds new data (`summary`) while preserving existing data
+- Follows the same structure as other steps
+
+Your third step is ready! Next, you'll update the workflow to include all three steps.

package/.docs/course/04-workflows/10-updating-the-workflow.md

@@ -0,0 +1,55 @@
+# Updating the Workflow
+
+Now you'll update your workflow to include all three steps: validate, enhance, and summarize.
+
+## Updating the Workflow Definition
+
+Replace your existing workflow with this updated version:
+
+```typescript
+export const contentWorkflow = createWorkflow({
+  id: 'content-processing-workflow',
+  description: 'Validates, enhances, and summarizes 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(),
+    }),
+    summary: z.string(),
+  }),
+})
+  .then(validateContentStep)
+  .then(enhanceContentStep)
+  .then(generateSummaryStep)
+  .commit()
+```
+
+## What Changed
+
+- **Description**: Updated to reflect the new functionality
+- **Output Schema**: Now includes the `summary` field
+- **Steps**: Added the third step to the chain
+
+## Testing the Updated Workflow
+
+You can now test this workflow in the playground to validate it works as expected.
+
+## The Complete Flow
+
+Your workflow now:
+
+1. **Validates** content and counts words
+2. **Enhances** with metadata like reading time and difficulty
+3. **Summarizes** the content for quick understanding
+
+Each step builds on the previous one, creating a comprehensive content processing pipeline!
+
+Next, you'll learn about using workflows with agents.

package/.docs/course/04-workflows/11-creating-an-ai-agent.md

@@ -0,0 +1,66 @@
+# Creating an AI Agent
+
+Learn how to create an Mastra agent that can be used within your workflows for more intelligent content processing.
+
+## Creating a Content Analysis Agent
+
+Create a new file for your agent in the `src/mastra/agents` directory. Use `content-agent.ts` as the name of the file with the following contents:
+
+```typescript
+// src/mastra/agents/content-agent.ts
+import { Agent } from '@mastra/core/agent'
+
+export const contentAgent = new Agent({
+  name: 'Content Agent',
+  description: 'AI agent for analyzing and improving content',
+  instructions: `
+    You are a professional content analyst. Your role is to:
+    1. Analyze content for clarity and engagement
+    2. Identify the main themes and topics
+    3. Provide a quality score from 1-10
+    4. Suggest specific improvements
+    
+    Always provide constructive, actionable feedback.
+  `,
+  model: 'openai/gpt-4.1-mini',
+})
+```
+
+## Understanding the Agent
+
+- **Name**: Unique identifier for the agent
+- **Description**: What the agent does
+- **Instructions**: Detailed prompts that guide the AI's behavior
+- **Model**: Which AI model to use (GPT-4.1-mini is fast and cost-effective)
+
+## Registering and Testing Your Agent
+
+Open your `src/mastra/index.ts` file and add your agent (you may need to append it to the agents object in the Mastra class):
+
+```typescript
+// Import your workflow
+import { contentAgent } from './agents/content-agent'
+
+export const mastra = new Mastra({
+  // Register your agent here
+  agents: {
+    contentAgent,
+  },
+  // ...Existing code
+})
+```
+
+You can test this agent in the Playground by navigating to the Agents tab and selecting `content-agent`. Use the chat interface to validate the agent is working.
+
+The agent should provide analysis of the content, including themes, quality assessment, and improvement suggestions.
+
+## Why Use Agents in Workflows?
+
+Agents add intelligence to workflows by:
+
+- **Understanding context**: AI can interpret meaning, not just process data
+- **Generating insights**: Provide analysis that simple logic cannot
+- **Adapting responses**: Give different feedback based on content type
+- **Natural language output**: Communicate results in human-readable form
+
+Your AI agent is ready! Next, you'll learn how to integrate it into a workflow step.

package/.docs/course/04-workflows/12-using-agent-in-workflow.md

@@ -0,0 +1,89 @@
+# Using Agent in Workflow
+
+Now you'll create a workflow step that uses your AI agent to provide intelligent content analysis.
+
+In each step, in the execute function, you have access to the `mastra` class which provides you the ability to access Agents, Tools, and even other Workflows. In this case, we use the `mastra` class to get our agent and call that agent's `generate()` function.
+
+## Creating an AI Analysis Step
+
+Add this step to your workflow file:
+
+```typescript
+const aiAnalysisStep = createStep({
+  id: 'ai-analysis',
+  description: 'AI-powered content analysis',
+  inputSchema: 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(),
+    }),
+    summary: z.string(),
+  }),
+  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(),
+    }),
+    summary: z.string(),
+    aiAnalysis: z.object({
+      score: z.number(),
+      feedback: z.string(),
+    }),
+  }),
+  execute: async ({ inputData, mastra }) => {
+    const { content, type, wordCount, metadata, summary } = inputData
+
+    // Create prompt for the AI agent
+    const prompt = `
+Analyze this ${type} content:
+
+Content: "${content}"
+Word count: ${wordCount}
+Reading time: ${metadata.readingTime} minutes
+Difficulty: ${metadata.difficulty}
+
+Please provide:
+1. A quality score from 1-10
+2. Brief feedback on strengths and areas for improvement
+
+Format as JSON: {"score": number, "feedback": "your feedback here"}
+    `
+
+    // Get the contentAgent from the mastra instance.
+    const contentAgent = mastra.getAgent('contentAgent')
+    const { text } = await contentAgent.generate([{ role: 'user', content: prompt }])
+
+    // Parse AI response (with fallback)
+    let aiAnalysis
+    try {
+      aiAnalysis = JSON.parse(text)
+    } catch {
+      aiAnalysis = {
+        score: 7,
+        feedback: 'AI analysis completed. ' + text,
+      }
+    }
+
+    console.log(`🤖 AI Score: ${aiAnalysis.score}/10`)
+
+    return {
+      content,
+      type,
+      wordCount,
+      metadata,
+      summary,
+      aiAnalysis,
+    }
+  },
+})
+```
+
+Your agent-powered step is ready! Next, you'll add it to your workflow for complete AI-enhanced content processing.

package/.docs/course/04-workflows/13-creating-ai-enhanced-workflow.md

@@ -0,0 +1,72 @@
+# Creating AI-Enhanced Workflow
+
+Now you'll create a new workflow that includes agent analysis alongside your existing content processing steps.
+
+## Creating the Enhanced Workflow
+
+Add this new workflow to your file:
+
+```typescript
+export const aiContentWorkflow = createWorkflow({
+  id: 'ai-content-workflow',
+  description: 'AI-enhanced content processing with analysis',
+  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(),
+    }),
+    summary: z.string(),
+    aiAnalysis: z.object({
+      score: z.number(),
+      feedback: z.string(),
+    }),
+  }),
+})
+  .then(validateContentStep)
+  .then(enhanceContentStep)
+  .then(generateSummaryStep)
+  .then(aiAnalysisStep)
+  .commit()
+```
+
+## Registering the New Workflow
+
+Update your Mastra configuration to include both workflows and ensure the contentAgent has been added.
+
+```typescript
+// In src/mastra/index.ts
+import { contentWorkflow, aiContentWorkflow } from './workflows/content-workflow'
+import { contentAgent } from './agents/content-agent'
+
+export const mastra = new Mastra({
+  workflows: {
+    contentWorkflow,
+    aiContentWorkflow, // Add the AI-enhanced version
+  },
+  agents: { contentAgent },
+  // ... rest of configuration
+})
+```
+
+## Testing the Agent-Enhanced Workflow
+
+You can now access this new Workflow inside the Mastra playground. Select this new `ai-content-workflow` workflow from the Workflows tab and run a test to validate it works as expected.
+
+## The Complete AI Pipeline
+
+Your AI-enhanced workflow now:
+
+1. **Validates** content and counts words
+2. **Enhances** with metadata
+3. **Summarizes** the content
+4. **Analyzes** with AI for quality scoring and feedback
+
+This creates a comprehensive, AI-powered content processing system! Next, you'll learn about parallel execution.

package/.docs/course/04-workflows/14-understanding-parallel-execution.md

@@ -0,0 +1,38 @@
+# Understanding Parallel Execution
+
+Learn how to run multiple workflow steps simultaneously to improve performance when steps don't depend on each other.
+
+## When to Use Parallel Execution
+
+Use parallel execution when you have steps that:
+
+- **Don't depend on each other**: Can run independently
+- **Take time**: Network requests, AI calls, or heavy computations
+- **Process the same input**: Multiple analyses of the same data
+
+## Example Scenario
+
+Imagine you want to analyze content in three different ways:
+
+1. SEO analysis
+2. Readability analysis
+3. Sentiment analysis
+
+These can all run at the same time since they don't depend on each other!
+
+## Creating Parallel Steps
+
+The .parallel() method on a workflow executes multiple steps in parallel.
+
+```typescript
+workflow.parallel([stepOne, stepTwo])
+```
+
+## Performance Benefits
+
+Running steps in parallel:
+
+- **Faster execution**: Steps run simultaneously instead of waiting
+- **Improved user experience**: Shorter wait times
+
+Next, you'll create the other parallel steps and see how to combine them!

package/.docs/course/04-workflows/15-creating-parallel-steps.md

@@ -0,0 +1,111 @@
+# Creating Parallel Steps
+
+Let's create three analysis steps that can run simultaneously to analyze different aspects of content.
+
+## Creating the Analysis Steps
+
+Add these three steps to your workflow file:
+
+```typescript
+// SEO Analysis
+const seoAnalysisStep = createStep({
+  id: 'seo-analysis',
+  description: 'SEO optimization analysis',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    seoScore: z.number(),
+    keywords: z.array(z.string()),
+  }),
+  execute: async ({ inputData }) => {
+    console.log('🔍 Running SEO analysis...')
+    await new Promise(resolve => setTimeout(resolve, 800))
+
+    const words = inputData.content.toLowerCase().split(/\s+/)
+    const keywords = words.filter(word => word.length > 4).slice(0, 3)
+
+    return {
+      seoScore: Math.floor(Math.random() * 40) + 60,
+      keywords,
+    }
+  },
+})
+
+// Readability Analysis
+const readabilityStep = createStep({
+  id: 'readability-analysis',
+  description: 'Content readability analysis',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    readabilityScore: z.number(),
+    gradeLevel: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    console.log('📖 Running readability analysis...')
+    await new Promise(resolve => setTimeout(resolve, 600))
+
+    const sentences = inputData.content.split(/[.!?]+/).length
+    const words = inputData.content.split(/\s+/).length
+    const avgWordsPerSentence = words / sentences
+
+    const score = Math.max(0, 100 - avgWordsPerSentence * 3)
+    const gradeLevel = score > 80 ? 'Easy' : score > 60 ? 'Medium' : 'Hard'
+
+    return {
+      readabilityScore: Math.floor(score),
+      gradeLevel,
+    }
+  },
+})
+
+// Sentiment Analysis
+const sentimentStep = createStep({
+  id: 'sentiment-analysis',
+  description: 'Content sentiment analysis',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    confidence: z.number(),
+  }),
+  execute: async ({ inputData }) => {
+    console.log('😊 Running sentiment analysis...')
+    await new Promise(resolve => setTimeout(resolve, 700))
+
+    const content = inputData.content.toLowerCase()
+    const positiveWords = ['good', 'great', 'excellent', 'amazing']
+    const negativeWords = ['bad', 'terrible', 'awful', 'horrible']
+
+    const positive = positiveWords.filter(word => content.includes(word)).length
+    const negative = negativeWords.filter(word => content.includes(word)).length
+
+    let sentiment: 'positive' | 'neutral' | 'negative' = 'neutral'
+    if (positive > negative) sentiment = 'positive'
+    if (negative > positive) sentiment = 'negative'
+
+    return {
+      sentiment,
+      confidence: Math.random() * 0.3 + 0.7, // 0.7-1.0
+    }
+  },
+})
+```
+
+## Notice the Timing
+
+Each step has a different simulated processing time:
+
+- SEO: 800ms
+- Readability: 600ms
+- Sentiment: 700ms
+
+When run sequentially, total time would be ~2.2 seconds. When run in parallel, total time will be ~800ms (the longest step)!
+
+Next, you'll learn how to run these steps in parallel using the `.parallel()` method.

package/.docs/course/04-workflows/16-building-parallel-workflow.md

@@ -0,0 +1,100 @@
+# Building Parallel Workflow
+
+Now you'll create a workflow that runs your analysis steps in parallel for maximum performance.
+
+## Creating the Parallel Workflow
+
+Add this workflow to your file:
+
+```typescript
+export const parallelAnalysisWorkflow = createWorkflow({
+  id: 'parallel-analysis-workflow',
+  description: 'Run multiple content analyses in parallel',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    results: z.object({
+      seo: z.object({
+        seoScore: z.number(),
+        keywords: z.array(z.string()),
+      }),
+      readability: z.object({
+        readabilityScore: z.number(),
+        gradeLevel: z.string(),
+      }),
+      sentiment: z.object({
+        sentiment: z.enum(['positive', 'neutral', 'negative']),
+        confidence: z.number(),
+      }),
+    }),
+  }),
+})
+  .parallel([seoAnalysisStep, readabilityStep, sentimentStep])
+  .then(
+    createStep({
+      id: 'combine-results',
+      description: 'Combines parallel analysis results',
+      inputSchema: z.object({
+        'seo-analysis': z.object({
+          seoScore: z.number(),
+          keywords: z.array(z.string()),
+        }),
+        'readability-analysis': z.object({
+          readabilityScore: z.number(),
+          gradeLevel: z.string(),
+        }),
+        'sentiment-analysis': z.object({
+          sentiment: z.enum(['positive', 'neutral', 'negative']),
+          confidence: z.number(),
+        }),
+      }),
+      outputSchema: z.object({
+        results: z.object({
+          seo: z.object({
+            seoScore: z.number(),
+            keywords: z.array(z.string()),
+          }),
+          readability: z.object({
+            readabilityScore: z.number(),
+            gradeLevel: z.string(),
+          }),
+          sentiment: z.object({
+            sentiment: z.enum(['positive', 'neutral', 'negative']),
+            confidence: z.number(),
+          }),
+        }),
+      }),
+      execute: async ({ inputData }) => {
+        console.log('🔄 Combining parallel results...')
+
+        return {
+          results: {
+            seo: inputData['seo-analysis'],
+            readability: inputData['readability-analysis'],
+            sentiment: inputData['sentiment-analysis'],
+          },
+        }
+      },
+    }),
+  )
+  .commit()
+```
+
+## Understanding Parallel Data Flow
+
+When steps run in parallel:
+
+1. Each step receives the same input data
+2. Steps execute simultaneously
+3. Results are collected into an object with step IDs as keys
+4. The next step receives all parallel results
+
+## Key Points
+
+- **`.parallel([step1, step2, step3])`**: Runs all steps simultaneously
+- **Result object keys**: Use the step IDs (e.g., "seo-analysis")
+- **Combine step**: Processes all parallel results together
+
+Next, you'll test this parallel workflow and see the performance improvement!