@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/reference/workflows/step-function.mdx

@@ -0,0 +1,92 @@
+---
+title: "Reference: Workflow.step() | Workflows | Mastra Docs"
+description: Documentation for the `.step()` method in workflows, which adds a new step to the workflow.
+---
+
+# Workflow.step()
+
+The `.step()` method adds a new step to the workflow, optionally configuring its variables and execution conditions.
+
+## Usage
+
+```typescript
+workflow.step({
+  id: "stepTwo",
+  outputSchema: z.object({
+    result: z.number()
+  }),
+  execute: async ({ context }) => {
+    return { result: 42 };
+  }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "stepConfig",
+      type: "Step | StepDefinition | string",
+      description: "Step instance, configuration object, or step ID to add to workflow",
+      isOptional: false
+    },
+    {
+      name: "options",
+      type: "StepOptions",
+      description: "Optional configuration for step execution",
+      isOptional: true
+    }
+  ]}
+/>
+
+### StepDefinition
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      isOptional: false
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodSchema",
+      description: "Schema for validating step output",
+      isOptional: true
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
+      description: "Function containing step logic",
+      isOptional: false
+    }
+  ]}
+/>
+
+### StepOptions
+
+<PropertiesTable
+  content={[
+    {
+      name: "variables",
+      type: "Record<string, VariableRef>",
+      description: "Map of variable names to their source references",
+      isOptional: true
+    },
+    {
+      name: "when",
+      type: "StepCondition",
+      description: "Condition that must be met for step to execute",
+      isOptional: true
+    }
+  ]}
+/>
+
+## Related
+- [Basic Usage with Step Instance](../../workflows/steps.mdx)
+- [Step Class Reference](./step-class.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

package/.docs/raw/reference/workflows/step-options.mdx

@@ -0,0 +1,69 @@
+---
+title: "Reference: StepOptions | Building Workflows | Mastra Docs"
+description: Documentation for the step options in workflows, which control variable mapping, execution conditions, and other runtime behavior.
+---
+
+# StepOptions
+
+Configuration options for workflow steps that control variable mapping, execution conditions, and other runtime behavior.
+
+## Usage
+
+```typescript
+workflow.step(processOrder, {
+  variables: {
+    orderId: { step: 'trigger', path: 'id' },
+    userId: { step: 'auth', path: 'user.id' }
+  },
+  when: {
+    ref: { step: 'auth', path: 'status' },
+    query: { $eq: 'authenticated' }
+  }
+});
+```
+
+## Properties
+
+<PropertiesTable
+  content={[
+    {
+      name: "variables",
+      type: "Record<string, VariableRef>",
+      description: "Maps step input variables to values from other steps",
+      isOptional: true
+    },
+    {
+      name: "when",
+      type: "StepCondition",
+      description: "Condition that must be met for step execution",
+      isOptional: true
+    }
+  ]}
+/>
+
+### VariableRef
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "string | Step | { id: string }",
+      description: "Source step for the variable value",
+      isOptional: false
+    },
+    {
+      name: "path",
+      type: "string",
+      description: "Path to the value in the step's output",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Related
+- [Path Comparison](../../workflows/control-flow.mdx#path-comparison)
+- [Step Function Reference](./step-function.mdx)
+- [Step Class Reference](./step-class.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

package/.docs/raw/reference/workflows/step-retries.mdx

@@ -0,0 +1,203 @@
+---
+title: "Step Retries | Error Handling | Mastra Docs"
+description: "Automatically retry failed steps in Mastra workflows with configurable retry policies."
+---
+
+# Step Retries
+
+Mastra provides built-in retry mechanisms to handle transient failures in workflow steps. This allows workflows to recover gracefully from temporary issues without requiring manual intervention.
+
+## Overview
+
+When a step in a workflow fails (throws an exception), Mastra can automatically retry the step execution based on a configurable retry policy. This is useful for handling:
+
+- Network connectivity issues
+- Service unavailability
+- Rate limiting
+- Temporary resource constraints
+- Other transient failures
+
+## Default Behavior
+
+By default, steps do not retry when they fail. This means:
+
+- A step will execute once
+- If it fails, it will immediately mark the step as failed
+- The workflow will continue to execute any subsequent steps that don't depend on the failed step
+
+## Configuration Options
+
+Retries can be configured at two levels:
+
+### 1. Workflow-level Configuration
+
+You can set a default retry configuration for all steps in a workflow:
+
+```typescript
+const workflow = new Workflow({
+  name: 'my-workflow',
+  retryConfig: {
+    attempts: 3,    // Number of retries (in addition to the initial attempt)
+    delay: 1000,    // Delay between retries in milliseconds
+  },
+});
+```
+
+### 2. Step-level Configuration
+
+You can also configure retries on individual steps, which will override the workflow-level configuration for that specific step:
+
+```typescript
+const fetchDataStep = new Step({
+  id: 'fetchData',
+  execute: async () => {
+    // Fetch data from external API
+  },
+  retryConfig: {
+    attempts: 5,    // This step will retry up to 5 times
+    delay: 2000,    // With a 2-second delay between retries
+  },
+});
+```
+
+## Retry Parameters
+
+The `retryConfig` object supports the following parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `attempts` | number | 0 | The number of retry attempts (in addition to the initial attempt) |
+| `delay` | number | 1000 | Time in milliseconds to wait between retries |
+
+## How Retries Work
+
+When a step fails, Mastra's retry mechanism:
+
+1. Checks if the step has retry attempts remaining
+2. If attempts remain:
+   - Decrements the attempt counter
+   - Transitions the step to a "waiting" state
+   - Waits for the configured delay period
+   - Retries the step execution
+3. If no attempts remain or all attempts have been exhausted:
+   - Marks the step as "failed"
+   - Continues workflow execution (for steps that don't depend on the failed step)
+
+During retry attempts, the workflow execution remains active but paused for the specific step that is being retried.
+
+## Examples
+
+### Basic Retry Example
+
+```typescript
+import { Workflow, Step } from '@mastra/core/workflows';
+
+// Define a step that might fail
+const unreliableApiStep = new Step({
+  id: 'callUnreliableApi',
+  execute: async () => {
+    // Simulate an API call that might fail
+    const random = Math.random();
+    if (random < 0.7) {
+      throw new Error('API call failed');
+    }
+    return { data: 'API response data' };
+  },
+  retryConfig: {
+    attempts: 3,  // Retry up to 3 times
+    delay: 2000,  // Wait 2 seconds between attempts
+  },
+});
+
+// Create a workflow with the unreliable step
+const workflow = new Workflow({
+  name: 'retry-demo-workflow',
+});
+
+workflow
+  .step(unreliableApiStep)
+  .then(processResultStep)
+  .commit();
+```
+
+### Workflow-level Retries with Step Override
+
+```typescript
+import { Workflow, Step } from '@mastra/core/workflows';
+
+// Create a workflow with default retry configuration
+const workflow = new Workflow({
+  name: 'multi-retry-workflow',
+  retryConfig: {
+    attempts: 2,  // All steps will retry twice by default
+    delay: 1000,  // With a 1-second delay
+  },
+});
+
+// This step uses the workflow's default retry configuration
+const standardStep = new Step({
+  id: 'standardStep',
+  execute: async () => {
+    // Some operation that might fail
+  },
+});
+
+// This step overrides the workflow's retry configuration
+const criticalStep = new Step({
+  id: 'criticalStep',
+  execute: async () => {
+    // Critical operation that needs more retry attempts
+  },
+  retryConfig: {
+    attempts: 5,  // Override with 5 retry attempts
+    delay: 5000,  // And a longer 5-second delay
+  },
+});
+
+// This step disables retries
+const noRetryStep = new Step({
+  id: 'noRetryStep',
+  execute: async () => {
+    // Operation that should not retry
+  },
+  retryConfig: {
+    attempts: 0,  // Explicitly disable retries
+  },
+});
+
+workflow
+  .step(standardStep)
+  .then(criticalStep)
+  .then(noRetryStep)
+  .commit();
+```
+
+## Monitoring Retries
+
+You can monitor retry attempts in your logs. Mastra logs retry-related events at the `debug` level:
+
+```
+[DEBUG] Step fetchData failed (runId: abc-123)
+[DEBUG] Attempt count for step fetchData: 2 remaining attempts (runId: abc-123)
+[DEBUG] Step fetchData waiting (runId: abc-123)
+[DEBUG] Step fetchData finished waiting (runId: abc-123)
+[DEBUG] Step fetchData pending (runId: abc-123)
+```
+
+## Best Practices
+
+1. **Use Retries for Transient Failures**: Only configure retries for operations that might experience transient failures. For deterministic errors (like validation failures), retries won't help.
+
+2. **Set Appropriate Delays**: Consider using longer delays for external API calls to allow time for services to recover.
+
+3. **Limit Retry Attempts**: Don't set extremely high retry counts as this could cause workflows to run for excessive periods during outages.
+
+4. **Implement Idempotent Operations**: Ensure your step's `execute` function is idempotent (can be called multiple times without side effects) since it may be retried.
+
+5. **Consider Backoff Strategies**: For more advanced scenarios, consider implementing exponential backoff in your step's logic for operations that might be rate-limited.
+
+## Related
+
+- [Step Class Reference](./step-class.mdx)
+- [Workflow Configuration](./workflow.mdx)
+- [Error Handling in Workflows](../../workflows/error-handling.mdx)

package/.docs/raw/reference/workflows/suspend.mdx

@@ -0,0 +1,70 @@
+---
+title: "Reference: suspend() | Control Flow | Mastra Docs"
+description: "Documentation for the suspend function in Mastra workflows, which pauses execution until resumed."
+---
+
+# suspend()
+
+Pauses workflow execution at the current step until explicitly resumed. The workflow state is persisted and can be continued later.
+
+## Usage Example
+
+```typescript
+const approvalStep = new Step({
+  id: "needsApproval",
+  execute: async ({ context, suspend }) => {
+    if (context.steps.amount > 1000) {
+      await suspend();
+    }
+    return { approved: true };
+  }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Optional data to store with the suspended state",
+      isOptional: true
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "Promise<void>",
+      type: "Promise",
+      description: "Resolves when the workflow is successfully suspended"
+    }
+  ]}
+/>
+
+## Additional Examples
+
+Suspend with metadata:
+
+```typescript
+const reviewStep = new Step({
+  id: "review",
+  execute: async ({ context, suspend }) => {
+    await suspend({
+      reason: "Needs manager approval",
+      requestedBy: context.user
+    });
+    return { reviewed: true };
+  }
+});
+```
+
+### Related
+
+- [Suspend & Resume Workflows](../../workflows/suspend-and-resume.mdx)
+- [.resume()](./resume.mdx)
+- [.watch()](./watch.mdx)

package/.docs/raw/reference/workflows/then.mdx

@@ -0,0 +1,74 @@
+---
+title: "Reference: Workflow.then() | Building Workflows | Mastra Docs"
+description: Documentation for the `.then()` method in workflows, which creates sequential dependencies between steps.
+---
+
+# Workflow.then()
+
+The `.then()` method creates a sequential dependency between workflow steps, ensuring steps execute in a specific order.
+
+## Usage
+
+```typescript
+workflow
+  .step(stepOne)
+  .then(stepTwo)
+  .then(stepThree);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step | string",
+      description: "The step instance or step ID that should execute after the previous step completes",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining"
+    }
+  ]}
+/>
+
+## Validation
+
+When using `then`:
+- The previous step must exist in the workflow
+- Steps cannot form circular dependencies
+- Each step can only appear once in a sequential chain
+
+## Error Handling
+
+```typescript
+try {
+  workflow
+    .step(stepA)
+    .then(stepB)
+    .then(stepA) // Will throw error - circular dependency
+    .commit();
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log(error.type); // 'circular_dependency'
+    console.log(error.details);
+  }
+}
+```
+
+## Related
+
+- [step Reference](./step-class.mdx)
+- [after Reference](./after.mdx)
+- [Sequential Steps Example](../../../examples/workflows/sequential-steps.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

package/.docs/raw/reference/workflows/until.mdx

@@ -0,0 +1,165 @@
+---
+title: "Reference: Workflow.until() | Looping in Workflows | Mastra Docs"
+description: "Documentation for the `.until()` method in Mastra workflows, which repeats a step until a specified condition becomes true."
+---
+
+# Workflow.until()
+
+The `.until()` method repeats a step until a specified condition becomes true. This creates a loop that continues executing the specified step until the condition is satisfied.
+
+## Usage
+
+```typescript
+workflow
+  .step(incrementStep)
+  .until(condition, incrementStep)
+  .then(finalStep);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "condition",
+      type: "Function | ReferenceCondition",
+      description: "A function or reference condition that determines when to stop looping",
+      isOptional: false
+    },
+    {
+      name: "step",
+      type: "Step",
+      description: "The step to repeat until the condition is met",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Condition Types
+
+### Function Condition
+
+You can use a function that returns a boolean:
+
+```typescript
+workflow
+  .step(incrementStep)
+  .until(async ({ context }) => {
+    const result = context.getStepResult<{ value: number }>('increment');
+    return (result?.value ?? 0) >= 10; // Stop when value reaches or exceeds 10
+  }, incrementStep)
+  .then(finalStep);
+```
+
+### Reference Condition
+
+You can use a reference-based condition with comparison operators:
+
+```typescript
+workflow
+  .step(incrementStep)
+  .until(
+    {
+      ref: { step: incrementStep, path: 'value' },
+      query: { $gte: 10 }, // Stop when value is greater than or equal to 10
+    },
+    incrementStep
+  )
+  .then(finalStep);
+```
+
+## Comparison Operators
+
+When using reference-based conditions, you can use these comparison operators:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq`    | Equal to    | `{ $eq: 10 }` |
+| `$ne`    | Not equal to | `{ $ne: 0 }` |
+| `$gt`    | Greater than | `{ $gt: 5 }` |
+| `$gte`   | Greater than or equal to | `{ $gte: 10 }` |
+| `$lt`    | Less than | `{ $lt: 20 }` |
+| `$lte`   | Less than or equal to | `{ $lte: 15 }` |
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for chaining"
+    }
+  ]}
+/>
+
+## Example
+
+```typescript
+import { Workflow, Step } from '@mastra/core';
+import { z } from 'zod';
+
+// Create a step that increments a counter
+const incrementStep = new Step({
+  id: 'increment',
+  description: 'Increments the counter by 1',
+  outputSchema: z.object({
+    value: z.number(),
+  }),
+  execute: async ({ context }) => {
+    // Get current value from previous execution or start at 0
+    const currentValue =
+      context.getStepResult<{ value: number }>('increment')?.value ||
+      context.getStepResult<{ startValue: number }>('trigger')?.startValue ||
+      0;
+
+    // Increment the value
+    const value = currentValue + 1;
+    console.log(`Incrementing to ${value}`);
+
+    return { value };
+  },
+});
+
+// Create a final step
+const finalStep = new Step({
+  id: 'final',
+  description: 'Final step after loop completes',
+  execute: async ({ context }) => {
+    const finalValue = context.getStepResult<{ value: number }>('increment')?.value;
+    console.log(`Loop completed with final value: ${finalValue}`);
+    return { finalValue };
+  },
+});
+
+// Create the workflow
+const counterWorkflow = new Workflow({
+  name: 'counter-workflow',
+  triggerSchema: z.object({
+    startValue: z.number(),
+    targetValue: z.number(),
+  }),
+});
+
+// Configure the workflow with an until loop
+counterWorkflow
+  .step(incrementStep)
+  .until(async ({ context }) => {
+    const targetValue = context.triggerData.targetValue;
+    const currentValue = context.getStepResult<{ value: number }>('increment')?.value ?? 0;
+    return currentValue >= targetValue;
+  }, incrementStep)
+  .then(finalStep)
+  .commit();
+
+// Execute the workflow
+const run = counterWorkflow.createRun();
+const result = await run.start({ triggerData: { startValue: 0, targetValue: 5 } });
+// Will increment from 0 to 5, then stop and execute finalStep
+```
+
+## Related
+
+- [.while()](./while.mdx) - Loop while a condition is true
+- [Control Flow Guide](../../workflows/control-flow.mdx#loop-control-with-until-and-while)
+- [Workflow Class Reference](./workflow.mdx)