@mastra/mcp-docs-server 0.13.5 → 0.13.7-alpha.0

package/.docs/raw/workflows/control-flow.mdx

@@ -14,7 +14,9 @@ When you build a workflow, you typically break down operations into smaller task
 
 Chain steps to execute sequentially using `.then()`:
 
-```typescript {8-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+![Chaining steps with .then()](/image/workflows/workflows-control-flow-then.jpg)
+
+```typescript {8-9,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -29,11 +31,13 @@ export const testWorkflow = createWorkflow({...})
 
 This does what you'd expect: it executes `step1`, then it executes `step2`.
 
-## Parallel steps with `.parallel()`:
+## Simultaneous steps with `.parallel()`
+
+Execute steps simultaneously using `.parallel()`:
 
-Execute steps in parallel using `.parallel()`:
+![Concurrent steps with .parallel()](/image/workflows/workflows-control-flow-parallel.jpg)
 
-```typescript {8} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {8,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -51,11 +55,13 @@ This executes `step1` and `step2` concurrently, then continues to `step3` after
 
 > See [Parallel Execution with Steps](/examples/workflows/parallel-steps) for more information.
 
-## Conditional branching (`.branch()`)
+## Conditional logic with `.branch()`
 
-Create conditional branches using `.branch()`:
+Execute steps conditionally using `.branch()`:
 
-```typescript {8-11} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+![Conditional branching with .branch()](/image/workflows/workflows-control-flow-branch.jpg)
+
+```typescript {8-11,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -74,15 +80,20 @@ Branch conditions are evaluated sequentially, but steps with matching conditions
 
 > See [Workflow with Conditional Branching](/examples/workflows/conditional-branching) for more information.
 
-## Looping commands
+## Looping steps
 
 Workflows support two types of loops. When looping a step, or any step-compatible construct like a nested workflow, the initial `inputData` is sourced from the output of the previous step.
 
 To ensure compatibility, the loop’s initial input must either match the shape of the previous step’s output, or be explicitly transformed using the `map` function.
 
-### `.dowhile()`
+- Match the shape of the previous step’s output, or
+- Be explicitly transformed using the `map` function.
+
+### Repeating with `.dowhile()`
 
-Executes a step repeatedly while a condition is true.
+Executes step repeatedly while a condition is true.
+
+![Repeating with .dowhile()](/image/workflows/workflows-control-flow-dowhile.jpg)
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -95,9 +106,11 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-### `.dountil()`
+### Repeating with `.dountil()`
+
+Executes step repeatedly until a condition becomes true.
 
-Executes a step repeatedly until a condition becomes true.
+![Repeating with .dountil()](/image/workflows/workflows-control-flow-dountil.jpg)
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -110,10 +123,12 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-### `.foreach()`
+### Repeating with `.foreach()`
 
 Sequentially executes the same step for each item from the `inputSchema`.
 
+![Repeating with .foreach()](/image/workflows/workflows-control-flow-foreach.jpg)
+
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
@@ -125,133 +140,116 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-### Early exit with `.bail()`
+#### Setting concurrency limits
 
-You can bail out of a workflow execution successfully by calling `bail()` in a step. This returns whatever payload is passed to the `bail()` function as the result of the workflow.
+Use `concurrency` to execute steps in parallel with a limit on the number of concurrent executions.
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const step1 = createStep({
-  id: 'step1',
-  execute: async ({ bail, inputData }) => {
-    return bail({ result: 'bailed' });
-  },
-  inputSchema: z.object({ value: z.string() }),
-  outputSchema: z.object({ result: z.string() }),
-});
+const mapStep = createStep({...})
 
 export const testWorkflow = createWorkflow({...})
-  .then(step1)
+  .foreach(mapStep, { concurrency: 2 })
   .commit();
 ```
 
-Unsuccessful bails happen through throwing an error in the step.
+## Using a nested workflow
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+Use a nested workflow as a step by passing it to `.then()`. This runs each of its steps in sequence as part of the parent workflow.
+
+```typescript {4,7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const step1 = createStep({
-  id: 'step1',
-  execute: async ({ bail, inputData }) => {
-    throw new Error('bailed');
-  },
-  inputSchema: z.object({ value: z.string() }),
-  outputSchema: z.object({ result: z.string() }),
-});
+export const nestedWorkflow = createWorkflow({...})
 
 export const testWorkflow = createWorkflow({...})
-  .then(step1)
+  .then(nestedWorkflow)
   .commit();
 ```
 
-#### Example Run Instance
-
-The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
-
-```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
+## Cloning a workflow
 
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
+Use `cloneWorkflow` to duplicate an existing workflow. This lets you reuse its structure while overriding parameters like `id`.
 
-const result = await run.start({
-  inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]
-});
-```
+```typescript {6,10} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep, cloneWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
 
-To execute this run from your terminal:
+const step1 = createStep({...});
+const parentWorkflow = createWorkflow({...})
+const clonedWorkflow = cloneWorkflow(parentWorkflow, { id: "cloned-workflow" });
 
-```bash copy
-npx tsx src/test-workflow.ts
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .then(clonedWorkflow)
+  .commit();
 ```
 
-#### Concurrency
+## Exiting early with `bail()`
 
-Optionally, using `concurrency` allows you to execute steps in parallel with a limit on the number of concurrent executions.
+Use `bail()` in a step to exit early with a successful result. This returns the provided payload as the step output and ends workflow execution.
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const mapStep = createStep({...})
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail }) => {
+    return bail({ result: 'bailed' });
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
 
 export const testWorkflow = createWorkflow({...})
-  .foreach(mapStep, { concurrency: 2 })
+  .then(step1)
   .commit();
 ```
 
-## Using a workflow as a step
-
-For greater composability, you can re-use a workflow as a step in another workflow.
+## Exiting early with `Error()`
 
-In the example below, `nestedWorkflow` is used as a step within `testWorkflow`. The `testWorkflow` uses `step1` while the `nestedWorkflow` composes `step2` and `step3`:
+Use `throw new Error()` in a step to exit with an error.
 
-```typescript {4,7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-export const nestedWorkflow = createWorkflow({...})
+const step1 = createStep({
+  id: 'step1',
+  execute: async () => {
+    throw new Error('bailed');
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
 
 export const testWorkflow = createWorkflow({...})
-  .then(nestedWorkflow)
+  .then(step1)
   .commit();
 ```
 
-When using `.branch()` or `.parallel()` to build more complex control flows, executing more than one step requires wrapping those steps in a nested workflow, along with a clear definition of how they should be executed.
+This throws an error from the step and stops workflow execution, returning the error as the result.
 
-## Running nested workflows in parallel
+## Example Run Instance
 
-Workflows themselves can also be executed in parallel.
+The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
 
-```typescript {4-5,8} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
+import { mastra } from "./mastra";
 
-const workflow1 = createWorkflow({...});
-const workflow2 = createWorkflow({...});
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
-export const testWorkflow = createWorkflow({...})
-  .parallel([workflow1, workflow2])
-  .commit();
+const result = await run.start({
+  inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]
+});
 ```
 
-Parallel steps receive previous step results as input. Their outputs are passed into the next step input as an object where the key is the step `id` and the value is the step `output`.
-
-## Cloning workflows
-
-In the example below, `clonedWorkflow` is a clone of `workflow1` and is used as a step within `testWorkflow`. The `clonedWorkflow` is run sequentially after `step1`.
-
-```typescript {5,9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep, cloneWorkflow } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({...});
-const clonedWorkflow = cloneWorkflow(step1, { id: "cloned-workflow" });
+To execute this run from your terminal:
 
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .then(clonedWorkflow)
-  .commit();
+```bash copy
+npx tsx src/test-workflow.ts
 ```

package/.docs/raw/workflows/input-data-mapping.mdx

@@ -12,78 +12,75 @@ Input data mapping allows explicit mapping of values for the inputs of the next
 - A constant value
 - The initial input of the workflow
 
-## Map
+## Mapping with `.map()`
 
 In this example the `output` from `step1` is transformed to match the `inputSchema` required for the `step2`. The value from `step1` is available using the `inputData` parameter of the `.map` function.
 
-```typescript {18} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+![Mapping with .map()](/image/workflows/workflows-data-mapping-map.jpg)
+
+```typescript {9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({...});
 const step2 = createStep({...});
 
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    input: z.number()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  })
-})
+export const testWorkflow = createWorkflow({...})
   .then(step1)
-  .map(({ inputData }) => {
+  .map(async ({ inputData }) => {
     const { value } = inputData;
     return {
-      output: `${value}`
+      output: `new ${value}`
     };
   })
   .then(step2)
   .commit();
 ```
 
-### inputData
+## Using `inputData`
 
 Use `inputData` to access the full output of the previous step:
 
-```typescript {2} showLineNumbers
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+  .then(step1)
   .map(({ inputData }) => {
-    const { value} = inputData;
-    ...
+    console.log(inputData);
   })
 ```
 
-### getStepResult
+## Using `getStepResult()`
 
 Use `getStepResult` to access the full output of a specific step by referencing the step's instance:
 
-```typescript {3} showLineNumbers
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
   .then(step1)
-  .map(({ getStepResult }) => {
+  .map(async ({ getStepResult }) => {
     console.log(getStepResult(step1));
-    ...
   })
 ```
 
-### getInitData
+## Using `getInitData()`
 
 Use `getInitData` to access the initial input data provided to the workflow:
 
-```typescript {3} showLineNumbers
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
   .then(step1)
-  .map(({ getInitData }) => {
+  .map(async ({ getInitData }) => {
       console.log(getInitData());
-    ...
   })
 ```
 
-## Renaming Outputs
+## Using `mapVariable()`
+
+To use `mapVariable` import the necessary function from the workflows module:
 
-### Step Outputs
+```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { mapVariable } from "@mastra/core/workflows";
+```
+
+### Renaming step with `mapVariable()`
 
 You can rename step outputs using the object syntax in `.map()`. In the example below, the `value` output from `step1` is renamed to `details`:
 
-```typescript {3} showLineNumbers
-  .then(step)
+```typescript {3-6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+  .then(step1)
   .map({
     details: mapVariable({
       step: step,
@@ -92,24 +89,15 @@ You can rename step outputs using the object syntax in `.map()`. In the example
   })
 ```
 
-### Workflow Outputs
+### Renaming workflows with `mapVariable()`
 
 You can rename workflow outputs by using **referential composition**. This involves passing the workflow instance as the `initData`.
 
-```typescript {12, 16} showLineNumbers
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  })
-});
+```typescript {6-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+export const testWorkflow = createWorkflow({...});
 
 testWorkflow
-  .then(cityCoordinatesStep)
+  .then(step1)
   .map({
     details: mapVariable({
       initData: testWorkflow,

package/.docs/raw/workflows/overview.mdx

@@ -5,12 +5,14 @@ description: "Workflows in Mastra help you orchestrate complex sequences of oper
 
 import { Steps } from "nextra/components";
 
-# Workflows Overview
+# Workflows overview
 
 Workflows let you define and orchestrate complex sequences of tasks as **typed steps** connected by data flows. Each step has clearly defined inputs and outputs validated by Zod schemas.
 
 A workflow manages execution order, dependencies, branching, parallelism, and error handling — enabling you to build robust, reusable processes. Steps can be nested or cloned to compose larger workflows.
 
+![Workflows overview](/image/workflows/workflows-overview.jpg)
+
 You create workflows by:
 
 - Defining **steps** with `createStep`, specifying input/output schemas and business logic.
@@ -20,7 +22,7 @@ You create workflows by:
 This structure provides full type safety and runtime validation, ensuring data integrity across the entire workflow.
 
 
-## Getting Started
+## Getting started
 
 To use workflows, first import the necessary functions from the workflows module:
 
@@ -29,7 +31,7 @@ import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 ```
 
-### Create Step
+### Create step
 
 Steps are the building blocks of workflows. Create a step using `createStep`:
 
@@ -39,7 +41,7 @@ const step1 = createStep({...});
 
 > See [createStep](/reference/workflows/step) for more information.
 
-### Create Workflow
+### Create workflow
 
 Create a workflow using `createWorkflow` and complete it with `.commit()`.
 
@@ -65,7 +67,7 @@ export const testWorkflow = createWorkflow({
 
 > See [workflow](/reference/workflows/workflow) for more information.
 
-#### Composing Steps
+#### Composing steps
 
 Workflow steps can be composed and executed sequentially using `.then()`.
 
@@ -93,8 +95,7 @@ export const testWorkflow = createWorkflow({
 
 > Steps can be composed using a number of different methods. See [Control Flow](/docs/workflows/control-flow)  for more information.
 
-
-#### Cloning Steps
+#### Cloning steps
 
 Workflow steps can be cloned using `cloneStep()`, and used with any workflow method.
 
@@ -122,7 +123,7 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
-### Register Workflow
+### Register workflow
 
 Register a workflow using `workflows` in the main Mastra instance:
 
@@ -146,7 +147,7 @@ export const mastra = new Mastra({
 });
 ```
 
-### Run Workflow
+### Run workflow
 There are two ways to run and test workflows.
 
 <Steps>
@@ -170,7 +171,13 @@ const result = await run.start({
   }
 });
 
+// Dump the complete workflow result (includes status, steps and result)
 console.log(JSON.stringify(result, null, 2));
+
+// Get the workflow output value
+if (result.status === 'success') {
+  console.log(`output value: ${result.result.output}`);
+}
 ```
 > see [createRunAsync](/reference/workflows/create-run) and [start](/reference/workflows/start) for more information.
 
@@ -182,7 +189,7 @@ npx tsx src/test-workflow.ts
 
 </Steps>
 
-#### Run Workflow Results
+#### Run workflow results
 
 The result of running a workflow using either `start()` or `resume()` will look like one of the following, depending on the outcome.
 
@@ -250,7 +257,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 ```
 - **error**: An optional field that includes the error message if the workflow fails
 
-### Stream Workflow
+### Stream workflow
 
 Similar to the run method shown above, workflows can also be streamed:
 
@@ -294,7 +301,7 @@ const result = await run.start({
 
 > See [watch](/reference/workflows/watch) for more information.
 
-## More Resources
+## More resources
 
 - The [Workflow Guide](../../guides/guide/ai-recruiter.mdx) in the Guides section is a tutorial that covers the main concepts.
 - [Parallel Steps workflow example](../../examples/workflows/parallel-steps.mdx)
@@ -303,4 +310,7 @@ const result = await run.start({
 - [Suspend and Resume workflow example](../../examples/workflows/human-in-the-loop.mdx)
 
 
+## Workflows (Legacy)
+
+For legacy workflow documentation, see [Workflows (Legacy)](/docs/workflows-legacy/overview).
 

package/.docs/raw/workflows/pausing-execution.mdx

@@ -16,7 +16,7 @@ You can pause execution using:
 
 When using any of these methods, the workflow status is set to `waiting` until execution resumes.
 
-## sleep
+## Pausing with `.sleep()`
 
 The `sleep()` method pauses execution between steps for a specified number of milliseconds.
 
@@ -34,7 +34,28 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-## sleepUntil
+### Pausing with `.sleep(callback)`
+
+The `sleep()` method also accepts a callback that returns the number of milliseconds to pause. The callback receives `inputData`, allowing the delay to be computed dynamically.
+
+```typescript {9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .sleep(async ({ inputData }) => {
+    const { delayInMs }  = inputData
+    return delayInMs;
+  })
+  .then(step2)
+  .commit();
+```
+
+## Pausing with `.sleepUntil()`
 
 The `sleepUntil()` method pauses execution between steps until a specified date.
 
@@ -52,12 +73,36 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
+### Pausing with `.sleepUntil(callback)`
+
+The `sleepUntil()` method also accepts a callback that returns a `Date` object. The callback receives `inputData`, allowing the target time to be computed dynamically.
+
+```typescript {9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .sleepUntil(async ({ inputData }) => {
+    const { delayInMs }  = inputData
+    return new Date(Date.now() + delayInMs);
+  })
+  .then(step2)
+  .commit();
+```
+
+
 > `Date.now()` is evaluated when the workflow starts, not at the moment the `sleepUntil()` method is called.
 
-## waitForEvent
+## Pausing with `.waitForEvent()`
 
 The `waitForEvent()` method pauses execution until a specific event is received. Use `run.sendEvent()` to send the event. You must provide both the event name and the step to resume.
 
+![Pausing with .waitForEvent()](/image/workflows/workflows-sleep-events-waitforevent.jpg)
+
 ```typescript {10} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
@@ -72,7 +117,7 @@ export const testWorkflow = createWorkflow({...})
   .then(step3)
   .commit();
 ```
-## sendEvent
+## Sending an event with `.sendEvent()`
 
 The `.sendEvent()` method sends an event to the workflow. It accepts the event name and optional event data, which can be any JSON-serializable value.