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

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,57 @@
+# 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.

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.