@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

package/.docs/raw/reference/vectors/upstash.mdx

@@ -164,7 +164,7 @@ Returns an array of index names (namespaces) as strings.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -238,7 +238,7 @@ Upstash Vector supports hybrid search that combines semantic search (dense vecto
 
 ### Basic Hybrid Usage
 
-```typescript copy
+```typescript
 import { UpstashVector } from "@mastra/upstash";
 
 const vectorStore = new UpstashVector({
@@ -275,7 +275,7 @@ const results = await vectorStore.query({
 
 ### Advanced Hybrid Search Options
 
-```typescript copy
+```typescript
 import { FusionAlgorithm, QueryMode } from "@upstash/vector";
 
 // Query with specific fusion algorithm
@@ -307,7 +307,7 @@ const sparseResults = await vectorStore.query({
 
 ### Updating Hybrid Vectors
 
-```typescript copy
+```typescript
 // Update both dense and sparse components
 await vectorStore.updateVector({
   indexName: "hybrid-index",
@@ -324,7 +324,7 @@ await vectorStore.updateVector({
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -337,7 +337,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "index_name",
@@ -358,6 +358,55 @@ Required environment variables:
 - `UPSTASH_VECTOR_URL`: Your Upstash Vector database URL
 - `UPSTASH_VECTOR_TOKEN`: Your Upstash Vector API token
 
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-upstash-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { UpstashStore, UpstashVector } from "@mastra/upstash";
+import { fastembed } from "@mastra/fastembed";
+
+export const upstashAgent = new Agent({
+  id: "upstash-agent",
+  name: "Upstash Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    vector: new UpstashVector({
+      id: 'upstash-agent-vector',
+      url: process.env.UPSTASH_VECTOR_REST_URL!,
+      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
 ## Related
 
 - [Metadata Filters](../rag/metadata-filters)

package/.docs/raw/reference/vectors/vectorize.mdx

@@ -135,7 +135,7 @@ Returns an array of index names as strings.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -259,7 +259,7 @@ Deletes a vector and its associated metadata for a specific ID within an index.
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -272,7 +272,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "index_name",

package/.docs/raw/reference/workflows/run-methods/cancel.mdx

@@ -9,7 +9,7 @@ The `.cancel()` method cancels a workflow run, stopping execution and cleaning u
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 await run.cancel();
@@ -43,7 +43,7 @@ await run.cancel();
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 try {

package/.docs/raw/reference/workflows/run-methods/restart.mdx

@@ -9,13 +9,11 @@ The `.restart()` method restarts an active workflow run that lost connection to
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const result = await run.start({ inputData: { value: "initial data" } });
 
-//.. server connection lost,
-
 const restartedResult = await run.restart();
 ```
 

package/.docs/raw/reference/workflows/run-methods/resume.mdx

@@ -9,7 +9,7 @@ The `.resume()` method resumes a suspended workflow run with new data, allowing
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const result = await run.start({ inputData: { value: "initial data" } });
@@ -177,7 +177,7 @@ if (result.status === "suspended") {
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 if (result.status === "suspended") {
   const resumedResults = await run.resume({
     step: result.suspended[0],

package/.docs/raw/reference/workflows/run-methods/start.mdx

@@ -9,7 +9,7 @@ The `.start()` method starts a workflow run with input data, allowing you to exe
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const result = await run.start({
@@ -168,7 +168,7 @@ const result = await run.start({
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 import { RequestContext } from "@mastra/core/request-context";
 
 const run = await workflow.createRun();

package/.docs/raw/reference/workflows/run-methods/startAsync.mdx

@@ -0,0 +1,143 @@
+---
+title: "Reference: Run.startAsync() | Workflows"
+description: Documentation for the `Run.startAsync()` method in workflows, which starts a workflow run without waiting for completion (fire-and-forget).
+---
+
+# Run.startAsync()
+
+The `.startAsync()` method starts a workflow run without waiting for completion. It returns immediately with the `runId`, allowing the workflow to execute in the background. This is useful for long-running workflows, scheduled tasks, or when you want to avoid blocking on workflow completion.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun();
+
+// Fire-and-forget - returns immediately
+const { runId } = await run.startAsync({
+  inputData: {
+    value: "initial data",
+  },
+});
+
+// Optionally poll for completion later
+const result = await workflow.getWorkflowRunExecutionResult(runId);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "inputData",
+      type: "z.infer<TInput>",
+      description: "Input data that matches the workflow's input schema",
+      isOptional: true,
+    },
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      description: "Request Context data to use during workflow execution",
+      isOptional: true,
+    },
+    {
+      name: "initialState",
+      type: "z.infer<TState>",
+      description: "Initial state to use for the workflow execution",
+      isOptional: true,
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for Tracing configuration.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "metadata",
+              type: "Record<string, any>",
+              isOptional: true,
+              description:
+                "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "traceId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "outputOptions",
+      type: "OutputOptions",
+      isOptional: true,
+      description: "Options for output configuration.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "includeState",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Whether to include the workflow run state in the result.",
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description:
+        "The unique identifier for this workflow run. Use this to check status or retrieve results later.",
+    },
+  ]}
+/>
+
+## When to use startAsync()
+
+Use `startAsync()` instead of `start()` when:
+
+- **Long-running workflows**: The workflow may take minutes or hours to complete
+- **Scheduled/cron triggers**: You want to trigger a workflow without blocking the scheduler
+- **Avoiding polling failures**: With Inngest workflows, `start()` polls for completion which can fail and cause retries. `startAsync()` avoids this issue
+- **Background processing**: You want to queue work and handle results asynchronously
+
+## Checking workflow status
+
+After calling `startAsync()`, you can check the workflow status using:
+
+```typescript
+// Get the execution result (including step outputs)
+const result = await workflow.getWorkflowRunExecutionResult(runId);
+
+if (result?.status === 'success') {
+  console.log('Workflow completed:', result.steps);
+} else if (result?.status === 'failed') {
+  console.log('Workflow failed:', result.error);
+} else if (result?.status === 'running') {
+  console.log('Workflow still running...');
+}
+```
+
+## Related
+
+- [Run.start()](./start) - Start a workflow and wait for completion
+- [Workflows overview](/docs/v1/workflows/overview)
+- [Workflow.createRun()](../workflow-methods/create-run)

package/.docs/raw/reference/workflows/run-methods/timeTravel.mdx

@@ -9,7 +9,7 @@ The `.timeTravel()` method re-executes a workflow starting from any specific ste
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const result = await run.timeTravel({
@@ -213,7 +213,7 @@ const result = await run.timeTravel({
 
 ### Time travel with custom context
 
-```typescript showLineNumbers copy
+```typescript
 const result = await run.timeTravel({
   step: "step2",
   context: {
@@ -230,7 +230,7 @@ const result = await run.timeTravel({
 
 ### Time travel to nested workflow step
 
-```typescript showLineNumbers copy
+```typescript
 // Using dot notation
 const result = await run.timeTravel({
   step: "nestedWorkflow.step3",
@@ -246,7 +246,7 @@ const result = await run.timeTravel({
 
 ### Time travel with initial state
 
-```typescript showLineNumbers copy
+```typescript
 const result = await run.timeTravel({
   step: "step2",
   inputData: { value: 10 },
@@ -259,7 +259,7 @@ const result = await run.timeTravel({
 
 ### Time travel with nested workflows context
 
-```typescript showLineNumbers copy
+```typescript
 const result = await run.timeTravel({
   step: "nestedWorkflow.step3",
   context: {

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

@@ -9,7 +9,7 @@ The `Run` class represents a workflow execution instance, providing methods to s
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const result = await run.start({

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

@@ -10,7 +10,7 @@ It can take either a tool or an agent as a parameter to automatically create a s
 
 ## Usage example
 
-```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -38,7 +38,7 @@ You can create a step directly from an agent. The step will use the agent's name
 
 ### Basic agent step
 
-```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts"
 import { testAgent } from "../agents/test-agent";
 
 const agentStep = createStep(testAgent);
@@ -50,7 +50,7 @@ const agentStep = createStep(testAgent);
 
 Pass `structuredOutput` to have the agent return typed structured data:
 
-```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts"
 const articleSchema = z.object({
   title: z.string(),
   summary: z.string(),

package/.docs/raw/reference/workflows/workflow-methods/branch.mdx

@@ -9,7 +9,7 @@ The `.branch()` method creates conditional branches between workflow steps, allo
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.branch([
   [async ({ context }) => true, step1],
   [async ({ context }) => false, step2],

package/.docs/raw/reference/workflows/workflow-methods/commit.mdx

@@ -9,7 +9,7 @@ The `.commit()` method finalizes the workflow and returns the final result.
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.then(step1).commit();
 ```
 

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

@@ -9,7 +9,7 @@ The `.createRun()` method creates a new workflow run instance, allowing you to e
 
 ## Usage example
 
-```typescript copy
+```typescript
 await workflow.createRun();
 ```
 
@@ -23,6 +23,18 @@ await workflow.createRun();
       description: "Optional custom identifier for the workflow run",
       isOptional: true,
     },
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Optional identifier to associate the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the workflow run and can be used for filtering and querying runs.",
+      isOptional: true,
+    },
+    {
+      name: "disableScorers",
+      type: "boolean",
+      description: "Optional flag to disable scorers for this workflow run",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -41,7 +53,7 @@ await workflow.createRun();
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 const workflow = mastra.getWorkflow("workflow");
 
 const run = await workflow.createRun();
@@ -53,6 +65,29 @@ const result = await run.start({
 });
 ```
 
+## Using resourceId
+
+The `resourceId` parameter associates a workflow run with a specific resource, such as a user or tenant. This is useful for multi-tenant applications or when you need to track which user initiated a workflow.
+
+```typescript
+const workflow = mastra.getWorkflow("workflow");
+
+// Create a run associated with a specific user
+const run = await workflow.createRun({
+  resourceId: "user-123",
+});
+
+const result = await run.start({
+  inputData: {
+    value: 10,
+  },
+});
+
+// Later, retrieve the run and access the resourceId
+const storedRun = await workflow.getWorkflowRunById(run.runId);
+console.log(storedRun.resourceId); // "user-123"
+```
+
 ## Related
 
 - [Run Class](../run)

package/.docs/raw/reference/workflows/workflow-methods/dountil.mdx

@@ -9,7 +9,7 @@ The `.dountil()` method executes a step until a condition is met. It always runs
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.dountil(step1, async ({ inputData }) => true);
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/dowhile.mdx

@@ -9,7 +9,7 @@ The `.dowhile()` method executes a step while a condition is met. It always runs
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.dowhile(step1, async ({ inputData }) => true);
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/foreach.mdx

@@ -9,7 +9,7 @@ The `.foreach()` method creates a loop that executes a step for each item in an
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.foreach(step1, { concurrency: 2 });
 ```
 
@@ -67,7 +67,7 @@ If you need to run multiple operations per item, use a nested workflow as the st
 
 `.foreach()` always outputs an array. Each element in the output array corresponds to the result of processing the element at the same index in the input array.
 
-```typescript copy
+```typescript
 // Input: [{ value: 1 }, { value: 2 }, { value: 3 }]
 // Step adds 10 to each value
 // Output: [{ value: 11 }, { value: 12 }, { value: 13 }]
@@ -77,7 +77,7 @@ If you need to run multiple operations per item, use a nested workflow as the st
 
 When you chain `.then()` after `.foreach()`, the next step receives the entire output array as its input. This allows you to aggregate or process all results together.
 
-```typescript copy
+```typescript
 workflow
   .foreach(processItemStep)    // Output: array of processed items
   .then(aggregateStep)         // Input: the entire array
@@ -88,7 +88,7 @@ workflow
 
 Use `.map()` to transform the array output before passing it to the next step:
 
-```typescript copy
+```typescript
 workflow
   .foreach(processItemStep)
   .map(async ({ inputData }) => ({
@@ -103,7 +103,7 @@ workflow
 
 When you chain `.foreach()` calls, each operates on the array from the previous step:
 
-```typescript copy
+```typescript
 workflow
   .foreach(stepA)    // If input is [a, b, c], output is [A, B, C]
   .foreach(stepB)    // Operates on [A, B, C], output is [A', B', C']
@@ -112,7 +112,7 @@ workflow
 
 If a step inside `.foreach()` returns an array, the output becomes an array of arrays. Use `.map()` with `.flat()` to flatten:
 
-```typescript copy
+```typescript
 workflow
   .foreach(chunkStep)           // Output: [[chunk1, chunk2], [chunk3, chunk4]]
   .map(async ({ inputData }) => inputData.flat())  // Output: [chunk1, chunk2, chunk3, chunk4]

package/.docs/raw/reference/workflows/workflow-methods/map.mdx

@@ -9,7 +9,7 @@ The `.map()` method maps output data from a previous step to the input of a subs
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.map(async ({ inputData }) => `${inputData.value} - map`
 ```
 
@@ -43,7 +43,7 @@ workflow.map(async ({ inputData }) => `${inputData.value} - map`
 
 Use `inputData` to access the full output of the previous step.
 
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(({ inputData }) => {
     console.log(inputData);
@@ -54,7 +54,7 @@ Use `inputData` to access the full output of the previous step.
 
 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
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(async ({ getStepResult }) => {
     console.log(getStepResult(step1));
@@ -65,7 +65,7 @@ Use `getStepResult()` to access the full output of a specific step by referencin
 
 Use `getInitData()` to access the initial input data provided to the workflow.
 
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(async ({ getInitData }) => {
       console.log(getInitData());
@@ -77,7 +77,7 @@ Use `getInitData()` to access the initial input data provided to the workflow.
 The object form of `.map()` provides an alternative declarative syntax for mapping fields. Instead of writing a function, you define an object where each key is a new field name and each value uses `mapVariable()` to extract data from previous steps or workflow input.
 Import `mapVariable()` from the workflows module:
 
-```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript filename="src/mastra/workflows/test-workflow.ts"
 import { mapVariable } from "@mastra/core/workflows";
 ```
 
@@ -86,7 +86,7 @@ import { mapVariable } from "@mastra/core/workflows";
 Use `mapVariable()` with `step` to extract a specific field from a step's output and map it to a new field name. The `path` parameter specifies which field to extract.
 In this example, the `value` field from `step1`'s output is extracted and mapped to a new field called `details`:
 
-```typescript {3-6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3-6} filename="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map({
     details: mapVariable({
@@ -101,7 +101,7 @@ In this example, the `value` field from `step1`'s output is extracted and mapped
 Use `mapVariable()` with `initData` to extract a specific field from the workflow's initial input data. This is useful when you need to pass the original workflow input to a later step.
 In this example, the `value` field from the workflow's input is extracted and mapped to a field called `details`:
 
-```typescript {6-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {6-9} filename="src/mastra/workflows/test-workflow.ts"
 export const testWorkflow = createWorkflow({...});
 
 testWorkflow

package/.docs/raw/reference/workflows/workflow-methods/parallel.mdx

@@ -9,7 +9,7 @@ The `.parallel()` method executes multiple steps in parallel.
 
 ## Usage example
 
-```typescript copy
+```typescript
 workflow.parallel([step1, step2]);
 ```
 

package/.docs/raw/reference/workflows/workflow-methods/sendEvent.mdx

@@ -9,7 +9,7 @@ The `.sendEvent()` resumes execution when an event is sent.
 
 ## Usage example
 
-```typescript copy
+```typescript
 run.sendEvent("event-name", { value: "data" });
 ```
 
@@ -46,7 +46,7 @@ run.sendEvent("event-name", { value: "data" });
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 import { mastra } from "./mastra";
 
 const run = await mastra.getWorkflow("testWorkflow").createRun();