@mastra/mcp-docs-server 0.0.1-alpha.1

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

@@ -0,0 +1,107 @@
+---
+title: "Reference: Workflow.if() | Conditional Branching | Mastra Docs"
+description: "Documentation for the `.if()` method in Mastra workflows, which creates conditional branches based on specified conditions."
+---
+
+# Workflow.if()
+
+> Experimental
+
+The `.if()` method creates a conditional branch in the workflow, allowing steps to execute only when a specified condition is true. This enables dynamic workflow paths based on the results of previous steps.
+
+## Usage
+
+```typescript copy showLineNumbers
+workflow
+  .step(startStep)
+  .if(async ({ context }) => {
+    const value = context.getStepResult<{ value: number }>('start')?.value;
+    return value < 10; // If true, execute the "if" branch
+  })
+  .then(ifBranchStep)
+  .else()
+  .then(elseBranchStep)
+  .commit();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "condition",
+      type: "Function | ReferenceCondition",
+      description: "A function or reference condition that determines whether to execute the 'if' branch",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Condition Types
+
+### Function Condition
+
+You can use a function that returns a boolean:
+
+```typescript
+workflow
+  .step(startStep)
+  .if(async ({ context }) => {
+    const result = context.getStepResult<{ status: string }>('start');
+    return result?.status === 'success'; // Execute "if" branch when status is "success"
+  })
+  .then(successStep)
+  .else()
+  .then(failureStep);
+```
+
+### Reference Condition
+
+You can use a reference-based condition with comparison operators:
+
+```typescript
+workflow
+  .step(startStep)
+  .if({
+    ref: { step: startStep, path: 'value' },
+    query: { $lt: 10 }, // Execute "if" branch when value is less than 10
+  })
+  .then(ifBranchStep)
+  .else()
+  .then(elseBranchStep);
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining"
+    }
+  ]}
+/>
+
+## Error Handling
+
+The `if` method requires a previous step to be defined. If you try to use it without a preceding step, an error will be thrown:
+
+```typescript
+try {
+  // This will throw an error
+  workflow
+    .if(async ({ context }) => true)
+    .then(someStep)
+    .commit();
+} catch (error) {
+  console.error(error); // "Condition requires a step to be executed after"
+}
+```
+
+## Related
+
+- [else Reference](./else.mdx)
+- [then Reference](./then.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+- [Step Condition Reference](./step-condition.mdx)

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

@@ -0,0 +1,155 @@
+---
+title: "Reference: run.resume() | Running Workflows | Mastra Docs"
+description: Documentation for the `.resume()` method in workflows, which continues execution of a suspended workflow step.
+---
+
+# run.resume()
+
+The `.resume()` method continues execution of a suspended workflow step, optionally providing new context data that can be accessed by the step on the inputData property.
+
+## Usage
+
+```typescript copy showLineNumbers
+await run.resume({
+  runId: "abc-123",
+  stepId: "stepTwo",
+  context: {
+    secondValue: 100
+  }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "config",
+      type: "object",
+      description: "Configuration for resuming the workflow",
+      isOptional: false
+    }
+  ]}
+/>
+
+### config
+
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description: "Unique identifier of the workflow run to resume",
+      isOptional: false
+    },
+    {
+      name: "stepId",
+      type: "string",
+      description: "ID of the suspended step to resume",
+      isOptional: false
+    },
+    {
+      name: "context",
+      type: "Record<string, any>",
+      description: "New context data to inject into the step's inputData property",
+      isOptional: true
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "Promise<WorkflowResult>",
+      type: "object",
+      description: "Result of the resumed workflow execution"
+    }
+  ]}
+/>
+
+## Async/Await Flow
+
+When a workflow is resumed, execution continues from the point immediately after the `suspend()` call in the step's execution function. This creates a natural flow in your code:
+
+```typescript
+// Step definition with suspend point
+const reviewStep = new Step({
+  id: "review",
+  execute: async ({ context, suspend }) => {
+    // First part of execution
+    const initialAnalysis = analyzeData(context.inputData.data);
+
+    if (initialAnalysis.needsReview) {
+      // Suspend execution here
+      await suspend({ analysis: initialAnalysis });
+
+      // This code runs after resume() is called
+      // context.inputData now contains any data provided during resume
+      return {
+        reviewedData: enhanceWithFeedback(initialAnalysis, context.inputData.feedback)
+      };
+    }
+
+    return { reviewedData: initialAnalysis };
+  }
+});
+
+const { runId, resume, start } = workflow.createRun();
+
+await start({
+  inputData: {
+    data: "some data"
+  }
+});
+
+// Later, resume the workflow
+const result = await resume({
+  runId: "workflow-123",
+  stepId: "review",
+  context: {
+    // This data will be available in `context.inputData`
+    feedback: "Looks good, but improve section 3"
+  }
+});
+```
+
+### Execution Flow
+
+1. The workflow runs until it hits `await suspend()` in the `review` step
+2. The workflow state is persisted and execution pauses
+3. Later, `run.resume()` is called with new context data
+4. Execution continues from the point after `suspend()` in the `review` step
+5. The new context data (`feedback`) is available to the step on the `inputData` property
+6. The step completes and returns its result
+7. The workflow continues with subsequent steps
+
+## Error Handling
+
+The resume function may throw several types of errors:
+
+```typescript
+try {
+  await run.resume({
+    runId,
+    stepId: "stepTwo",
+    context: newData
+  });
+} catch (error) {
+  if (error.message === "No snapshot found for workflow run") {
+    // Handle missing workflow state
+  }
+  if (error.message === "Failed to parse workflow snapshot") {
+    // Handle corrupted workflow state
+  }
+}
+```
+
+## Related
+
+- [Suspend and Resume](../../workflows/suspend-and-resume.mdx)
+- [`suspend` Reference](./suspend.mdx)
+- [`watch` Reference](./watch.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+```

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

@@ -0,0 +1,84 @@
+---
+title: "Reference: start() | Running Workflows | Mastra Docs"
+description: "Documentation for the `start()` method in workflows, which begins execution of a workflow run."
+---
+
+# start()
+
+The start function begins execution of a workflow run. It processes all steps in the defined workflow order, handling parallel execution, branching logic, and step dependencies.
+
+## Usage
+
+```typescript copy showLineNumbers
+const { runId, start } = workflow.createRun();
+const result = await start({ 
+  triggerData: { inputValue: 42 } 
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "config",
+      type: "object",
+      description: "Configuration for starting the workflow run",
+      isOptional: true
+    }
+  ]}
+/>
+
+### config
+
+<PropertiesTable
+  content={[
+    {
+      name: "triggerData",
+      type: "Record<string, any>",
+      description: "Initial data that matches the workflow's triggerSchema",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "results",
+      type: "Record<string, any>",
+      description: "Combined output from all completed workflow steps"
+    },
+    {
+      name: "status",
+      type: "'completed' | 'error' | 'suspended'",
+      description: "Final status of the workflow run"
+    }
+  ]}
+/>
+
+## Error Handling
+
+The start function may throw several types of validation errors:
+
+```typescript copy showLineNumbers
+try {
+  const result = await start({ triggerData: data });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log(error.type); // 'circular_dependency' | 'no_terminal_path' | 'unreachable_step'
+    console.log(error.details);
+  }
+}
+```
+
+## Related
+
+- [Example: Creating a Workflow](../../../examples/workflows/creating-a-workflow.mdx)
+- [Example: Suspend and Resume](../../../examples/workflows/suspend-and-resume.mdx)
+- [createRun Reference](./createRun.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Step Class Reference](./step-class.mdx)
+```

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

@@ -0,0 +1,100 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+const processOrder = new Step({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string()
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string()
+  }),
+  execute: async ({ context, runId }) => {
+    return {
+      status: "processed",
+      orderId: context.orderId
+    };
+  }
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      required: true
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodSchema",
+      description: "Zod schema to validate input data before execution",
+      required: false
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodSchema",
+      description: "Zod schema to validate step output data",
+      required: false
+    },
+    {
+      name: "payload",
+      type: "Record<string, any>",
+      description: "Static data to be merged with variables",
+      required: false
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
+      description: "Async function containing step logic",
+      required: true
+    }
+  ]}
+/>
+
+### ExecuteParams
+
+<PropertiesTable
+  content={[
+    {
+      name: "context",
+      type: "StepContext",
+      description: "Access to workflow context and step results"
+    },
+    {
+      name: "runId",
+      type: "string",
+      description: "Unique identifier for current workflow run"
+    },
+    {
+      name: "suspend",
+      type: "() => Promise<void>",
+      description: "Function to suspend step execution"
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Access to Mastra instance"
+    }
+  ]}
+/>
+
+## Related
+
+- [Workflow Reference](./workflow.mdx)
+- [Step Configuration Guide](../../workflows/steps.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

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

@@ -0,0 +1,134 @@
+---
+title: "Reference: StepCondition | Building Workflows | Mastra"
+description: Documentation for the step condition class in workflows, which determines whether a step should execute based on the output of previous steps or trigger data.
+---
+
+# StepCondition
+
+Conditions determine whether a step should execute based on the output of previous steps or trigger data.
+
+## Usage
+
+There are three ways to specify conditions: function, query object, and simple path comparison.
+
+### 1. Function Condition
+```typescript copy showLineNumbers
+workflow.step(processOrder, {
+  when: async ({ context }) => {
+    const auth = context?.getStepResult<{status: string}>("auth");
+    return auth?.status === "authenticated";
+  }
+});
+```
+
+### 2. Query Object
+```typescript copy showLineNumbers
+workflow.step(processOrder, {
+  when: {
+    ref: { step: 'auth', path: 'status' },
+    query: { $eq: 'authenticated' }
+  }
+});
+```
+
+### 3. Simple Path Comparison
+```typescript copy showLineNumbers
+workflow.step(processOrder, {
+  when: {
+    "auth.status": "authenticated"
+  }
+});
+```
+
+Based on the type of condition, the workflow runner will try to match the condition to one of these types.
+
+1. Simple Path Condition (when there's a dot in the key)
+2. Base/Query Condition (when there's a 'ref' property)
+3. Function Condition (when it's an async function)
+
+## StepCondition
+
+<PropertiesTable
+  content={[
+    {
+      name: "ref",
+      type: "{ stepId: string | 'trigger'; path: string }",
+      description: "Reference to step output value. stepId can be a step ID or 'trigger' for initial data. path specifies location of value in step result",
+      isOptional: false
+    },
+    {
+      name: "query",
+      type: "Query<any>",
+      description: "MongoDB-style query using sift operators ($eq, $gt, etc)",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Query
+
+The Query object provides MongoDB-style query operators for comparing values from previous steps or trigger data. It supports basic comparison operators like `$eq`, `$gt`, `$lt` as well as array operators like `$in` and `$nin`, and can be combined with and/or operators for complex conditions.
+
+This query syntax allows for readable conditional logic for determining whether a step should execute.
+
+<PropertiesTable
+  content={[
+    {
+      name: "$eq",
+      type: "any",
+      description: "Equal to value"
+    },
+    {
+      name: "$ne",
+      type: "any",
+      description: "Not equal to value"
+    },
+    {
+      name: "$gt",
+      type: "number",
+      description: "Greater than value"
+    },
+    {
+      name: "$gte",
+      type: "number",
+      description: "Greater than or equal to value"
+    },
+    {
+      name: "$lt",
+      type: "number",
+      description: "Less than value"
+    },
+    {
+      name: "$lte",
+      type: "number",
+      description: "Less than or equal to value"
+    },
+    {
+      name: "$in",
+      type: "any[]",
+      description: "Value exists in array"
+    },
+    {
+      name: "$nin",
+      type: "any[]",
+      description: "Value does not exist in array"
+    },
+    {
+      name: "and",
+      type: "StepCondition[]",
+      description: "Array of conditions that must all be true"
+    },
+    {
+      name: "or",
+      type: "StepCondition[]",
+      description: "Array of conditions where at least one must be true"
+    }
+  ]}
+/>
+
+## Related
+
+- [Step Options Reference](./step-options.mdx)
+- [Step Function Reference](./step-function.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

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)
+```