@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/raw/workflows/error-handling.mdx

@@ -1,213 +0,0 @@
----
-title: "Error Handling in Workflows | Workflows | Mastra Docs"
-description: "Learn how to handle errors in Mastra workflows using step retries, conditional branching, and monitoring."
----
-
-# Error Handling
-
-Mastra provides a built-in retry mechanism for workflows or steps that fail due to transient errors. This is particularly useful for steps that interact with external services or resources that might experience temporary unavailability.
-
-## Workflow-level using `retryConfig`
-
-You can configure retries at the workflow level, which applies to all steps in the workflow:
-
-```typescript {8-11} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({...});
-
-export const testWorkflow = createWorkflow({
-  // ...
-  retryConfig: {
-    attempts: 5,
-    delay: 2000
-  }
-})
-  .then(step1)
-  .commit();
-```
-
-## Step-level using `retries`
-
-You can configure retries for individual steps using the `retries` property. This overrides the workflow-level retry configuration for that specific step:
-
-```typescript {17} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({
-  // ...
-  execute: async () => {
-    const response = await // ...
-
-    if (!response.ok) {
-      throw new Error('Error');
-    }
-
-    return {
-      value: ""
-    };
-  },
-  retries: 3
-});
-```
-
-## Conditional branching
-
-You can create alternative workflow paths based on the success or failure of previous steps using conditional logic:
-
-```typescript {15,19,33-34} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({
-  // ...
-  execute: async () => {
-    try {
-      const response = await // ...
-
-      if (!response.ok) {
-        throw new Error('error');
-      }
-
-      return {
-        status: "ok"
-      };
-    } catch (error) {
-      return {
-        status: "error"
-      };
-    }
-  }
-});
-
-const step2 = createStep({...});
-const fallback = createStep({...});
-
-export const testWorkflow = createWorkflow({
-  // ...
-})
-  .then(step1)
-  .branch([
-    [async ({ inputData: { status } }) => status === "ok", step2],
-    [async ({ inputData: { status } }) => status === "error", fallback]
-  ])
-  .commit();
-```
-
-## Check previous step results
-
-Use `getStepResult()` to inspect a previous step’s results.
-
-```typescript {10} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({...});
-
-const step2 = createStep({
-  // ...
-  execute: async ({ getStepResult }) => {
-
-    const step1Result = getStepResult(step1);
-
-    return {
-      value: ""
-    };
-  }
-});
-```
-
-## Exiting early with `bail()`
-
-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 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({...})
-  .then(step1)
-  .commit();
-```
-
-## Exiting early with `Error()`
-
-Use `throw new Error()` in a step to exit with an error.
-
-```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 () => {
-    throw new Error('error');
-  },
-  inputSchema: z.object({ value: z.string() }),
-  outputSchema: z.object({ result: z.string() }),
-});
-
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-
-## Monitor errors with `watch()`
-
-You can monitor workflows for errors using the `watch` method:
-
-```typescript {11} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "../src/mastra";
-
-const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRunAsync();
-
-run.watch((event) => {
-  const {
-    payload: { currentStep }
-  } = event;
-
-  console.log(currentStep?.payload?.status);
-});
-
-```
-
-## Monitor errors with `stream()`
-
-You can monitor workflows for errors using `stream`:
-
-```typescript {11} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "../src/mastra";
-
-const workflow = mastra.getWorkflow("testWorkflow");
-
-const run = await workflow.createRunAsync();
-
-const stream = await run.stream({
-  inputData: {
-    value: "initial data"
-  }
-});
-
-for await (const chunk of stream.stream) {
-  console.log(chunk.payload.output.stats);
-}
-
-```
-
-## Related
-
-- [Control Flow](./control-flow.mdx)
-- [Conditional Branching](./control-flow.mdx#conditional-logic-with-branch)
-- [Running Workflows](../../examples/workflows/running-workflows.mdx)

package/.docs/raw/workflows/inngest-workflow.mdx

@@ -1,359 +0,0 @@
----
-title: "Inngest Workflows | Workflows | Mastra Docs"
-description: "Inngest workflow allows you to run Mastra workflows with Inngest"
----
-
-# Inngest Workflow
-
-[Inngest](https://www.inngest.com/docs) is a developer platform for building and running background workflows, without managing infrastructure.
-
-## How Inngest Works with Mastra
-
-Inngest and Mastra integrate by aligning their workflow models: Inngest organizes logic into functions composed of steps, and Mastra workflows defined using `createWorkflow` and `createStep` map directly onto this paradigm. Each Mastra workflow becomes an Inngest function with a unique identifier, and each step within the workflow maps to an Inngest step.
-
-The `serve` function bridges the two systems by registering Mastra workflows as Inngest functions and setting up the necessary event handlers for execution and monitoring.
-
-When an event triggers a workflow, Inngest executes it step by step, memoizing each step’s result. This means if a workflow is retried or resumed, completed steps are skipped, ensuring efficient and reliable execution. Control flow primitives in Mastra, such as loops, conditionals, and nested workflows are seamlessly translated into the same Inngest’s function/step model, preserving advanced workflow features like composition, branching, and suspension.
-
-Real-time monitoring, suspend/resume, and step-level observability are enabled via Inngest’s publish-subscribe system and dashboard. As each step executes, its state and output are tracked using Mastra storage and can be resumed as needed.
-
-## Setup
-
-```sh
-npm install @mastra/inngest @mastra/core @mastra/deployer
-```
-
-## Building an Inngest Workflow
-
-This guide walks through creating a workflow with Inngest and Mastra, demonstrating a counter application that increments a value until it reaches 10.
-
-### Inngest Initialization
-
-Initialize the Inngest integration to obtain Mastra-compatible workflow helpers. The createWorkflow and createStep functions are used to create workflow and step objects that are compatible with Mastra and inngest.
-
-In development
-
-```ts showLineNumbers copy filename="src/mastra/inngest/index.ts"
-import { Inngest } from "inngest";
-import { realtimeMiddleware } from "@inngest/realtime";
-
-export const inngest = new Inngest({
-  id: "mastra",
-  baseUrl:"http://localhost:8288",
-  isDev: true,
-  middleware: [realtimeMiddleware()],
-});
-```
-
-In production
-
-```ts showLineNumbers copy filename="src/mastra/inngest/index.ts"
-import { Inngest } from "inngest";
-import { realtimeMiddleware } from "@inngest/realtime";
-
-export const inngest = new Inngest({
-  id: "mastra",
-  middleware: [realtimeMiddleware()],
-});
-```
-
-### Creating Steps
-
-Define the individual steps that will compose your workflow:
-
-```ts showLineNumbers copy filename="src/mastra/workflows/index.ts"
-import { z } from "zod";
-import { inngest } from "../inngest";
-import { init } from "@mastra/inngest";
-
-// Initialize Inngest with Mastra, pointing to your local Inngest server
-const { createWorkflow, createStep } = init(inngest);
-
-// Step: Increment the counter value
-const incrementStep = createStep({
-  id: "increment",
-  inputSchema: z.object({
-    value: z.number(),
-  }),
-  outputSchema: z.object({
-    value: z.number(),
-  }),
-  execute: async ({ inputData }) => {
-    return { value: inputData.value + 1 };
-  },
-});
-```
-
-### Creating the Workflow
-
-Compose the steps into a workflow using the `dountil` loop pattern. The createWorkflow function creates a function on inngest server that is invocable.
-
-```ts showLineNumbers copy filename="src/mastra/workflows/index.ts"
-// workflow that is registered as a function on inngest server
-const workflow = createWorkflow({
-  id: "increment-workflow",
-  inputSchema: z.object({
-    value: z.number(),
-  }),
-  outputSchema: z.object({
-    value: z.number(),
-  }),
-}).then(incrementStep);
-
-workflow.commit();
-
-export { workflow as incrementWorkflow };
-```
-
-### Configuring the Mastra Instance and Executing the Workflow
-
-Register the workflow with Mastra and configure the Inngest API endpoint:
-
-```ts showLineNumbers copy filename="src/mastra/index.ts"
-import { Mastra } from "@mastra/core/mastra";
-import { serve as inngestServe } from "@mastra/inngest";
-import { incrementWorkflow } from "./workflows";
-import { inngest } from "./inngest";
-import { PinoLogger } from "@mastra/loggers";
-
-// Configure Mastra with the workflow and Inngest API endpoint
-export const mastra = new Mastra({
-  workflows: {
-    incrementWorkflow,
-  },
-  server: {
-    // The server configuration is required to allow local docker container can connect to the mastra server
-    host: "0.0.0.0",
-    apiRoutes: [
-      // This API route is used to register the Mastra workflow (inngest function) on the inngest server
-      {
-        path: "/api/inngest",
-        method: "ALL",
-        createHandler: async ({ mastra }) => inngestServe({ mastra, inngest }),
-        // The inngestServe function integrates Mastra workflows with Inngest by:
-        // 1. Creating Inngest functions for each workflow with unique IDs (workflow.${workflowId})
-        // 2. Setting up event handlers that:
-        //    - Generate unique run IDs for each workflow execution
-        //    - Create an InngestExecutionEngine to manage step execution
-        //    - Handle workflow state persistence and real-time updates
-        // 3. Establishing a publish-subscribe system for real-time monitoring
-        //    through the workflow:${workflowId}:${runId} channel
-        //
-        // Optional: You can also pass additional Inngest functions to serve alongside workflows:
-        // createHandler: async ({ mastra }) => inngestServe({
-        //   mastra,
-        //   inngest,
-        //   functions: [customFunction1, customFunction2] // User-defined Inngest functions
-        // }),
-      },
-    ],
-  },
-  logger: new PinoLogger({
-    name: "Mastra",
-    level: "info",
-  }),
-});
-```
-
-### Running the Workflow locally
-
-> **Prerequisites:**
->
-> - Docker installed and running
-> - Mastra project set up
-> - Dependencies installed (`npm install`)
-
-1. Run `npx mastra dev` to start the Mastra server on local to serve the server on port 4111.
-2. Start the Inngest Dev Server (via Docker)
-   In a new terminal, run:
-
-```sh
-docker run --rm -p 8288:8288 \
-  inngest/inngest \
-  inngest dev -u http://host.docker.internal:4111/api/inngest
-```
-
-> **Note:** The URL after `-u` tells the Inngest dev server where to find your Mastra `/api/inngest` endpoint.
-
-3. Open the Inngest Dashboard
-
-- Visit [http://localhost:8288](http://localhost:8288) in your browser.
-- Go to the **Apps** section in the sidebar.
-- You should see your Mastra workflow registered.
-  ![Inngest Dashboard](/inngest-apps-dashboard.png)
-
-4. Invoke the Workflow
-
-- Go to the **Functions** section in the sidebar.
-- Select your Mastra workflow.
-- Click **Invoke** and use the following input:
-
-```json
-{
-  "data": {
-    "inputData": {
-      "value": 5
-    }
-  }
-}
-```
-
-![Inngest Function](/inngest-function-dashboard.png)
-
-5. **Monitor the Workflow Execution**
-
-- Go to the **Runs** tab in the sidebar.
-- Click on the latest run to see step-by-step execution progress.
-  ![Inngest Function Run](/inngest-runs-dashboard.png)
-
-### Running the Workflow in Production
-
-> **Prerequisites:**
->
-> - Vercel account and Vercel CLI installed (`npm i -g vercel`)
-> - Inngest account
-> - Vercel token (recommended: set as environment variable)
-
-1. Add Vercel Deployer to Mastra instance
-
-```ts showLineNumbers copy filename="src/mastra/index.ts"
-import { VercelDeployer } from "@mastra/deployer-vercel";
-
-export const mastra = new Mastra({
-  // ...other config
-  deployer: new VercelDeployer({
-    teamSlug: "your_team_slug",
-    projectName: "your_project_name",
-    // you can get your vercel token from the vercel dashboard by clicking on the user icon in the top right corner
-    // and then clicking on "Account Settings" and then clicking on "Tokens" on the left sidebar.
-    token: "your_vercel_token",
-  }),
-});
-```
-
-> **Note:** Set your Vercel token in your environment:
->
-> ```sh
-> export VERCEL_TOKEN=your_vercel_token
-> ```
-
-2. Build the mastra instance
-
-```sh
-npx mastra build
-```
-
-3. Deploy to Vercel
-
-```sh
-cd .mastra/output
-vercel --prod
-```
-
-> **Tip:** If you haven't already, log in to Vercel CLI with `vercel login`.
-
-4. Sync with Inngest Dashboard
-
-- Go to the [Inngest dashboard](https://app.inngest.com/env/production/apps).
-- Click **Sync new app with Vercel** and follow the instructions.
-- You should see your Mastra workflow registered as an app.
-  ![Inngest Dashboard](/inngest-apps-dashboard-prod.png)
-
-5. Invoke the Workflow
-
-- In the **Functions** section, select `workflow.increment-workflow`.
-- Click **All actions** (top right) > **Invoke**.
-- Provide the following input:
-
-```json
-{
-  "data": {
-    "inputData": {
-      "value": 5
-    }
-  }
-}
-```
-
-![Inngest Function Run](/inngest-function-dashboard-prod.png)
-
-6.  Monitor Execution
-
-- Go to the **Runs** tab.
-- Click the latest run to see step-by-step execution progress.
-  ![Inngest Function Run](/inngest-runs-dashboard-prod.png)
-
-## Advanced Usage: Adding Custom Inngest Functions
-
-You can serve additional Inngest functions alongside your Mastra workflows by using the optional `functions` parameter in `inngestServe`.
-
-### Creating Custom Functions
-
-First, create your custom Inngest functions:
-
-```ts showLineNumbers copy filename="src/inngest/custom-functions.ts"
-import { inngest } from "./inngest";
-
-// Define custom Inngest functions
-export const customEmailFunction = inngest.createFunction(
-  { id: 'send-welcome-email' },
-  { event: 'user/registered' },
-  async ({ event }) => {
-    // Custom email logic here
-    console.log(`Sending welcome email to ${event.data.email}`);
-    return { status: 'email_sent' };
-  }
-);
-
-export const customWebhookFunction = inngest.createFunction(
-  { id: 'process-webhook' },
-  { event: 'webhook/received' },
-  async ({ event }) => {
-    // Custom webhook processing
-    console.log(`Processing webhook: ${event.data.type}`);
-    return { processed: true };
-  }
-);
-```
-
-### Serving Custom Functions with Workflows
-
-Update your Mastra configuration to include the custom functions:
-
-```ts showLineNumbers copy filename="src/mastra/index.ts"
-import { Mastra } from "@mastra/core/mastra";
-import { serve as inngestServe } from "@mastra/inngest";
-import { incrementWorkflow } from "./workflows";
-import { inngest } from "./inngest";
-import { customEmailFunction, customWebhookFunction } from "./inngest/custom-functions";
-
-export const mastra = new Mastra({
-  workflows: {
-    incrementWorkflow,
-  },
-  server: {
-    host: "0.0.0.0",
-    apiRoutes: [
-      {
-        path: "/api/inngest",
-        method: "ALL",
-        createHandler: async ({ mastra }) => inngestServe({
-          mastra,
-          inngest,
-          functions: [customEmailFunction, customWebhookFunction] // Add your custom functions
-        }),
-      },
-    ],
-  },
-});
-```
-
-### Function Registration
-
-When you include custom functions:
-
-1. **Mastra workflows** are automatically converted to Inngest functions with IDs like `workflow.${workflowId}`
-2. **Custom functions** retain their specified IDs (e.g., `send-welcome-email`, `process-webhook`)
-3. **All functions** are served together on the same `/api/inngest` endpoint
-
-This allows you to combine Mastra's workflow orchestration with your existing Inngest functions seamlessly.

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

@@ -1,107 +0,0 @@
----
-title: "Input Data Mapping with Workflow | Mastra Docs"
-description: "Learn how to use workflow input mapping to create more dynamic data flows in your Mastra workflows."
----
-
-# Input Data Mapping
-
-Input data mapping allows explicit mapping of values for the inputs of the next step. These values can come from a number of sources:
-
-- The outputs of a previous step
-- The runtime context
-- A constant value
-- The initial input of the workflow
-
-## 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.
-
-![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({...})
-  .then(step1)
-  .map(async ({ inputData }) => {
-    const { value } = inputData;
-    return {
-      output: `new ${value}`
-    };
-  })
-  .then(step2)
-  .commit();
-```
-
-## Using `inputData`
-
-Use `inputData` to access the full output of the previous step:
-
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-  .then(step1)
-  .map(({ inputData }) => {
-    console.log(inputData);
-  })
-```
-
-## Using `getStepResult()`
-
-Use `getStepResult` to access the full output of a specific step by referencing the step's instance:
-
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-  .then(step1)
-  .map(async ({ getStepResult }) => {
-    console.log(getStepResult(step1));
-  })
-```
-
-## Using `getInitData()`
-
-Use `getInitData` to access the initial input data provided to the workflow:
-
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-  .then(step1)
-  .map(async ({ getInitData }) => {
-      console.log(getInitData());
-  })
-```
-
-## Using `mapVariable()`
-
-To use `mapVariable` import the necessary function from the workflows module:
-
-```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-6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-  .then(step1)
-  .map({
-    details: mapVariable({
-      step: step,
-      path: "value"
-    })
-  })
-```
-
-### Renaming workflows with `mapVariable()`
-
-You can rename workflow outputs by using **referential composition**. This involves passing the workflow instance as the `initData`.
-
-```typescript {6-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-export const testWorkflow = createWorkflow({...});
-
-testWorkflow
-  .then(step1)
-  .map({
-    details: mapVariable({
-      initData: testWorkflow,
-      path: "value"
-    })
-  })
-```