@mastra/mcp-docs-server 0.13.2-alpha.2 → 0.13.2

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

@@ -0,0 +1,91 @@
+# 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/raw/course/04-workflows/13-creating-ai-enhanced-workflow.md

@@ -0,0 +1,75 @@
+# 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/raw/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/raw/course/04-workflows/15-creating-parallel-steps.md

@@ -0,0 +1,115 @@
+# 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/raw/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!

package/.docs/raw/course/04-workflows/17-testing-parallel-performance.md

@@ -0,0 +1,40 @@
+# Testing Parallel Workflow
+
+Let's test your parallel workflow.
+
+## Registering the New Workflow
+
+Update your Mastra configuration to include your new workflow workflows:
+
+```typescript
+// In src/mastra/index.ts
+import {
+  contentWorkflow,
+  aiContentWorkflow,
+  parallelAnalysisWorkflow,
+} from "./workflows/content-workflow";
+
+export const mastra = new Mastra({
+  workflows: {
+    contentWorkflow,
+    aiContentWorkflow,
+    parallelAnalysisWorkflow, // Add the parallel workflow
+  },
+  // ... rest of configuration
+});
+```
+
+## Testing the Parallel Workflow
+
+You can now test this new workflow in the Playground. You will notice that it processes the three analysis steps in parallel speeding up execution time.
+
+## When to Use Parallel Execution
+
+Use parallel execution when:
+
+- Steps don't depend on each other's outputs
+- Steps involve I/O operations (API calls, database queries)
+- You want to maximize performance
+- Steps process the same input data
+
+Register your parallel workflow with Mastra to use it in the playground! Next, you'll learn about conditional branching.

package/.docs/raw/course/04-workflows/18-understanding-conditional-branching.md

@@ -0,0 +1,61 @@
+# Understanding Conditional Branching
+
+Learn how to create workflows that take different paths based on data conditions, making your workflows more intelligent and adaptive.
+
+## What is Conditional Branching?
+
+Conditional branching allows workflows to:
+
+- **Make decisions**: Choose different processing paths based on data
+- **Handle variations**: Process different content types differently
+- **Optimize performance**: Skip unnecessary steps for certain inputs
+- **Customize behavior**: Provide different experiences based on conditions
+
+## Real-World Example
+
+Imagine a content processing workflow that:
+
+- **Short content** (< 50 words): Gets quick processing
+- **Medium content** (50-200 words): Gets standard processing
+- **Long content** (> 200 words): Gets detailed processing with extra analysis
+
+## Basic Branching Syntax
+
+```typescript
+.branch([
+  [condition1, step1],
+  [condition2, step2],
+  [condition3, step3]
+])
+```
+
+Where:
+
+- **condition**: An async function that returns `true` or `false`
+- **step**: The step to execute if the condition is `true`
+
+## Condition Functions
+
+Conditions are functions that examine the input data:
+
+```typescript
+// Example condition function
+async ({ inputData }) => {
+  return inputData.wordCount < 50;
+};
+```
+
+## Multiple Paths
+
+- If multiple conditions are `true`, **all matching steps run in parallel**
+- If no conditions are `true`, the workflow continues without executing any branch steps
+- Conditions are evaluated in order, but matching steps run simultaneously
+
+## Benefits
+
+- **Smart routing**: Send data down the most appropriate path
+- **Performance**: Skip expensive operations when not needed
+- **Flexibility**: Handle different scenarios in one workflow
+- **Maintainability**: Clear logic for different processing paths
+
+Next, you'll create a workflow with conditional branches!

package/.docs/raw/course/04-workflows/19-creating-conditional-steps.md

@@ -0,0 +1,128 @@
+# Creating Conditional Steps
+
+Let's create two processing steps for different types of content: one for short and simple content, and one for everything else.
+
+## Assessment Step
+
+First, create a step that analyzes content to determine which path to take:
+
+```typescript
+const assessContentStep = createStep({
+  id: "assess-content",
+  description: "Assesses content to determine processing path",
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(["article", "blog", "social"]).default("article"),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.enum(["article", "blog", "social"]).default("article"),
+    wordCount: z.number(),
+    complexity: z.enum(["simple", "moderate", "complex"]),
+    category: z.enum(["short", "medium", "long"]),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type } = inputData;
+    const words = content.trim().split(/\s+/);
+    const wordCount = words.length;
+
+    // Determine category by length
+    let category: "short" | "medium" | "long" = "short";
+    if (wordCount >= 50) category = "medium";
+    if (wordCount >= 200) category = "long";
+
+    // Determine complexity by average word length
+    const avgWordLength =
+      words.reduce((sum, word) => sum + word.length, 0) / wordCount;
+    let complexity: "simple" | "moderate" | "complex" = "simple";
+    if (avgWordLength > 5) complexity = "moderate";
+    if (avgWordLength > 7) complexity = "complex";
+
+    console.log(`📋 Assessment: ${category} content, ${complexity} complexity`);
+
+    return {
+      content,
+      type,
+      wordCount,
+      complexity,
+      category,
+    };
+  },
+});
+```
+
+## Quick Processing Step
+
+For short, simple content:
+
+```typescript
+const quickProcessingStep = createStep({
+  id: "quick-processing",
+  description: "Quick processing for short and simple content",
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(["article", "blog", "social"]).default("article"),
+    wordCount: z.number(),
+    complexity: z.enum(["simple", "moderate", "complex"]),
+    category: z.enum(["short", "medium", "long"]),
+  }),
+  outputSchema: z.object({
+    processedContent: z.string(),
+    processingType: z.string(),
+    recommendations: z.array(z.string()),
+  }),
+  execute: async ({ inputData }) => {
+    console.log("⚡ Quick processing for short and simple content...");
+
+    return {
+      processedContent: inputData.content,
+      processingType: "quick",
+      recommendations: [
+        "Content is concise",
+        "Consider expanding for more detail",
+      ],
+    };
+  },
+});
+```
+
+## General Processing Step
+
+For all other content (not short and simple):
+
+```typescript
+const generalProcessingStep = createStep({
+  id: "general-processing",
+  description: "General processing for all other content",
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(["article", "blog", "social"]).default("article"),
+    wordCount: z.number(),
+    complexity: z.enum(["simple", "moderate", "complex"]),
+    category: z.enum(["short", "medium", "long"]),
+  }),
+  outputSchema: z.object({
+    processedContent: z.string(),
+    processingType: z.string(),
+    recommendations: z.array(z.string()),
+  }),
+  execute: async ({ inputData }) => {
+    console.log("📝 General processing for non-short/simple content...");
+
+    // Simulate more involved processing
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    return {
+      processedContent: inputData.content,
+      processingType: "general",
+      recommendations: [
+        "Consider simplifying content",
+        "Break up long paragraphs",
+        "Add examples or explanations if needed",
+      ],
+    };
+  },
+});
+```
+
+These two steps will be used in different branches based on the content assessment. Next, you'll create the conditional workflow!