@mastra/mcp-docs-server 0.13.2-alpha.0 → 0.13.2-alpha.2

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -539,6 +539,7 @@ runtimeContext.set("filter", { category: "docs" });
 runtimeContext.set("databaseConfig", {
   pinecone: { namespace: "runtime-namespace" }
 });
+runtimeContext.set("model", openai.embedding("text-embedding-3-small"));
 
 const response = await agent.generate(
   "Find documentation from the knowledge base.",

package/.docs/raw/reference/workflows/create-run.mdx

@@ -31,7 +31,7 @@ const mastra = new Mastra({
   },
 });
 
-const run = mastra.getWorkflow("myWorkflow").createRun();
+const run = await mastra.getWorkflow("myWorkflow").createRunAsync();
 ```
 
 ## Parameters

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

@@ -10,7 +10,7 @@ The `.resume()` method resumes a suspended workflow run with new data, allowing
 ## Usage
 
 ```typescript
-const run = counterWorkflow.createRun();
+const run = await counterWorkflow.createRunAsync();
 const result = await run.start({ inputData: { startValue: 0 } });
 
 if (result.status === "suspended") {

package/.docs/raw/reference/workflows/sleep.mdx

@@ -0,0 +1,43 @@
+---
+title: "Reference: Workflow.sleep() | Building Workflows | Mastra Docs"
+description: Documentation for the `.sleep()` method in workflows, which pauses execution for a specified number of milliseconds.
+---
+
+# Workflow.sleep()
+
+The `.sleep()` method pauses execution for a specified number of milliseconds.
+
+## Usage
+
+```typescript
+workflow.sleep(1000);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "milliseconds",
+      type: "number",
+      description: "The number of milliseconds to pause execution",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
+
+## Related
+
+- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)

package/.docs/raw/reference/workflows/sleepUntil.mdx

@@ -0,0 +1,43 @@
+---
+title: "Reference: Workflow.sleepUntil() | Building Workflows | Mastra Docs"
+description: Documentation for the `.sleepUntil()` method in workflows, which pauses execution until a specified date.
+---
+
+# Workflow.sleepUntil()
+
+The `.sleepUntil()` method pauses execution until a specified date.
+
+## Usage
+
+```typescript
+workflow.sleepUntil(new Date(Date.now() + 1000));
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "date",
+      type: "Date",
+      description: "The date until which to pause execution",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
+
+## Related
+
+- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)

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

@@ -10,7 +10,7 @@ The `.start()` method starts a workflow run with input data, allowing you to exe
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Start the workflow with input data
 const result = await run.start({

package/.docs/raw/reference/workflows/stream.mdx

@@ -10,7 +10,7 @@ The `.stream()` method allows you to monitor the execution of a workflow run, pr
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Add a stream to monitor execution
 const result = run.stream({ inputData: {...} });

package/.docs/raw/reference/workflows/waitForEvent.mdx

@@ -0,0 +1,49 @@
+---
+title: "Reference: Workflow.waitForEvent() | Building Workflows | Mastra Docs"
+description: Documentation for the `.waitForEvent()` method in workflows, which pauses execution until an event is received.
+---
+
+# Workflow.waitForEvent()
+
+The `.waitForEvent()` method pauses execution until an event is received.
+
+## Usage
+
+```typescript
+workflow.waitForEvent('my-event-name', step1);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "eventName",
+      type: "string",
+      description: "The name of the event to wait for",
+      isOptional: false,
+    },
+    {
+      name: "step",
+      type: "Step",
+      description: "The step to resume after the event is received",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "Workflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
+
+## Related
+
+- [Sleep & Events](../../docs/workflows/pausing-execution.mdx)

package/.docs/raw/reference/workflows/watch.mdx

@@ -10,7 +10,7 @@ The `.watch()` method allows you to monitor the execution of a workflow run, pro
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Add a watcher to monitor execution
 run.watch(event => {

package/.docs/raw/reference/workflows/workflow.mdx

@@ -31,7 +31,7 @@ const mastra = new Mastra({
   },
 });
 
-const run = mastra.getWorkflow("myWorkflow").createRun();
+const run = await mastra.getWorkflow("myWorkflow").createRunAsync();
 ```
 
 ## API Reference
@@ -99,7 +99,11 @@ Validates and finalizes the workflow configuration. Must be called after adding
 
 #### `createRun()`
 
-Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+Deprecated. Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+
+#### `createRunAsync()`
+
+Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID. Stores a pending workflow run snapshot into storage.
 
 #### `execute()`
 

package/.docs/raw/storage/overview.mdx

@@ -55,7 +55,7 @@ Each tab includes detailed column information with types, constraints, and examp
 The data types include Messages, Threads, Workflows, Eval Datasets, and Traces.
 */}
 
-<Tabs items={['Messages', 'Threads', 'Workflows', 'Eval Datasets', 'Traces']}>
+<Tabs items={['Messages', 'Threads', 'Resources', 'Workflows', 'Eval Datasets', 'Traces']}>
   <Tabs.Tab>
 Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.
 
@@ -212,6 +212,55 @@ Groups related messages together and associates them with a resource. Contains m
   ]}
 />
 
+</Tabs.Tab>
+  <Tabs.Tab>
+Stores user-specific data for resource-scoped working memory. Each resource represents a user or entity, allowing working memory to persist across all conversation threads for that user.
+
+<br />
+<SchemaTable
+  columns={[
+    {
+      name: "id",
+      type: "text",
+      description: "Resource identifier (user or entity ID) - same as resourceId used in threads and agent calls",
+      constraints: [
+        { type: "primaryKey" },
+        { type: "nullable", value: false }
+      ]
+    },
+    {
+      name: "workingMemory",
+      type: "text",
+      description: "Persistent working memory data as Markdown text. Contains user profile, preferences, and contextual information that persists across conversation threads.",
+      constraints: [{ type: "nullable", value: true }]
+    },
+    {
+      name: "metadata",
+      type: "jsonb",
+      description: "Additional resource metadata as JSON. Example:",
+      example: {
+        preferences: { language: "en", timezone: "UTC" },
+        tags: ["premium", "beta-user"]
+      },
+      constraints: [{ type: "nullable", value: true }]
+    },
+    {
+      name: "createdAt",
+      type: "timestamp",
+      description: "When the resource record was first created",
+      constraints: [{ type: "nullable", value: false }]
+    },
+    {
+      name: "updatedAt",
+      type: "timestamp",
+      description: "When the working memory was last updated",
+      constraints: [{ type: "nullable", value: false }]
+    }
+  ]}
+/>
+
+**Note**: This table is only created and used by storage adapters that support resource-scoped working memory (LibSQL, PostgreSQL, Upstash). Other storage adapters will provide helpful error messages if resource-scoped memory is attempted.
+
 </Tabs.Tab>
   <Tabs.Tab>
 When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.

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

@@ -309,4 +309,56 @@ const server = new MCPServer({
 For an agent to be exposed as a tool, it must have a non-empty `description` string. Similarly, for a workflow to be exposed, its `description` must also be a non-empty string. If the description is missing or empty for either, `MCPServer` will throw an error during initialization.
 Workflows will use their `inputSchema` for the tool's input.
 
+### Tools with Structured Outputs
+
+You can define an `outputSchema` for your tools to enforce a specific structure for the tool's output. This is useful for ensuring that the tool returns data in a consistent and predictable format, which can then be validated by the client.
+
+When a tool includes an `outputSchema`, its `execute` function **must** return an object containing a `structuredContent` property. The value of `structuredContent` must conform to the `outputSchema`. Mastra will automatically validate this output on both the server and client sides.
+
+Here's an example of a tool with an `outputSchema`:
+
+```typescript filename="src/tools/structured-tool.ts"
+import { createTool } from '@mastra/core';
+import { z } from 'zod';
+
+export const structuredTool = createTool({
+  description: 'A test tool that returns structured data.',
+  parameters: z.object({
+    input: z.string().describe('Some input string.'),
+  }),
+  outputSchema: z.object({
+    processedInput: z.string().describe('The processed input string.'),
+    timestamp: z.string().describe('An ISO timestamp.'),
+  }),
+  execute: async ({ input }) => {
+    // When outputSchema is defined, you must return a structuredContent object
+    return {
+      structuredContent: {
+        processedInput: `processed: ${input}`,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  },
+});
+```
+
+When this tool is called, the MCP client will receive both the structured data and a text representation of it.
+
+```
+Tool result
+
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"processedInput\": \"hello\", \"timestamp\": \"2025-06-19T16:53:16.472Z\"}"
+    }
+  ],
+  "structuredContent": {
+    "processedInput": "processed: hello",
+    "timestamp": "2025-06-19T16:53:16.472Z",
+  }
+}
+```
+
 For detailed usage and examples, see the [`MCPServer` reference documentation](/reference/tools/mcp-server).

package/.docs/raw/workflows/control-flow.mdx

@@ -126,6 +126,47 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
+### Early exit
+
+You can bail out of a workflow execution successfully by calling `bail()` in a step. This returns whatever payload is passed to the `bail()` function as the result of the workflow.
+
+```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, inputData }) => {
+    return bail({ result: 'bailed' });
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+Unsuccessful bails happen through throwing an error in the step.
+
+```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, inputData }) => {
+    throw new Error('bailed');
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
 #### Example Run Instance
 
 The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
@@ -133,7 +174,7 @@ The following example demonstrates how to start a run with multiple inputs. Each
 ```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.start({
   inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]

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

@@ -163,7 +163,7 @@ export const mastra = new Mastra({
 ```sh
 docker run --rm -p 8288:8288 \
   inngest/inngest \
-  inngest dev -u http://host.docker.internal:4111/inngest/api
+  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.

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

@@ -157,12 +157,12 @@ With the Mastra Dev Server running you can run the workflow from the Mastra Play
 
 #### Command line
 
-Create a run instance of any Mastra workflow using `createRun` and `start`:
+Create a run instance of any Mastra workflow using `createRunAsync` and `start`:
 
 ```typescript {3,5} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.start({
   inputData: {
@@ -172,7 +172,7 @@ const result = await run.start({
 
 console.log(JSON.stringify(result, null, 2));
 ```
-> see [createRun](/reference/workflows/create-run) and [start](/reference/workflows/start) for more information.
+> see [createRunAsync](/reference/workflows/create-run-async) and [start](/reference/workflows/start) for more information.
 
 To trigger this workflow, run the following:
 
@@ -182,6 +182,74 @@ npx tsx src/test-workflow.ts
 
 </Steps>
 
+#### 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
+
+```json
+{
+  "status": "success",
+  "steps": {
+    // ...
+    "step-1": {
+      // ...
+      "status": "success",
+    }
+  },
+  "result": {
+    "output": "London + step-1"
+  }
+}
+```
+
+- **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
+
 ### Stream Workflow
 
 Similar to the run method shown above, workflows can also be streamed:
@@ -189,7 +257,7 @@ Similar to the run method shown above, workflows can also be streamed:
 ```typescript {5} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.stream({
   inputData: {
@@ -211,7 +279,7 @@ A workflow can also be watched, allowing you to inspect each event that is emitt
 ```typescript {5} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 run.watch((event) => {
   console.log(event);

package/.docs/raw/workflows/pausing-execution.mdx

@@ -0,0 +1,60 @@
+---
+title: "Pausing Execution | Mastra Docs"
+description: "Pausing execution in Mastra workflows allows you to pause execution while waiting for external input or resources via .sleep(), .sleepUntil() and .waitForEvent()."
+---
+
+# Sleep & Events
+
+Pausing execution in Mastra workflows allows you to pause execution while waiting for external input or resources via `sleep()`, `sleepUntil()` and `waitForEvent()`.
+
+This sets the workflow status to `waiting`.
+
+## sleep()
+
+`sleep()` pauses execution for a specified number of milliseconds.
+
+```typescript
+workflow
+    .then(step1)
+    .sleep(1000)
+    .then(step2)
+    .commit();
+```
+
+## sleepUntil()
+
+`sleepUntil()` pauses execution until a specified date.
+
+```typescript
+workflow
+    .then(step1)
+    .sleepUntil(new Date(Date.now() + 1000))
+    .then(step2)
+    .commit();
+```
+
+## waitForEvent()
+
+`waitForEvent()` pauses execution until an event is received. Events can be sent to the workflow using `run.sendEvent()`. The event name and the step to resume after the event is received are provided as arguments to `waitForEvent()`.
+
+`.sendEvent()` takes as arguments the event name and the event data. The event data is optional and can be any JSON-serializable value.
+
+```typescript
+workflow
+    .then(step1)
+    .waitForEvent('my-event-name', step2)
+    .then(step3)
+    .commit();
+
+const run = await workflow.createRunAsync()
+run.start({})
+
+setTimeout(() => {
+    run.sendEvent('my-event-name', {
+        data1: 'hello',
+        data2: {
+            anyData: 12
+        }
+    })
+}, 2e3)
+```