@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.0

package/.docs/raw/workflows-legacy/nested-workflows.mdx

@@ -1,360 +0,0 @@
----
-title: "Nested Workflows (Legacy) | Workflows (Legacy) | Mastra Docs"
-sidebar_position: 4
-sidebar_label: "Nested Workflows"
----
-
-# Nested Workflows (Legacy)
-
-Mastra allows you to use workflows as steps within other workflows, enabling you to create modular and reusable workflow components. This feature helps in organizing complex workflows into smaller, manageable pieces and promotes code reuse.
-
-It is also visually easier to understand the flow of a workflow when you can see the nested workflows as steps in the parent workflow.
-
-## Basic Usage
-
-You can use a workflow as a step directly in another workflow using the `step()` method:
-
-```typescript
-import { LegacyStep, LegacyWorkflow } from "@mastra/core/workflows/legacy";
-
-// Create a nested workflow
-const nestedWorkflow = new LegacyWorkflow({ name: "nested-workflow" })
-  .step(stepA)
-  .then(stepB)
-  .commit();
-
-// Use the nested workflow in a parent workflow
-const parentWorkflow = new LegacyWorkflow({ name: "parent-workflow" })
-  .step(nestedWorkflow, {
-    variables: {
-      city: {
-        step: "trigger",
-        path: "myTriggerInput",
-      },
-    },
-  })
-  .then(stepC)
-  .commit();
-```
-
-When a workflow is used as a step:
-
-- It is automatically converted to a step using the workflow's name as the step ID
-- The workflow's results are available in the parent workflow's context
-- The nested workflow's steps are executed in their defined order
-
-## Accessing Results
-
-Results from a nested workflow are available in the parent workflow's context under the nested workflow's name. The results include all step outputs from the nested workflow:
-
-```typescript
-const { results } = await parentWorkflow.start();
-// Access nested workflow results
-const nestedWorkflowResult = results["nested-workflow"];
-if (nestedWorkflowResult.status === "success") {
-  const nestedResults = nestedWorkflowResult.output.results;
-}
-```
-
-## Control Flow with Nested Workflows
-
-Nested workflows support all the control flow features available to regular steps:
-
-### Parallel Execution
-
-Multiple nested workflows can be executed in parallel:
-
-```typescript
-parentWorkflow
-  .step(nestedWorkflowA)
-  .step(nestedWorkflowB)
-  .after([nestedWorkflowA, nestedWorkflowB])
-  .step(finalStep);
-```
-
-Or using `step()` with an array of workflows:
-
-```typescript
-parentWorkflow.step([nestedWorkflowA, nestedWorkflowB]).then(finalStep);
-```
-
-In this case, `then()` will implicitly wait for all the workflows to finish before executing the final step.
-
-### If-Else Branching
-
-Nested workflows can be used in if-else branches using the new syntax that accepts both branches as arguments:
-
-```typescript
-// Create nested workflows for different paths
-const workflowA = new LegacyWorkflow({ name: "workflow-a" })
-  .step(stepA1)
-  .then(stepA2)
-  .commit();
-
-const workflowB = new LegacyWorkflow({ name: "workflow-b" })
-  .step(stepB1)
-  .then(stepB2)
-  .commit();
-
-// Use the new if-else syntax with nested workflows
-parentWorkflow
-  .step(initialStep)
-  .if(
-    async ({ context }) => {
-      // Your condition here
-      return someCondition;
-    },
-    workflowA, // if branch
-    workflowB, // else branch
-  )
-  .then(finalStep)
-  .commit();
-```
-
-The new syntax is more concise and clearer when working with nested workflows. When the condition is:
-
-- `true`: The first workflow (if branch) is executed
-- `false`: The second workflow (else branch) is executed
-
-The skipped workflow will have a status of `skipped` in the results:
-
-The `.then(finalStep)` call following the if-else block will merge the if and else branches back into a single execution path.
-
-### Looping
-
-Nested workflows can use `.until()` and `.while()` loops same as any other step. One interesting new pattern is to pass a workflow directly as the loop-back argument to keep executing that nested workflow until something is true about its results:
-
-```typescript
-parentWorkflow
-  .step(firstStep)
-  .while(
-    ({ context }) =>
-      context.getStepResult("nested-workflow").output.results.someField ===
-      "someValue",
-    nestedWorkflow,
-  )
-  .step(finalStep)
-  .commit();
-```
-
-## Watching Nested Workflows
-
-You can watch the state changes of nested workflows using the `watch` method on the parent workflow. This is useful for monitoring the progress and state transitions of complex workflows:
-
-```typescript
-const parentWorkflow = new LegacyWorkflow({ name: "parent-workflow" })
-  .step([nestedWorkflowA, nestedWorkflowB])
-  .then(finalStep)
-  .commit();
-
-const run = parentWorkflow.createRun();
-const unwatch = parentWorkflow.watch((state) => {
-  console.log("Current state:", state.value);
-  // Access nested workflow states in state.context
-});
-
-await run.start();
-unwatch(); // Stop watching when done
-```
-
-## Suspending and Resuming
-
-Nested workflows support suspension and resumption, allowing you to pause and continue workflow execution at specific points. You can suspend either the entire nested workflow or specific steps within it:
-
-```typescript
-// Define a step that may need to suspend
-const suspendableStep = new LegacyStep({
-  id: "other",
-  description: "Step that may need to suspend",
-  execute: async ({ context, suspend }) => {
-    if (!wasSuspended) {
-      wasSuspended = true;
-      await suspend();
-    }
-    return { other: 26 };
-  },
-});
-
-// Create a nested workflow with suspendable steps
-const nestedWorkflow = new LegacyWorkflow({ name: "nested-workflow-a" })
-  .step(startStep)
-  .then(suspendableStep)
-  .then(finalStep)
-  .commit();
-
-// Use in parent workflow
-const parentWorkflow = new LegacyWorkflow({ name: "parent-workflow" })
-  .step(beginStep)
-  .then(nestedWorkflow)
-  .then(lastStep)
-  .commit();
-
-// Start the workflow
-const run = parentWorkflow.createRun();
-const { runId, results } = await run.start({ triggerData: { startValue: 1 } });
-
-// Check if a specific step in the nested workflow is suspended
-if (results["nested-workflow-a"].output.results.other.status === "suspended") {
-  // Resume the specific suspended step using dot notation
-  const resumedResults = await run.resume({
-    stepId: "nested-workflow-a.other",
-    context: { startValue: 1 },
-  });
-
-  // The resumed results will contain the completed nested workflow
-  expect(resumedResults.results["nested-workflow-a"].output.results).toEqual({
-    start: { output: { newValue: 1 }, status: "success" },
-    other: { output: { other: 26 }, status: "success" },
-    final: { output: { finalValue: 27 }, status: "success" },
-  });
-}
-```
-
-When resuming a nested workflow:
-
-- Use the nested workflow's name as the `stepId` when calling `resume()` to resume the entire workflow
-- Use dot notation (`nested-workflow.step-name`) to resume a specific step within the nested workflow
-- The nested workflow will continue from the suspended step with the provided context
-- You can check the status of specific steps in the nested workflow's results using `results["nested-workflow"].output.results`
-
-## Result Schemas and Mapping
-
-Nested workflows can define their result schema and mapping, which helps in type safety and data transformation. This is particularly useful when you want to ensure the nested workflow's output matches a specific structure or when you need to transform the results before they're used in the parent workflow.
-
-```typescript
-// Create a nested workflow with result schema and mapping
-const nestedWorkflow = new LegacyWorkflow({
-  name: "nested-workflow",
-  result: {
-    schema: z.object({
-      total: z.number(),
-      items: z.array(
-        z.object({
-          id: z.string(),
-          value: z.number(),
-        }),
-      ),
-    }),
-    mapping: {
-      // Map values from step results using variables syntax
-      total: { step: "step-a", path: "count" },
-      items: { step: "step-b", path: "items" },
-    },
-  },
-})
-  .step(stepA)
-  .then(stepB)
-  .commit();
-
-// Use in parent workflow with type-safe results
-const parentWorkflow = new LegacyWorkflow({ name: "parent-workflow" })
-  .step(nestedWorkflow)
-  .then(async ({ context }) => {
-    const result = context.getStepResult("nested-workflow");
-    // TypeScript knows the structure of result
-    console.log(result.total); // number
-    console.log(result.items); // Array<{ id: string, value: number }>
-    return { success: true };
-  })
-  .commit();
-```
-
-## Best Practices
-
-1. **Modularity**: Use nested workflows to encapsulate related steps and create reusable workflow components.
-2. **Naming**: Give nested workflows descriptive names as they will be used as step IDs in the parent workflow.
-3. **Error Handling**: Nested workflows propagate their errors to the parent workflow, so handle errors appropriately.
-4. **State Management**: Each nested workflow maintains its own state but can access the parent workflow's context.
-5. **Suspension**: When using suspension in nested workflows, consider the entire workflow's state and handle resumption appropriately.
-
-## Example
-
-Here's a complete example showing various features of nested workflows:
-
-```typescript
-const workflowA = new LegacyWorkflow({
-  name: "workflow-a",
-  result: {
-    schema: z.object({
-      activities: z.string(),
-    }),
-    mapping: {
-      activities: {
-        step: planActivities,
-        path: "activities",
-      },
-    },
-  },
-})
-  .step(fetchWeather)
-  .then(planActivities)
-  .commit();
-
-const workflowB = new LegacyWorkflow({
-  name: "workflow-b",
-  result: {
-    schema: z.object({
-      activities: z.string(),
-    }),
-    mapping: {
-      activities: {
-        step: planActivities,
-        path: "activities",
-      },
-    },
-  },
-})
-  .step(fetchWeather)
-  .then(planActivities)
-  .commit();
-
-const weatherWorkflow = new LegacyWorkflow({
-  name: "weather-workflow",
-  triggerSchema: z.object({
-    cityA: z.string().describe("The city to get the weather for"),
-    cityB: z.string().describe("The city to get the weather for"),
-  }),
-  result: {
-    schema: z.object({
-      activitiesA: z.string(),
-      activitiesB: z.string(),
-    }),
-    mapping: {
-      activitiesA: {
-        step: workflowA,
-        path: "result.activities",
-      },
-      activitiesB: {
-        step: workflowB,
-        path: "result.activities",
-      },
-    },
-  },
-})
-  .step(workflowA, {
-    variables: {
-      city: {
-        step: "trigger",
-        path: "cityA",
-      },
-    },
-  })
-  .step(workflowB, {
-    variables: {
-      city: {
-        step: "trigger",
-        path: "cityB",
-      },
-    },
-  });
-
-weatherWorkflow.commit();
-```
-
-In this example:
-
-1. We define schemas for type safety across all workflows
-2. Each step has proper input and output schemas
-3. The nested workflows have their own trigger schemas and result mappings
-4. Data is passed through using variables syntax in the `.step()` calls
-5. The main workflow combines data from both nested workflows

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

@@ -1,182 +0,0 @@
----
-title: "Handling Complex LLM Operations with Workflows (Legacy) | Workflows (Legacy) | Mastra Docs"
-sidebar_position: 1
-sidebar_label: "Overview"
-description: "Workflows in Mastra help you orchestrate complex sequences of operations with features like branching, parallel execution, resource suspension, and more."
----
-
-# Handling Complex LLM Operations with Workflows (Legacy)
-
-All the legacy workflow documentation is available on the links below.
-
-- [Steps](/docs/workflows-legacy/steps)
-- [Control Flow](/docs/workflows-legacy/control-flow)
-- [Variables](/docs/workflows-legacy/variables)
-- [Suspend & Resume](/docs/workflows-legacy/suspend-and-resume)
-- [Dynamic Workflows](/docs/workflows-legacy/dynamic-workflows)
-- [Error Handling](/docs/workflows-legacy/error-handling)
-- [Nested Workflows](/docs/workflows-legacy/nested-workflows)
-- [Runtime/Dynamic Variables](/docs/workflows-legacy/runtime-variables)
-
-Workflows in Mastra help you orchestrate complex sequences of operations with features like branching, parallel execution, resource suspension, and more.
-
-## When to use workflows
-
-Most AI applications need more than a single call to a language model. You may want to run multiple steps, conditionally skip certain paths, or even pause execution altogether until you receive user input. Sometimes your agent tool calling is not accurate enough.
-
-Mastra's workflow system provides:
-
-- A standardized way to define steps and link them together.
-- Support for both simple (linear) and advanced (branching, parallel) paths.
-- Debugging and observability features to track each workflow run.
-
-## Example
-
-To create a workflow, you define one or more steps, link them, and then commit the workflow before starting it.
-
-### Breaking Down the Workflow (Legacy)
-
-Let's examine each part of the workflow creation process:
-
-#### 1. Creating the Workflow
-
-Here's how you define a workflow in Mastra. The `name` field determines the workflow's API endpoint (`/workflows/$NAME/`), while the `triggerSchema` defines the structure of the workflow's trigger data:
-
-```ts title="src/mastra/workflow/index.ts"
-import { LegacyStep, LegacyWorkflow } from "@mastra/core/workflows/legacy";
-
-const myWorkflow = new LegacyWorkflow({
-  name: "my-workflow",
-  triggerSchema: z.object({
-    inputValue: z.number(),
-  }),
-});
-```
-
-#### 2. Defining Steps
-
-Now, we'll define the workflow's steps. Each step can have its own input and output schemas. Here, `stepOne` doubles an input value, and `stepTwo` increments that result if `stepOne` was successful. (To keep things simple, we aren't making any LLM calls in this example):
-
-```ts title="src/mastra/workflow/index.ts"
-const stepOne = new LegacyStep({
-  id: "stepOne",
-  outputSchema: z.object({
-    doubledValue: z.number(),
-  }),
-  execute: async ({ context }) => {
-    const doubledValue = context.triggerData.inputValue * 2;
-    return { doubledValue };
-  },
-});
-
-const stepTwo = new LegacyStep({
-  id: "stepTwo",
-  execute: async ({ context }) => {
-    const doubledValue = context.getStepResult(stepOne)?.doubledValue;
-    if (!doubledValue) {
-      return { incrementedValue: 0 };
-    }
-    return {
-      incrementedValue: doubledValue + 1,
-    };
-  },
-});
-```
-
-#### 3. Linking Steps
-
-Now, let's create the control flow, and "commit" (finalize the workflow). In this case, `stepOne` runs first and is followed by `stepTwo`.
-
-```ts title="src/mastra/workflow/index.ts"
-myWorkflow.step(stepOne).then(stepTwo).commit();
-```
-
-### Register the Workflow
-
-Register your workflow with Mastra to enable logging and telemetry:
-
-```ts showLineNumbers title="src/mastra/index.ts"
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({
-  legacy_workflows: { myWorkflow },
-});
-```
-
-The workflow can also have the mastra instance injected into the context in the case where you need to create dynamic workflows:
-
-```ts title="src/mastra/workflow/index.ts"
-import { Mastra } from "@mastra/core";
-import { LegacyWorkflow } from "@mastra/core/workflows/legacy";
-
-const mastra = new Mastra();
-
-const myWorkflow = new LegacyWorkflow({
-  name: "my-workflow",
-  mastra,
-});
-```
-
-### Executing the Workflow
-
-Execute your workflow programmatically or via API:
-
-```ts showLineNumbers title="src/mastra/run-workflow.ts" copy
-import { mastra } from "./index";
-
-// Get the workflow
-const myWorkflow = mastra.legacy_getWorkflow("myWorkflow");
-const { runId, start } = myWorkflow.createRun();
-
-// Start the workflow execution
-await start({ triggerData: { inputValue: 45 } });
-```
-
-Or use the API (requires running `mastra dev`):
-
-// Create workflow run
-
-```bash
-curl --location 'http://localhost:4111/api/workflows/myWorkflow/start-async' \
-     --header 'Content-Type: application/json' \
-     --data '{
-       "inputValue": 45
-     }'
-```
-
-This example shows the essentials: define your workflow, add steps, commit the workflow, then execute it.
-
-## Defining Steps
-
-The basic building block of a workflow [is a step](./steps). Steps are defined using schemas for inputs and outputs, and can fetch prior step results.
-
-## Control Flow
-
-Workflows let you define a [control flow](./control-flow) to chain steps together in with parallel steps, branching paths, and more.
-
-## Workflow Variables
-
-When you need to map data between steps or create dynamic data flows, [workflow variables](./variables) provide a powerful mechanism for passing information from one step to another and accessing nested properties within step outputs.
-
-## Suspend and Resume
-
-When you need to pause execution for external data, user input, or asynchronous events, Mastra [supports suspension at any step](./suspend-and-resume), persisting the state of the workflow so you can resume it later.
-
-## Observability and Debugging
-
-Mastra workflows automatically [log the input and output of each step within a workflow run](/docs/observability/otel-tracing), allowing you to send this data to your preferred logging, telemetry, or observability tools.
-
-You can:
-
-- Track the status of each step (e.g., `success`, `error`, or `suspended`).
-- Store run-specific metadata for analysis.
-- Integrate with third-party observability platforms like Datadog or New Relic by forwarding logs.
-
-## More Resources
-
-- [Sequential Steps workflow example](/examples/workflows_legacy/sequential-steps)
-- [Parallel Steps workflow example](/examples/workflows_legacy/parallel-steps)
-- [Branching Paths workflow example](/examples/workflows_legacy/branching-paths)
-- [Workflow Variables example](/examples/workflows_legacy/workflow-variables)
-- [Cyclical Dependencies workflow example](/examples/workflows_legacy/cyclical-dependencies)
-- [Suspend and Resume workflow example](/examples/workflows_legacy/suspend-and-resume)

package/.docs/raw/workflows-legacy/runtime-variables.mdx

@@ -1,156 +0,0 @@
----
-title: "Workflow Runtime Variables (Legacy) | Workflows (Legacy) | Mastra Docs"
-sidebar_position: 6
-sidebar_label: "Runtime/Dynamic Variables"
-description: Learn how to use Mastra's dependency injection system to provide runtime configuration to workflows and steps.
----
-
-# Workflow Runtime Variables (Legacy)
-
-Mastra provides a powerful dependency injection system that enables you to configure your workflows and steps with runtime variables. This feature is essential for creating flexible and reusable workflows that can adapt their behavior based on runtime configuration.
-
-## Overview
-
-The dependency injection system allows you to:
-
-1. Pass runtime configuration variables to workflows through a type-safe runtimeContext
-2. Access these variables within step execution contexts
-3. Modify workflow behavior without changing the underlying code
-4. Share configuration across multiple steps within the same workflow
-
-## Basic Usage
-
-```typescript
-const myWorkflow = mastra.legacy_getWorkflow("myWorkflow");
-const { runId, start, resume } = myWorkflow.createRun();
-
-// Define your runtimeContext's type structure
-type WorkflowRuntimeContext = {
-  multiplier: number;
-};
-
-const runtimeContext = new RuntimeContext<WorkflowRuntimeContext>();
-runtimeContext.set("multiplier", 5);
-
-// Start the workflow execution with runtimeContext
-await start({
-  triggerData: { inputValue: 45 },
-  runtimeContext,
-});
-```
-
-## Using with REST API
-
-Here's how to dynamically set a multiplier value from an HTTP header:
-
-```typescript title="src/index.ts"
-import { Mastra } from "@mastra/core";
-import { RuntimeContext } from "@mastra/core/di";
-import { workflow as myWorkflow } from "./workflows";
-
-// Define runtimeContext type with clear, descriptive types
-type WorkflowRuntimeContext = {
-  multiplier: number;
-};
-
-export const mastra = new Mastra({
-  legacy_workflows: {
-    myWorkflow,
-  },
-  server: {
-    middleware: [
-      async (c, next) => {
-        const multiplier = c.req.header("x-multiplier");
-        const runtimeContext = c.get<WorkflowRuntimeContext>("runtimeContext");
-
-        // Parse and validate the multiplier value
-        const multiplierValue = parseInt(multiplier || "1", 10);
-        if (isNaN(multiplierValue)) {
-          throw new Error("Invalid multiplier value");
-        }
-
-        runtimeContext.set("multiplier", multiplierValue);
-
-        await next(); // Don't forget to call next()
-      },
-    ],
-  },
-});
-```
-
-## Creating Steps with Variables
-
-Steps can access runtimeContext variables and must conform to the workflow's runtimeContext type:
-
-```typescript
-import { LegacyStep } from "@mastra/core/workflows/legacy";
-import { z } from "zod";
-
-// Define step input/output types
-interface StepInput {
-  inputValue: number;
-}
-
-interface StepOutput {
-  incrementedValue: number;
-}
-
-const stepOne = new LegacyStep({
-  id: "stepOne",
-  description: "Multiply the input value by the configured multiplier",
-  execute: async ({ context, runtimeContext }) => {
-    try {
-      // Type-safe access to runtimeContext variables
-      const multiplier = runtimeContext.get("multiplier");
-      if (multiplier === undefined) {
-        throw new Error("Multiplier not configured in runtimeContext");
-      }
-
-      // Get and validate input
-      const inputValue =
-        context.getStepResult<StepInput>("trigger")?.inputValue;
-      if (inputValue === undefined) {
-        throw new Error("Input value not provided");
-      }
-
-      const result: StepOutput = {
-        incrementedValue: inputValue * multiplier,
-      };
-
-      return result;
-    } catch (error) {
-      console.error(`Error in stepOne: ${error.message}`);
-      throw error;
-    }
-  },
-});
-```
-
-## Error Handling
-
-When working with runtime variables in workflows, it's important to handle potential errors:
-
-1. **Missing Variables**: Always check if required variables exist in the runtimeContext
-2. **Type Mismatches**: Use TypeScript's type system to catch type errors at compile time
-3. **Invalid Values**: Validate variable values before using them in your steps
-
-```typescript
-// Example of defensive programming with runtimeContext variables
-const multiplier = runtimeContext.get("multiplier");
-if (multiplier === undefined) {
-  throw new Error("Multiplier not configured in runtimeContext");
-}
-
-// Type and value validation
-if (typeof multiplier !== "number" || multiplier <= 0) {
-  throw new Error(`Invalid multiplier value: ${multiplier}`);
-}
-```
-
-## Best Practices
-
-1. **Type Safety**: Always define proper types for your runtimeContext and step inputs/outputs
-2. **Validation**: Validate all inputs and runtimeContext variables before using them
-3. **Error Handling**: Implement proper error handling in your steps
-4. **Documentation**: Document the expected runtimeContext variables for each workflow
-5. **Default Values**: Provide sensible defaults when possible