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

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

@@ -0,0 +1,70 @@
+# 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/raw/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/raw/course/04-workflows/11-creating-an-ai-agent.md

@@ -0,0 +1,67 @@
+# 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 { openai } from "@ai-sdk/openai";
+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-4o-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-4o-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/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.