@mastra/mcp-docs-server 0.13.17-alpha.3 → 0.13.17-alpha.5

package/.docs/raw/streaming/workflow-streaming.mdx

@@ -3,6 +3,8 @@ title: "Workflow Streaming | Streaming | Mastra"
 description: "Learn how to use workflow streaming in Mastra, including handling workflow execution events, step streaming, and workflow integration with agents and tools."
 ---
 
+import { Callout } from "nextra/components";
+
 # Workflow streaming
 
 Workflow streaming in Mastra enables workflows to send incremental results while they execute, rather than waiting until completion. This allows you to surface partial progress, intermediate states, or progressive data directly to users or upstream agents and workflows.
@@ -18,6 +20,10 @@ By combining writable workflow streams with agent streaming, you gain fine-grain
 
 The `writer` argument is passed to a workflow step's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables workflow steps to provide intermediate results or status updates while execution is still in progress.
 
+<Callout type="warning">
+You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
+</Callout>
+
 ```typescript {5,8,15} showLineNumbers copy
 import { createStep } from "@mastra/core/workflows";
 
@@ -26,14 +32,14 @@ export const testStep = createStep({
   execute: async ({ inputData, writer }) => {
      const { value } = inputData;
 
-    writer?.write({
+    await writer?.write({
       type: "custom-event",
       status: "pending"
     });
 
     const response = await fetch(...);
 
-    writer?.write({
+   await writer?.write({
       type: "custom-event",
       status: "success"
     });

package/.docs/raw/tools-mcp/overview.mdx

@@ -3,6 +3,8 @@ title: "Tools Overview | Tools & MCP | Mastra Docs"
 description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
 ---
 
+import { Steps } from "nextra/components";
+
 # Tools Overview
 
 Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
@@ -65,3 +67,45 @@ Some providers that we include this layer for:
 - **DeepSeek & Meta:** Apply similar compatibility logic to ensure schema alignment and tool usability.
 
 This approach makes tool usage more reliable and model-agnostic for both custom and MCP tools.
+
+
+## Testing tools locally
+There are two ways to run and test tools.
+
+<Steps>
+
+### Mastra Playground
+
+With the Mastra Dev Server running you can test a tool from the Mastra Playground by visiting [http://localhost:4111/tools](http://localhost:4111/tools) in your browser.
+
+> For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
+
+### Command line
+
+Invoke a tool using `.execute()`.
+
+```typescript filename="src/test-tool.ts" showLineNumbers copy
+import { RuntimeContext } from "@mastra/core/runtime-context";
+import { testTool } from "./mastra/tools/test-tool";
+
+const runtimeContext = new RuntimeContext();
+
+const result = await testTool.execute({
+  context: {
+    value: "foo"
+  },
+  runtimeContext
+});
+
+console.log(result);
+```
+
+> See [createTool()](../../reference/tools/create-tool.mdx) for more information.
+
+To test this tool, run the following:
+
+```bash copy
+npx tsx src/test-tool.ts
+```
+
+</Steps>

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

@@ -130,7 +130,7 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
-### Register workflow
+## Register workflow
 
 Register a workflow using `workflows` in the main Mastra instance:
 
@@ -154,20 +154,24 @@ export const mastra = new Mastra({
 });
 ```
 
-### Run workflow
+## Testing workflows locally
 There are two ways to run and test workflows.
 
 <Steps>
 
-#### Mastra Playground
+### 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.
 
-#### Command line
+> For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
 
-Create a run instance of any Mastra workflow using `createRunAsync` and `start`:
+### Command line
+
+Create a workflow run instance using `createRunAsync` and `start`:
 
 ```typescript {3,5} filename="src/test-workflow.ts" showLineNumbers copy
+import "dotenv/config";
+
 import { mastra } from "./mastra";
 
 const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
@@ -178,15 +182,13 @@ const result = await run.start({
   }
 });
 
-// Dump the complete workflow result (includes status, steps and result)
-console.log(JSON.stringify(result, null, 2));
+console.log(result);
 
-// Get the workflow output value
 if (result.status === 'success') {
-  console.log(`output value: ${result.result.output}`);
+  console.log(result.result.output);
 }
 ```
-> see [createRunAsync](/reference/workflows/create-run) and [start](/reference/workflows/run-methods/start) for more information.
+> see [createRunAsync](../../reference/workflows/create-run.mdx) and [start](../../reference/workflows/run-methods/start.mdx) for more information.
 
 To trigger this workflow, run the following:
 
@@ -196,11 +198,11 @@ npx tsx src/test-workflow.ts
 
 </Steps>
 
-#### Run workflow results
+### Run workflow results
 
 The result of running a workflow using either `start()` or `resume()` will look like one of the following, depending on the outcome.
 
-##### Status success
+#### Status success
 
 ```json
 {
@@ -224,7 +226,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 - **result**: Includes the final output of the workflow, typed according to the `outputSchema`
 
 
-##### Status suspended
+#### Status suspended
 
 ```json
 {
@@ -246,7 +248,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 
 - **suspended**: An optional array listing any steps currently awaiting input before continuing
 
-##### Status failed
+#### Status failed
 
 ```json
 {
@@ -264,7 +266,7 @@ The result of running a workflow using either `start()` or `resume()` will look
 ```
 - **error**: An optional field that includes the error message if the workflow fails
 
-### Stream workflow
+## Stream workflow
 
 Similar to the run method shown above, workflows can also be streamed:
 
@@ -286,7 +288,7 @@ for await (const chunk of result.stream) {
 
 > See [stream](/reference/workflows/run-methods/stream) and [messages](/reference/workflows/run-methods/stream#messages) for more information.
 
-### Watch Workflow
+## Watch Workflow
 
 A workflow can also be watched, allowing you to inspect each event that is emitted.
 
@@ -308,7 +310,7 @@ const result = await run.start({
 
 > See [watch](/reference/workflows/run-methods/watch) for more information.
 
-## More resources
+## Related
 
 - The [Workflow Guide](../../guides/guide/ai-recruiter.mdx) in the Guides section is a tutorial that covers the main concepts.
 - [Parallel Steps workflow example](../../examples/workflows/parallel-steps.mdx)

package/.docs/raw/workflows/suspend-and-resume.mdx

@@ -30,17 +30,15 @@ To pause execution at a specific step until user input is received, use the `⁠
 
 ![Suspending a workflow with suspend()](/image/workflows/workflows-suspend-resume-suspend.jpg)
 
-```typescript {18} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {16} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
   id: "step-1",
-  description: "Test suspend",
   inputSchema: z.object({
     input: z.string()
   }),
   outputSchema: z.object({
     output: z.string()
   }),
-  suspendSchema: z.object({}),
   resumeSchema: z.object({
     city: z.string()
   }),
@@ -48,15 +46,16 @@ const step1 = createStep({
     const { city } = resumeData ?? {};
 
     if (!city) {
-      await suspend({});
-      return { output: "" };
+      return await suspend({});
     }
 
     return { output: "" };
   }
 });
 
-export const testWorkflow = createWorkflow({})
+export const testWorkflow = createWorkflow({
+  // ...
+})
   .then(step1)
   .commit();
 ```
@@ -88,9 +87,10 @@ if (result.status === "suspended") {
     }
   });
 }
-
 ```
 
+> See [Run Workflow Results](/docs/workflows/overview#run-workflow-results) for more details.
+
 In this case, the logic resumes the first step listed in the `suspended` array. A `step` can also be defined using it's `id`, for example: 'step-1'.
 
 ```json
@@ -111,6 +111,63 @@ In this case, the logic resumes the first step listed in the `suspended` array.
 }
 ```
 
+## Providing user feedback with suspend
+
+When a workflow is suspended, feedback can be surfaced to the user through the `suspendSchema`. Include a reason in the `suspend` payload to explain why the workflow paused.
+
+```typescript {13,23} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: "step-1",
+  inputSchema: z.object({
+    value: z.string()
+  }),
+  resumeSchema: z.object({
+    confirm: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  outputSchema: z.object({
+    value: z.string()
+  }),
+  execute: async ({ resumeData, suspend }) => {
+    const { confirm } = resumeData ?? {};
+
+    if (!confirm) {
+      return await suspend({
+        reason: "Confirm to continue"
+      });
+    }
+
+    return { value: "" };
+  }
+});
+
+export const testWorkflow = createWorkflow({
+  // ...
+})
+  .then(step1)
+  .commit();
+
+```
+
+In this case, the reason provided explains that the user must confirm to continue.
+
+```json
+{
+  "step-1": {
+    // ...
+    "status": "suspended",
+    "suspendPayload": {
+      "reason": "Confirm to continue"
+    },
+  }
+}
+```
+
 > See [Run Workflow Results](/docs/workflows/overview#run-workflow-results) for more details.
 
 ## Resuming a workflow with `resume()`