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

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

@@ -1,158 +0,0 @@
----
-title: "Reference: run.resume() | Legacy 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<LegacyWorkflowResult>",
-      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 LegacyStep({
-  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](/docs/workflows-legacy/suspend-and-resume)
-- [`suspend` Reference](./suspend)
-- [`watch` Reference](./watch)
-- [Workflow Class Reference](./workflow)

package/.docs/raw/reference/legacyWorkflows/resumeWithEvent.mdx

@@ -1,133 +0,0 @@
----
-title: "Reference: resumeWithEvent() | Legacy Workflows | Mastra Docs"
-description: "Reference for the resumeWithEvent method that resumes suspended workflows using event data."
----
-
-# resumeWithEvent()
-
-The `resumeWithEvent()` method resumes workflow execution by providing data for a specific event that the workflow is waiting for.
-
-## Syntax
-
-```typescript
-const run = workflow.createRun();
-
-// After the workflow has started and suspended at an event step
-await run.resumeWithEvent(eventName: string, data: any): Promise<WorkflowRunResult>
-```
-
-## Parameters
-
-| Parameter | Type   | Description                                                                                             |
-| --------- | ------ | ------------------------------------------------------------------------------------------------------- |
-| eventName | string | The name of the event to trigger. Must match an event defined in the workflow's `events` configuration. |
-| data      | any    | The event data to provide. Must conform to the schema defined for that event.                           |
-
-## Return Value
-
-Returns a Promise that resolves to a `WorkflowRunResult` object, containing:
-
-- `results`: The result status and output of each step in the workflow
-- `activePaths`: A map of active workflow paths and their states
-- `value`: The current state value of the workflow
-- Other workflow execution metadata
-
-## Description
-
-The `resumeWithEvent()` method is used to resume a workflow that has been suspended at an event step created by the `afterEvent()` method. When called, this method:
-
-1. Validates the provided event data against the schema defined for that event
-2. Loads the workflow snapshot from storage
-3. Updates the context with the event data in the `resumedEvent` field
-4. Resumes execution from the event step
-5. Continues workflow execution with the subsequent steps
-
-This method is part of Mastra's event-driven workflow capabilities, allowing you to create workflows that can respond to external events or user interactions.
-
-## Usage Notes
-
-- The workflow must be in a suspended state, specifically at the event step created by `afterEvent(eventName)`
-- The event data must conform to the schema defined for that event in the workflow configuration
-- The workflow will continue execution from the point it was suspended
-- If the workflow is not suspended or is suspended at a different step, this method may throw an error
-- The event data is made available to subsequent steps via `context.inputData.resumedEvent`
-
-## Examples
-
-### Basic Usage
-
-```typescript
-// Define and start a workflow
-const workflow = mastra.legacy_getWorkflow("approval-workflow");
-const run = workflow.createRun();
-
-// Start the workflow
-await run.start({ triggerData: { requestId: "req-123" } });
-
-// Later, when the approval event occurs:
-const result = await run.resumeWithEvent("approval", {
-  approved: true,
-  approverName: "John Doe",
-  comment: "Looks good to me!",
-});
-
-console.log(result.results);
-```
-
-### With Error Handling
-
-```typescript
-try {
-  const result = await run.resumeWithEvent("paymentReceived", {
-    amount: 100.5,
-    transactionId: "tx-456",
-    paymentMethod: "credit-card",
-  });
-
-  console.log("Workflow resumed successfully:", result.results);
-} catch (error) {
-  console.error("Failed to resume workflow with event:", error);
-  // Handle error - could be invalid event data, workflow not suspended, etc.
-}
-```
-
-### Monitoring and Auto-Resuming
-
-```typescript
-// Start a workflow
-const { start, watch, resumeWithEvent } = workflow.createRun();
-
-// Watch for suspended event steps
-watch(async ({ activePaths }) => {
-  const isApprovalEventSuspended =
-    activePaths.get("__approval_event")?.status === "suspended";
-  // Check if suspended at the approval event step
-  if (isApprovalEventSuspended) {
-    console.log("Workflow waiting for approval");
-
-    // In a real scenario, you would wait for the actual event
-    // Here we're simulating with a timeout
-    setTimeout(async () => {
-      try {
-        await resumeWithEvent("approval", {
-          approved: true,
-          approverName: "Auto Approver",
-        });
-      } catch (error) {
-        console.error("Failed to auto-resume workflow:", error);
-      }
-    }, 5000); // Wait 5 seconds before auto-approving
-  }
-});
-
-// Start the workflow
-await start({ triggerData: { requestId: "auto-123" } });
-```
-
-## Related
-
-- [Event-Driven Workflows](./events)
-- [afterEvent()](./afterEvent)
-- [Suspend and Resume](/docs/workflows-legacy/suspend-and-resume)
-- [resume()](./resume)
-- [watch()](./watch)

package/.docs/raw/reference/legacyWorkflows/snapshots.mdx

@@ -1,207 +0,0 @@
----
-title: "Reference: Snapshots | Legacy Workflows | Mastra Docs"
-description: "Technical reference on snapshots in Mastra - the serialized workflow state that enables suspend and resume functionality"
----
-
-# Snapshots
-
-In Mastra, a snapshot is a serializable representation of a workflow's complete execution state at a specific point in time. Snapshots capture all the information needed to resume a workflow from exactly where it left off, including:
-
-- The current state of each step in the workflow
-- The outputs of completed steps
-- The execution path taken through the workflow
-- Any suspended steps and their metadata
-- The remaining retry attempts for each step
-- Additional contextual data needed to resume execution
-
-Snapshots are automatically created and managed by Mastra whenever a workflow is suspended, and are persisted to the configured storage system.
-
-## The Role of Snapshots in Suspend and Resume
-
-Snapshots are the key mechanism enabling Mastra's suspend and resume capabilities. When a workflow step calls `await suspend()`:
-
-1. The workflow execution is paused at that exact point
-2. The current state of the workflow is captured as a snapshot
-3. The snapshot is persisted to storage
-4. The workflow step is marked as "suspended" with a status of `'suspended'`
-5. Later, when `resume()` is called on the suspended step, the snapshot is retrieved
-6. The workflow execution resumes from exactly where it left off
-
-This mechanism provides a powerful way to implement human-in-the-loop workflows, handle rate limiting, wait for external resources, and implement complex branching workflows that may need to pause for extended periods.
-
-## Snapshot Anatomy
-
-A Mastra workflow snapshot consists of several key components:
-
-```typescript
-export interface LegacyWorkflowRunState {
-  // Core state info
-  value: Record<string, string>; // Current state machine value
-  context: {
-    // Workflow context
-    steps: Record<
-      string,
-      {
-        // Step execution results
-        status: "success" | "failed" | "suspended" | "waiting" | "skipped";
-        payload?: any; // Step-specific data
-        error?: string; // Error info if failed
-      }
-    >;
-    triggerData: Record<string, any>; // Initial trigger data
-    attempts: Record<string, number>; // Remaining retry attempts
-    inputData: Record<string, any>; // Initial input data
-  };
-
-  activePaths: Array<{
-    // Currently active execution paths
-    stepPath: string[];
-    stepId: string;
-    status: string;
-  }>;
-
-  // Metadata
-  runId: string; // Unique run identifier
-  timestamp: number; // Time snapshot was created
-
-  // For nested workflows and suspended steps
-  childStates?: Record<string, WorkflowRunState>; // Child workflow states
-  suspendedSteps?: Record<string, string>; // Mapping of suspended steps
-}
-```
-
-## How Snapshots Are Saved and Retrieved
-
-Mastra persists snapshots to the configured storage system. By default, snapshots are saved to a LibSQL database, but can be configured to use other storage providers like Upstash.
-The snapshots are stored in the `workflow_snapshots` table and identified uniquely by the `run_id` for the associated run when using libsql.
-Utilizing a persistence layer allows for the snapshots to be persisted across workflow runs, allowing for advanced human-in-the-loop functionality.
-
-Read more about [libsql storage](../storage/libsql) and [upstash storage](../storage/upstash) here.
-
-### Saving Snapshots
-
-When a workflow is suspended, Mastra automatically persists the workflow snapshot with these steps:
-
-1. The `suspend()` function in a step execution triggers the snapshot process
-2. The `WorkflowInstance.suspend()` method records the suspended machine
-3. `persistWorkflowSnapshot()` is called to save the current state
-4. The snapshot is serialized and stored in the configured database in the `workflow_snapshots` table
-5. The storage record includes the workflow name, run ID, and the serialized snapshot
-
-### Retrieving Snapshots
-
-When a workflow is resumed, Mastra retrieves the persisted snapshot with these steps:
-
-1. The `resume()` method is called with a specific step ID
-2. The snapshot is loaded from storage using `loadWorkflowSnapshot()`
-3. The snapshot is parsed and prepared for resumption
-4. The workflow execution is recreated with the snapshot state
-5. The suspended step is resumed, and execution continues
-
-## Storage Options for Snapshots
-
-Mastra provides multiple storage options for persisting snapshots.
-
-A `storage` instance is configured on the `Mastra` class, and is used to setup a snapshot persistence layer for all workflows registered on the `Mastra` instance.
-This means that storage is shared across all workflows registered with the same `Mastra` instance.
-
-### LibSQL (Default)
-
-The default storage option is LibSQL, a SQLite-compatible database:
-
-```typescript
-import { Mastra } from "@mastra/core/mastra";
-import { DefaultStorage } from "@mastra/core/storage/libsql";
-
-const mastra = new Mastra({
-  storage: new DefaultStorage({
-    config: {
-      url: "file:storage.db", // Local file-based database
-      // For production:
-      // url: process.env.DATABASE_URL,
-      // authToken: process.env.DATABASE_AUTH_TOKEN,
-    },
-  }),
-  legacy_workflows: {
-    weatherWorkflow,
-    travelWorkflow,
-  },
-});
-```
-
-### Upstash (Redis-Compatible)
-
-For serverless environments:
-
-```typescript
-import { Mastra } from "@mastra/core/mastra";
-import { UpstashStore } from "@mastra/upstash";
-
-const mastra = new Mastra({
-  storage: new UpstashStore({
-    url: process.env.UPSTASH_URL,
-    token: process.env.UPSTASH_TOKEN,
-  }),
-  workflows: {
-    weatherWorkflow,
-    travelWorkflow,
-  },
-});
-```
-
-## Best Practices for Working with Snapshots
-
-1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
-
-2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
-
-3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
-
-4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
-
-5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
-
-## Advanced Snapshot Patterns
-
-### Custom Snapshot Metadata
-
-When suspending a workflow, you can include custom metadata that can help when resuming:
-
-```typescript
-await suspend({
-  reason: "Waiting for customer approval",
-  requiredApprovers: ["manager", "finance"],
-  requestedBy: currentUser,
-  urgency: "high",
-  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
-});
-```
-
-This metadata is stored with the snapshot and available when resuming.
-
-### Conditional Resumption
-
-You can implement conditional logic based on the suspend payload when resuming:
-
-```typescript
-run.watch(async ({ activePaths }) => {
-  const isApprovalStepSuspended =
-    activePaths.get("approval")?.status === "suspended";
-  if (isApprovalStepSuspended) {
-    const payload = activePaths.get("approval")?.suspendPayload;
-    if (payload.urgency === "high" && currentUser.role === "manager") {
-      await resume({
-        stepId: "approval",
-        context: { approved: true, approver: currentUser.id },
-      });
-    }
-  }
-});
-```
-
-## Related
-
-- [Suspend Function Reference](./suspend)
-- [Resume Function Reference](./resume)
-- [Watch Function Reference](./watch)
-- [Suspend and Resume Guide](/docs/workflows-legacy/suspend-and-resume)

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

@@ -1,87 +0,0 @@
----
-title: "Reference: start() | Legacy 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_legacy/creating-a-workflow)
-- [Example: Suspend and Resume](/examples/workflows_legacy/suspend-and-resume)
-- [createRun Reference](./createRun)
-- [Workflow Class Reference](./workflow)
-- [Step Class Reference](./step-class)
-
-```
-
-```

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

@@ -1,100 +0,0 @@
----
-title: "Reference: Step | Legacy 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 LegacyStep({
-  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)
-- [Step Configuration Guide](/docs/workflows-legacy/steps)
-- [Control Flow Guide](/docs/workflows-legacy/control-flow)