@mastra/mcp-docs-server 0.13.30 → 0.13.31

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

@@ -3,360 +3,268 @@ title: "Handling Complex LLM Operations | Workflows | Mastra"
 description: "Workflows in Mastra help you orchestrate complex sequences of tasks with features like branching, parallel execution, resource suspension, and more."
 ---
 
-import { Steps } from "nextra/components";
+import { Steps, Callout, Tabs } from "nextra/components";
 
 # Workflows overview
 
-Workflows allow you to define and manage complex sequences of tasks by connecting them with clear, structured processes. Unlike a single agent, which operates independently, workflows enable you to orchestrate multiple steps with specific logic, tools, and external services. This approach provides more control and predictability, ensuring consistent results by allowing you to determine what tasks are performed and when they are completed.
+Workflows let you define complex sequences of tasks using clear, structured steps rather than relying on the reasoning of a single agent. They give you full control over how tasks are broken down, how data moves between them, and what gets executed when.
 
 ![Workflows overview](/image/workflows/workflows-overview.jpg)
 
-## When to use a workflow
+## When to use workflows
 
-For example, you might want to perform a sequence of tasks:
+Use workflows for tasks that are clearly defined upfront and involve multiple steps with a specific execution order. They give you fine-grained control over how data flows and transforms between steps, and which primitives are called at each stage.
 
-1. Handle a user question like “Can I return my last order?”
-2. Fetch user-specific data from a database using their `user_id`.
-3. Check return eligibility via an external API or business logic.
-4. Make a conditional decision (e.g. approve, deny, escalate) based on the data.
-5. Generate a tailored response based on the outcome.
 
-Each of these tasks is created as a **step** in a workflow, giving you fine-grained control over data flow, execution order, and side effects.
 
 > **📹 Watch**:  → An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
-## Building workflows
+## Core principles
 
-You create workflows by:
+Mastra workflows operate using these principles:
 
 - Defining **steps** with `createStep`, specifying input/output schemas and business logic.
 - Composing **steps** with `createWorkflow` to define the execution flow.
 - Running **workflows** to execute the entire sequence, with built-in support for suspension, resumption, and streaming results.
 
-This structure provides full type safety and runtime validation, ensuring data integrity across the entire workflow.
+## Creating a workflow step
 
-### Visual testing
+Steps are the building blocks of workflows. Create a step using `createStep()` with `inputSchema` and `outputSchema` to define the data it accepts and returns.
 
-Use the [Playground](../server-db/local-dev-playground.mdx#workflows) to visualize workflow execution in real time. It shows which steps are running, completed, or suspended.
+```typescript {6,9,14} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createStep } from "@mastra/core/workflows";
 
-
-## Getting started
-
-To use workflows, install the required dependencies:
-
-```bash
-npm install @mastra/core
-```
-
-Import the necessary functions from the `workflows` subpath:
-
-```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-```
-
-### Create step
-
-Steps are the building blocks of workflows. Create a step using `createStep`:
-
-```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const step1 = createStep({...});
-```
-
-> See [createStep](../../reference/workflows/step.mdx) for more information.
-
-### Create workflow
-
-Create a workflow using `createWorkflow` and complete it with `.commit()`.
-
-```typescript {6,17} 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({
-  id: "test-workflow",
-  description: 'Test workflow',
+const step1 = createStep({
+  id: "step-1",
   inputSchema: z.object({
-    input: z.string()
+    message: z.string()
   }),
   outputSchema: z.object({
-    output: z.string()
+    formatted: z.string()
   }),
-  options: {
-    // enables runtime validation of inputs and applies zod default values.
-    validateInputs: true, 
+  execute: async ({ inputData }) => {
+    const { message } = inputData;
+    return {
+      formatted: message.toUpperCase()
+    };
   }
-})
-  .then(step1)
-  .commit();
+});
 ```
 
-> See [workflow](../../reference/workflows/workflow.mdx) for more information.
+> See the [Step Class](../../reference/workflows/step.mdx) for a full list of configuration options.
 
-#### Composing steps
+## Creating a workflow
 
-Workflow steps can be composed and executed sequentially using `.then()`.
+Create a workflow using `createWorkflow()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. Add steps using `.then()` and complete the workflow with `.commit()`.
 
-```typescript {17,18} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {9,12,15,16} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({...});
-const step2 = createStep({...});
 
 export const testWorkflow = createWorkflow({
   id: "test-workflow",
-  description: 'Test workflow',
   inputSchema: z.object({
-    input: z.string()
+    message: z.string()
   }),
   outputSchema: z.object({
     output: z.string()
   })
 })
   .then(step1)
-  .then(step2)
   .commit();
+
 ```
 
-> Steps can be composed using a number of different methods. See [Control Flow](./control-flow.mdx)  for more information.
+> See the [Workflow Class](../../reference/workflows/workflow.mdx) for a full list of configuration options.
 
-#### Cloning steps
+### Understanding control flow
 
-Workflow steps can be cloned using `cloneStep()`, and used with any workflow method.
+Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured.
 
-```typescript {5,19} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep, cloneStep } from "@mastra/core/workflows";
-import { z } from "zod";
+> See [Control Flow](./control-flow.mdx) for more information.
 
-const step1 = createStep({...});
-const clonedStep = cloneStep(step1, { id: "cloned-step" });
-const step2 = createStep({...});
+#### Composing steps
+
+When using `.then()`, steps run sequentially. The `inputSchema` of each step must match the `outputSchema` of the step before it. The final step’s `outputSchema` doesn’t need to match the workflow’s `outputSchema`, which can be defined independently.
+
+```typescript {4,7,14,17,24,27} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const step1 = createStep({
+  //...
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    formatted: z.string()
+  })
+});
+
+const step2 = createStep({
+  // ...
+  inputSchema: z.object({
+    formatted: z.string()
+  }),
+  outputSchema: z.object({
+    emphasized: z.string()
+  })
+});
 
 export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
+  // ...
   inputSchema: z.object({
-    input: z.string()
+    message: z.string()
   }),
   outputSchema: z.object({
     output: z.string()
   })
 })
   .then(step1)
-  .then(clonedStep)
   .then(step2)
   .commit();
 ```
 
-## Register workflow
+### Registering a workflow
 
-Register a workflow using `workflows` in the main Mastra instance:
+Register your workflow in the Mastra instance to make it available throughout your application. Once registered, it can be called from agents or tools and has access to shared resources such as logging and observability features:
 
-```typescript {8} filename="src/mastra/index.ts" showLineNumbers copy
+```typescript {6} filename="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
-import { PinoLogger } from "@mastra/loggers";
-import { LibSQLStore } from "@mastra/libsql";
-
 import { testWorkflow } from "./workflows/test-workflow";
 
 export const mastra = new Mastra({
+  // ...
   workflows: { testWorkflow },
-  storage: new LibSQLStore({
-    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
-    url: ":memory:"
-  }),
-  logger: new PinoLogger({
-    name: "Mastra",
-    level: "info"
-  })
 });
 ```
 
-## Using `RuntimeContext`
-
-Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
-
-```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers
-export type UserTier = {
-  "user-tier": "enterprise" | "pro";
-};
-
-const stepOne = createStep({
-  // ...
-  execute: async ({ runtimeContext }) => {
-    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+## Referencing a workflow
 
-    const maxResults = userTier === "enterprise"
-      ? 1000
-      : 50;
+You can run workflows from agents, tools, the Mastra Client, or the command line. Get a reference by calling `.getWorkflow()` on your `mastra` or `mastraClient` instance, depending on your setup:
 
-    return { maxResults };
-  }
-});
+```typescript showLineNumbers copy
+const testWorkflow = mastra.getWorkflow("testWorkflow");
 ```
+<Callout type="info">
+  <p>
+    `mastra.getWorkflow()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
+  </p>
+</Callout>
 
-## Testing workflows locally
-There are two ways to run and test workflows.
-
-<Steps>
-
-### Mastra Playground
-
-With the Mastra Dev Server running you can run the workflow from the Mastra Playground by visiting [http://localhost:4111/workflows](http://localhost:4111/workflows) in your browser.
-
-> For more information, see the [Local Dev Playground](../server-db/local-dev-playground.mdx) documentation.
+> See [Running Workflows](../../examples/workflows/running-workflows.mdx) for more information.
 
-### Command line
+## Running workflows
 
-Create a workflow run instance using `createRunAsync` and `start`:
+Workflows can be run in two modes: start waits for all steps to complete before returning, and stream emits events during execution. Choose the approach that fits your use case: start when you only need the final result, and stream when you want to monitor progress or trigger actions as steps complete.
 
-```typescript {3,5} filename="src/test-workflow.ts" showLineNumbers copy
-import "dotenv/config";
+<Tabs items={["Start", "Stream"]}>
+  <Tabs.Tab>
+Create a workflow run instance using `createRunAsync()`, then call `.start()` with `inputData` matching the workflow's `inputSchema`. The workflow executes all steps and returns the final result.
 
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
+```typescript showLineNumbers copy
+const run = await testWorkflow.createRunAsync();
 
 const result = await run.start({
   inputData: {
-    city: "London"
+    message: "Hello world"
   }
 });
 
 console.log(result);
-
-if (result.status === 'success') {
-  console.log(result.result.output);
-}
 ```
-> see [createRunAsync](../../reference/workflows/run.mdx) and [start](../../reference/workflows/run-methods/start.mdx) for more information.
-
-To trigger this workflow, run the following:
+  </Tabs.Tab>
+  <Tabs.Tab>
+Create a workflow run instance using `.createRunAsync()`, then call `.stream()` with `inputData` matching the workflow's `inputSchema`. The workflow emits events as each step executes, which you can iterate over to track progress.
 
-```bash copy
-npx tsx src/test-workflow.ts
-```
+```typescript showLineNumbers copy
+const run = await testWorkflow.createRunAsync();
 
-</Steps>
+const result = await run.stream({
+  inputData: {
+    message: "Hello world"
+  }
+});
 
-### Run workflow results
+for await (const chunk of result.stream) {
+  console.log(chunk);
+}
+```
+  </Tabs.Tab>
+</Tabs>
 
-The result of running a workflow using either `start()` or `resume()` will look like one of the following, depending on the outcome.
+## Workflow output
 
-#### Status success
+The workflow output includes the full execution lifecycle, showing the input and output for each step. It also includes the status of each step, the overall workflow status, and the final result. This gives you clear insight into how data moved through the workflow, what each step produced, and how the workflow completed.
 
 ```json
 {
   "status": "success",
   "steps": {
-    // ...
+    "input": {
+      "message": "Hello world"
+    },
     "step-1": {
-      // ...
+      "payload": {
+        "message": "Hello world"
+      },
       "status": "success",
+      "output": {
+        "formatted": "HELLO WORLD"
+      },
+    },
+    "step-2": {
+      "payload": {
+        "formatted": "HELLO WORLD"
+      },
+      "status": "success",
+      "output": {
+        "emphasized": "HELLO WORLD!!!"
+      },
     }
   },
+  "input": {
+    "message": "Hello world"
+  },
   "result": {
-    "output": "London + step-1"
+    "emphasized": "HELLO WORLD!!!"
   }
 }
 ```
 
-- **status**: Shows the final state of the workflow execution, either: `success`, `suspended`, or `error`
-- **steps**: Lists each step in the workflow, including inputs and outputs
-- **status**: Shows the outcome of each individual step
-- **result**: Includes the final output of the workflow, typed according to the `outputSchema`
-
-
-#### Status suspended
-
-```json
-{
-  "status": "suspended",
-  "steps": {
-    // ...
-    "step-1": {
-      // ...
-      "status": "suspended",
-    }
-  },
-  "suspended": [
-    [
-      "step-1"
-    ]
-  ]
-}
-```
-
-- **suspended**: An optional array listing any steps currently awaiting input before continuing
-
-#### Status failed
-
-```json
-{
-  "status": "failed",
-  "steps": {
-    // ...
-    "step-1": {
-      // ...
-      "status": "failed",
-      "error": "Test error",
-    }
-  },
-  "error": "Test error"
-}
-```
-- **error**: An optional field that includes the error message if the workflow fails
+## Using `RuntimeContext`
 
-## Stream workflow
+Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
-Similar to the run method shown above, workflows can also be streamed:
+```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
 
-```typescript {5} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
+const step1 = createStep({
+  // ...
+  execute: async ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
 
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
+    const maxResults = userTier === "enterprise"
+      ? 1000
+      : 50;
 
-const result = await run.stream({
-  inputData: {
-    city: "London"
+    return { maxResults };
   }
 });
-
-for await (const chunk of result.stream) {
-  console.log(chunk);
-}
 ```
 
-> See [stream](../../reference/workflows/run-methods/stream.mdx) for more information.
-
-## Watch Workflow
-
-A workflow can also be watched, allowing you to inspect each event that is emitted.
+> See [Runtime Context](../server-db/runtime-context.mdx) for more information.
 
-```typescript {5} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
+## Testing with Mastra Playground
 
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
+Use the Mastra [Playground](../server-db/local-dev-playground.mdx) to easily run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
 
-run.watch((event) => {
-  console.log(event);
-});
-
-const result = await run.start({
-  inputData: {
-    city: "London"
-  }
-});
-```
-
-> See [watch](../../reference/workflows/run-methods/watch.mdx) for more information.
 
 ## Related
 
-- The [Workflow Guide](../../guides/guide/ai-recruiter.mdx) in the Guides section is a tutorial that covers the main concepts.
+For a closer look at workflows, see our [Workflow Guide](../../guides/guide/ai-recruiter.mdx), which walks through the core concepts with a practical example.
+
 - [Parallel Steps workflow example](../../examples/workflows/parallel-steps.mdx)
 - [Conditional Branching workflow example](../../examples/workflows/conditional-branching.mdx)
 - [Inngest workflow example](../../examples/workflows/inngest-workflow.mdx)

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 0.13.31
+
+### Patch Changes
+
+- Updated dependencies [[`ca85c93`](https://github.com/mastra-ai/mastra/commit/ca85c932b232e6ad820c811ec176d98e68c59b0a), [`a1d40f8`](https://github.com/mastra-ai/mastra/commit/a1d40f88d4ce42c4508774ad22e38ac582157af2), [`01c4a25`](https://github.com/mastra-ai/mastra/commit/01c4a2506c514d5e861c004d3d2fb3791c6391f3), [`cce8aad`](https://github.com/mastra-ai/mastra/commit/cce8aad878a0dd98e5647680f3765caba0b1701c)]:
+  - @mastra/core@0.21.1
+
+## 0.13.31-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`ca85c93`](https://github.com/mastra-ai/mastra/commit/ca85c932b232e6ad820c811ec176d98e68c59b0a), [`a1d40f8`](https://github.com/mastra-ai/mastra/commit/a1d40f88d4ce42c4508774ad22e38ac582157af2), [`01c4a25`](https://github.com/mastra-ai/mastra/commit/01c4a2506c514d5e861c004d3d2fb3791c6391f3), [`cce8aad`](https://github.com/mastra-ai/mastra/commit/cce8aad878a0dd98e5647680f3765caba0b1701c)]:
+  - @mastra/core@0.21.1-alpha.0
+
 ## 0.13.30
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.30",
+  "version": "0.13.31",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@mastra/core": "0.21.0",
+    "@mastra/core": "0.21.1",
     "@mastra/mcp": "^0.13.5"
   },
   "devDependencies": {
@@ -49,8 +49,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.49",
-    "@mastra/core": "0.21.0"
+    "@internal/lint": "0.0.50",
+    "@mastra/core": "0.21.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {