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

package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md

@@ -1,5 +1,12 @@
 # @mastra/dynamodb
 
+## 0.12.0-alpha.4
+
+### Patch Changes
+
+- ab52239: dependencies updates:
+  - Updated dependency [`@aws-sdk/lib-dynamodb@^3.830.0` ↗︎](https://www.npmjs.com/package/@aws-sdk/lib-dynamodb/v/3.830.0) (from `^3.828.0`, in `dependencies`)
+
 ## 0.12.0-alpha.3
 
 ### Minor Changes
@@ -291,12 +298,5 @@
 - Updated dependencies [2901125]
   - @mastra/core@0.10.2-alpha.1
 
-## 0.10.0
-
-### Patch Changes
-
-- b3a3d63: BREAKING: Make vnext workflow the default worklow, and old workflow legacy_workflow
-- d2d4fe4: Add a DynamoDB storage connector using a single-table design pattern with ElectroDB.
-
 
-... 56 more lines hidden. See full changelog in package directory.
+... 63 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md

@@ -1,5 +1,11 @@
 # @mastra/mcp-docs-server
 
+## 0.13.2-alpha.3
+
+### Patch Changes
+
+- d2a783c: Minor lesson 1 course updates, added lesson 4 on workflows
+
 ## 0.13.2-alpha.2
 
 ### Patch Changes
@@ -292,11 +298,5 @@
 - Updated dependencies [f53a6ac]
 - Updated dependencies [5eb5a99]
 - Updated dependencies [7e632c5]
-- Updated dependencies [1e9fbfa]
-- Updated dependencies [eabdcd9]
-- Updated dependencies [90be034]
-- Updated dependencies [99f050a]
-- Updated dependencies [d0ee3c6]
-- Updated dependencies [b2ae5aa]
-
-... 855 more lines hidden. See full changelog in package directory.
+
+... 861 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md

@@ -1,5 +1,12 @@
 # @mastra/playground-ui
 
+## 5.1.7-alpha.5
+
+### Patch Changes
+
+- d569c16: dependencies updates:
+  - Updated dependency [`react-code-block@1.1.3` ↗︎](https://www.npmjs.com/package/react-code-block/v/1.1.3) (from `1.1.1`, in `dependencies`)
+
 ## 5.1.7-alpha.4
 
 ### Patch Changes
@@ -292,11 +299,4 @@
 
 - e719504: don't start posthog when the browser is Brave
 
-## 5.1.4-alpha.1
-
-### Patch Changes
-
-- 1ccccff: dependencies updates:
-  - Updated dependency [`zod@^3.25.56` ↗︎](https://www.npmjs.com/package/zod/v/3.25.56) (from `^3.24.3`, in `dependencies`)
-
-... 1649 more lines hidden. See full changelog in package directory.
+... 1656 more lines hidden. See full changelog in package directory.

package/.docs/raw/course/01-first-agent/04-project-structure.md

@@ -4,9 +4,14 @@ Let's check that your project has the correct structure. You should have:
 
 1. A `src/mastra` directory that contains:
    - `index.ts` - The main entry point for your Mastra project
-   - `agents/index.ts` - Where your agents are defined
-   - `tools/index.ts` - Where your tools are defined
+   - `agents/` - Directory containing individual agent files
+   - `tools/` - Directory containing individual tool files
+   - `workflows/` - Directory containing individual workflow files
 
-If these files exist, you're ready to start building your agent!
+If the CLI created your project, you should see files like:
+
+- `agents/weather-agent.ts` - Example weather agent
+- `tools/weather-tool.ts` - Example weather tool
+- `workflows/weather-workflow.ts` - Example weather workflow
 
 This structure is important because it follows the Mastra convention for organizing your code. The `index.ts` file is the main entry point for your Mastra project, while the `agents` and `tools` directories contain the definitions for your agents and tools, respectively.

package/.docs/raw/course/01-first-agent/07-creating-your-agent.md

@@ -1,11 +1,13 @@
 # Creating Your Agent
 
-Let's create a simple agent that will help users analyze financial transaction data. We'll start by modifying the `agents/index.ts` file.
+Let's create a simple agent that will help users analyze financial transaction data. We'll create a new file called `agents/financial-agent.ts`.
 
-First, make sure you have the necessary imports at the top of your file:
+First, create the new agent file at src/mastra/agents/financial-agent.ts
+
+Now add the necessary imports at the top of your file:
 
 ```typescript
-import { Agent } from "@mastra/core";
+import { Agent } from "@mastra/core/agent";
 import { openai } from "@ai-sdk/openai";
 // We'll import our tool in a later step
 ```

package/.docs/raw/course/01-first-agent/08-exporting-your-agent.md

@@ -1,18 +1,32 @@
 # Exporting Your Agent
 
-To make your agent available to the playground, you need to export it through the Mastra class in your `src/mastra/index.ts` file:
+To make your agent available to the playground, you need to export it through the Mastra class in your `src/mastra/index.ts` file.
+
+First, import the necessary dependencies and your agent:
 
 ```typescript
-import { Mastra } from "@mastra/core";
-import { financialAgent } from "./agents";
+import { Mastra } from "@mastra/core/mastra";
+import { PinoLogger } from "@mastra/loggers";
+import { LibSQLStore } from "@mastra/libsql";
+import { financialAgent } from "./agents/financial-agent";
 
-export const mastra: Mastra = new Mastra({
+export const mastra = new Mastra({
   agents: {
     financialAgent,
   },
+  storage: new LibSQLStore({
+    url: ":memory:",
+  }),
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
 });
 ```
 
-This creates a new Mastra instance that includes your financial agent, making it available to the playground and any other parts of your application.
+This creates a new Mastra instance that includes:
+- Your financial agent
+- In-memory storage for development
+- A logger for debugging and monitoring
 
-The Mastra class is the main entry point for your Mastra project. It's responsible for registering your agents and making them available to the rest of your application. By adding your agent to the Mastra instance, you're telling Mastra that this agent should be available for use.
+The Mastra class is the main entry point for your Mastra project. It's responsible for registering your agents and configuring the core services like storage and logging.

package/.docs/raw/course/01-first-agent/11-creating-transactions-tool.md

@@ -1,11 +1,13 @@
 # Creating the getTransactions Tool
 
-Let's create a tool that fetches transaction data from a Google Sheet. We'll add this to your `tools/index.ts` file.
+Let's create a tool that fetches transaction data from a Google Sheet. We'll create a new file called `tools/get-transactions-tool.ts`.
 
-First, make sure you have the necessary imports:
+First, create the new tool file at src/mastra/tools/get-transactions-tool.ts
+
+Now add the necessary imports:
 
 ```typescript
-import { createTool } from "@mastra/core";
+import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 ```
 

package/.docs/raw/course/01-first-agent/12-connecting-tool-to-agent.md

@@ -1,11 +1,11 @@
 # Connecting the Tool to Your Agent
 
-Now that we've created our tool, we need to connect it to our agent. Go back to your `agents/index.ts` file and update it:
+Now that we've created our tool, we need to connect it to our agent. Go back to your `agents/financial-agent.ts` file and update it:
 
 1. Import the tool:
 
 ```typescript
-import { getTransactionsTool } from "../tools";
+import { getTransactionsTool } from "../tools/get-transactions-tool";
 ```
 
 2. Add the tool to your agent:

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