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

package/.docs/raw/course/04-workflows/06-registering-with-mastra.md

@@ -0,0 +1,24 @@
+# Registering with Mastra
+
+Now you'll register your workflow with the main Mastra instance so you can use it alongside agents and tools.
+
+## Updating Your Mastra Configuration
+
+Open your `src/mastra/index.ts` file and add your workflow:
+
+```typescript
+// Import your workflow
+import { contentWorkflow } from "./workflows/content-workflow";
+
+export const mastra = new Mastra({
+  // Register your workflow here
+  workflows: {
+    contentWorkflow,
+  },
+  // ...Existing code
+});
+```
+
+Note: You may already have workflows registered, in which case, this workflow should be added to the workflows object.
+
+Your workflow is now registered with Mastra! Next, you'll learn how to use it in the playground.

package/.docs/raw/course/04-workflows/07-using-playground.md

@@ -0,0 +1,58 @@
+# Using the Playground
+
+The Mastra Playground provides a visual interface to test and run your workflows. Let's see your workflow in action!
+
+## Starting the Development Server
+
+Start your Mastra development server using the `mastra dev` command. If you are using npm the command is:
+
+```bash
+npm run dev
+```
+
+You should see output like:
+
+```bash
+🚀 Mastra Dev Server starting...
+📊 Playground available at: http://localhost:4111
+```
+
+## Accessing Workflows in Playground
+
+1. Open your browser and go to `http://localhost:4111`
+2. Click on "Workflows" in the navigation
+3. You should see your `contentWorkflow` listed
+
+## Testing Your Workflow
+
+1. Click on your `contentWorkflow`
+2. You'll see an input form based on your workflow's input schema
+3. Enter some test content in the form:
+
+```json
+{
+  "content": "Machine learning is revolutionizing healthcare by enabling faster diagnoses and personalized treatments.",
+  "type": "article"
+}
+```
+
+4. Click "Run Workflow"
+5. Watch the execution progress and see the results
+
+## Understanding the Interface
+
+The playground shows you:
+
+- **Input Schema**: What data your workflow expects
+- **Execution Progress**: Real-time updates as steps complete
+- **Output**: The final result from your workflow
+- **Execution Time**: How long the workflow took to run
+
+## Benefits of the Playground
+
+- **Visual Testing**: Easy way to test workflows without writing code
+- **Schema Validation**: Automatic form generation from your schemas
+- **Real-time Feedback**: See exactly what's happening during execution
+- **Easy Debugging**: Quickly test different inputs and view traces from workflow runs
+
+Great! You can now visually test your workflow. Next, you'll learn how to run workflows programmatically.

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

@@ -0,0 +1,77 @@
+# 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 = 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/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.