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

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

@@ -1,18 +1,18 @@
 ---
-title: "Reference: Run.stream() | Streaming | Mastra Docs"
-description: Documentation for the `Run.stream()` method in workflows, which allows you to monitor the execution of a workflow run as a stream.
+title: "Reference: Run.stream() | Streaming"
+description: Documentation for the `Run.stream()` method in workflows, which enables real-time streaming of responses.
 ---
 
 # Run.stream()
 
-The `.stream()` method allows you to monitor the execution of a workflow run, providing real-time updates on the status of steps.
+The `.stream()` method enables real-time streaming of responses from a workflow.
 
 ## Usage example
 
 ```typescript showLineNumbers copy
 const run = await workflow.createRun();
 
-const { stream } = await run.stream({
+const stream = run.stream({
   inputData: {
     value: "initial data",
   },
@@ -40,7 +40,7 @@ const { stream } = await run.stream({
       type: "TracingContext",
       isOptional: true,
       description:
-        "Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+        "Tracing context for creating child spans and adding metadata.",
       properties: [
         {
           parameters: [
@@ -49,7 +49,7 @@ const { stream } = await run.stream({
               type: "Span",
               isOptional: true,
               description:
-                "Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.",
+                "Current span for creating child spans and adding metadata.",
             },
           ],
         },
@@ -67,13 +67,63 @@ const { stream } = await run.stream({
               name: "metadata",
               type: "Record<string, any>",
               isOptional: true,
+              description: "Metadata to add to the root trace span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          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.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
               description:
-                "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
             },
           ],
         },
       ],
     },
+    {
+      name: "closeOnSuspend",
+      type: "boolean",
+      description:
+        "Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -83,22 +133,31 @@ const { stream } = await run.stream({
   content={[
     {
       name: "stream",
-      type: "ReadableStream<StreamEvent>",
+      type: "MastraWorkflowStream<ChunkType>",
       description:
-        "A readable stream that emits workflow execution events in real-time",
+        "A custom stream that extends ReadableStream<ChunkType> with additional workflow-specific properties",
     },
     {
-      name: "getWorkflowState",
-      type: "() => Promise<WorkflowResult<TState, TOutput, TSteps>>",
-      description:
-        "A function that returns a promise resolving to the final workflow result",
+      name: "stream.status",
+      type: "Promise<RunStatus>",
+      description: "A promise that resolves to the current workflow run status",
+    },
+    {
+      name: "stream.result",
+      type: "Promise<WorkflowResult<TState, TOutput, TSteps>>",
+      description: "A promise that resolves to the final workflow result",
+    },
+    {
+      name: "stream.usage",
+      type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>",
+      description: "A promise that resolves to token usage statistics",
     },
     {
-      name: "traceId",
+      name: "stream.traceId",
       type: "string",
       isOptional: true,
       description:
-        "The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.",
+        "The trace ID associated with this execution when Tracing is enabled.",
     },
   ]}
 />
@@ -106,29 +165,29 @@ const { stream } = await run.stream({
 ## Extended usage example
 
 ```typescript showLineNumbers copy
-const { getWorkflowState } = await run.stream({
+const run = await workflow.createRun();
+
+const stream = run.stream({
   inputData: {
     value: "initial data",
   },
 });
 
-const result = await getWorkflowState();
+const result = await stream.result;
 ```
 
 ## Stream Events
 
 The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
 
-- **`start`**: Workflow execution begins
-- **`step-start`**: A step begins execution
-- **`tool-call`**: A tool call is initiated
-- **`tool-call-streaming-start`**: Tool call streaming begins
-- **`tool-call-delta`**: Incremental tool output updates
-- **`step-result`**: A step completes with results
-- **`step-finish`**: A step finishes execution
-- **`finish`**: Workflow execution completes
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
 
 ## Related
 
 - [Workflows overview](/docs/v1/workflows/overview#running-workflows)
 - [Workflow.createRun()](/reference/v1/workflows/workflow-methods/create-run)
+- [Run.resumeStream()](./resumeStream)

package/.docs/raw/reference/streaming/workflows/timeTravelStream.mdx

@@ -0,0 +1,170 @@
+---
+title: "Reference: Run.timeTravelStream() | Streaming"
+description: Documentation for the `Run.timeTravelStream()` method for streaming workflow time travel execution.
+---
+
+# Run.timeTravelStream()
+
+The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
+
+## Usage example
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const output = run.timeTravelStream({
+  step: "step2",
+  inputData: { value: 10 },
+});
+
+// Process events as they arrive
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload);
+}
+
+// Get the final result
+const result = await output.result;
+```
+
+## Parameters
+
+All parameters are the same as [`Run.timeTravel()`](../../workflows/run-methods/timeTravel#parameters). See the [timeTravel reference](../../workflows/run-methods/timeTravel#parameters) for detailed parameter documentation.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "output",
+      type: "WorkflowRunOutput<WorkflowResult<TState, TInput, TOutput, TSteps>>",
+      description:
+        "An object containing both the stream and result promise",
+    },
+    {
+      name: "output.fullStream",
+      type: "ReadableStream<WorkflowStreamEvent>",
+      description:
+        "A readable stream that emits workflow events as execution progresses",
+    },
+    {
+      name: "output.result",
+      type: "Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>",
+      description:
+        "A promise that resolves to the final workflow execution result",
+    },
+    {
+      name: "output.traceId",
+      type: "string",
+      isOptional: true,
+      description:
+        "The trace ID associated with this execution when Tracing is enabled",
+    },
+  ]}
+/>
+
+## Stream events
+
+The stream emits various workflow events during execution:
+
+- `workflow-step-start`: Emitted when a step begins execution
+- `workflow-step-finish`: Emitted when a step completes successfully
+- `workflow-step-error`: Emitted when a step encounters an error
+- `workflow-step-suspended`: Emitted when a step suspends
+- Additional events depending on step types (agents, tools, etc.)
+
+## Extended usage examples
+
+### Processing events during time travel
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const output = run.timeTravelStream({
+  step: "step2",
+  inputData: { value: 10 },
+});
+
+for await (const event of output.fullStream) {
+  switch (event.type) {
+    case "workflow-step-start":
+      console.log(`Starting step: ${event.payload.stepName}`);
+      break;
+    case "workflow-step-finish":
+      console.log(`Completed step: ${event.payload.stepName}`);
+      break;
+    case "workflow-step-error":
+      console.error(`Error in step: ${event.payload.stepName}`, event.payload.error);
+      break;
+  }
+}
+
+const result = await output.result;
+console.log("Time travel completed:", result);
+```
+
+### Time travel stream with context
+
+```typescript showLineNumbers copy
+const output = run.timeTravelStream({
+  step: "step2",
+  context: {
+    step1: {
+      status: "success",
+      payload: { value: 0 },
+      output: { step1Result: 2 },
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+    },
+  },
+});
+
+for await (const event of output.fullStream) {
+  // Handle events
+  console.log(event);
+}
+
+const result = await output.result;
+```
+
+### Time travel stream with nested workflows
+
+```typescript showLineNumbers copy
+const output = run.timeTravelStream({
+  step: ["nestedWorkflow", "step3"],
+  inputData: { value: 10 },
+  nestedStepsContext: {
+    nestedWorkflow: {
+      step2: {
+        status: "success",
+        payload: { step1Result: 2 },
+        output: { step2Result: 3 },
+        startedAt: Date.now(),
+        endedAt: Date.now(),
+      },
+    },
+  },
+});
+
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload);
+}
+
+const result = await output.result;
+```
+
+## Notes
+
+- The stream closes automatically when time travel execution completes or encounters an error
+- You can process events from the stream while the workflow is still executing
+- The `result` promise resolves only after all steps have completed
+- Stream events follow the same format as regular workflow streaming
+- Time travel streaming requires storage to be configured since it relies on persisted workflow snapshots
+
+## Related
+
+- [Run.timeTravel()](../../workflows/run-methods/timeTravel)
+- [Time Travel](/docs/v1/workflows/time-travel)
+- [Workflow Streaming](/docs/v1/streaming/workflow-streaming)
+- [Run.stream()](./stream)
+- [Run.resumeStream()](./resumeStream)
+

package/.docs/raw/reference/templates/overview.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: LLM provider API keys (choose one or more) | Templates | Mastra Docs"
+title: "Reference: LLM provider API keys (choose one or more) | Templates"
 description: "Complete guide to creating, using, and contributing Mastra templates"
 ---
 
@@ -118,13 +118,10 @@ We recommend using OpenAI, Anthropic, or Google model providers for templates. C
 
 ```typescript title="src/mastra/agents/example-agent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-// Or use: import { anthropic } from '@ai-sdk/anthropic';
-// Or use: import { google } from '@ai-sdk/google';
 
 const agent = new Agent({
   name: "example-agent",
-  model: openai("gpt-4"), // or anthropic('') or google('')
+  model: "openai/gpt-5.1", // or other provider strings
   instructions: "Your agent instructions here",
   // ... other configuration
 });

package/.docs/raw/reference/tools/client.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraMCPClient (Deprecated) | Tools & MCP | Mastra Docs"
+title: "Reference: MastraMCPClient (Deprecated) | Tools & MCP"
 description: API Reference for MastraMCPClient - A client implementation for the Model Context Protocol.
 ---
 
@@ -230,7 +230,6 @@ Returns an object mapping tool names to their corresponding Mastra tool implemen
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { MastraMCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
 
 // Initialize the MCP client using mcp/fetch as an example https://hub.docker.com/r/mcp/fetch
 // Visit https://github.com/docker/mcp-servers for other reference docker mcp servers
@@ -250,7 +249,7 @@ const agent = new Agent({
   name: "Fetch agent",
   instructions:
     "You are able to fetch data from URLs on demand and discuss the response data with the user.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 
 try {

package/.docs/raw/reference/tools/create-tool.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: createTool() | Tools & MCP | Mastra Docs"
+title: "Reference: createTool() | Tools & MCP"
 description: Documentation for the `createTool()` function in Mastra, used to define custom tools for agents.
 ---
 
@@ -131,6 +131,34 @@ export const tool = createTool({
         },
       ],
     },
+    {
+      name: "onInputStart",
+      type: "function",
+      description:
+        "Optional callback invoked when the tool call input streaming begins. Receives `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onInputDelta",
+      type: "function",
+      description:
+        "Optional callback invoked for each incremental chunk of input text as it streams in. Receives `inputTextDelta`, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onInputAvailable",
+      type: "function",
+      description:
+        "Optional callback invoked when the complete tool input is available and parsed. Receives the validated `input` object, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
+    {
+      name: "onOutput",
+      type: "function",
+      description:
+        "Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's `output`, `toolCallId`, `messages`, and `abortSignal`.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -149,9 +177,112 @@ The `createTool()` function returns a `Tool` object.
   ]}
 />
 
+## Tool Lifecycle Hooks
+
+Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
+
+### Available Hooks
+
+#### onInputStart
+
+Called when tool call input streaming begins, before any input data is received.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  onInputStart: ({ toolCallId, messages, abortSignal }) => {
+    console.log(`Tool ${toolCallId} input streaming started`);
+  },
+  // ... other properties
+});
+```
+
+#### onInputDelta
+
+Called for each incremental chunk of input text as it streams in. Useful for showing real-time progress or parsing partial JSON.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
+    console.log(`Received input chunk: ${inputTextDelta}`);
+  },
+  // ... other properties
+});
+```
+
+#### onInputAvailable
+
+Called when the complete tool input is available and has been parsed and validated against the `inputSchema`.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
+    console.log(`Tool received complete input:`, input);
+    // input is fully typed based on inputSchema
+  },
+  // ... other properties
+});
+```
+
+#### onOutput
+
+Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
+
+```typescript
+export const tool = createTool({
+  id: "example-tool",
+  description: "Example tool with hooks",
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async (input) => {
+    return { result: "Success" };
+  },
+  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
+    console.log(`${toolName} execution completed:`, output);
+    // output is fully typed based on outputSchema
+  },
+});
+```
+
+### Hook Execution Order
+
+For a typical streaming tool call, the hooks are invoked in this order:
+
+1. **onInputStart** - Input streaming begins
+2. **onInputDelta** - Called multiple times as chunks arrive
+3. **onInputAvailable** - Complete input is parsed and validated
+4. Tool's **execute** function runs
+5. **onOutput** - Tool has completed successfully
+
+### Hook Parameters
+
+All hooks receive a parameter object with these common properties:
+
+- `toolCallId` (string): Unique identifier for this specific tool call
+- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
+
+Additionally:
+- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
+- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
+- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
+- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
+
+### Error Handling
+
+Hook errors are caught and logged automatically, but do not prevent tool execution from continuing. If a hook throws an error, it will be logged to the console but will not fail the tool call.
+
 ## Related
 
-- [Tools Overview](/docs/v1/tools-mcp/overview)
+- [MCP Overview](/docs/v1/mcp/overview)
 - [Using Tools with Agents](/docs/v1/agents/using-tools)
-- [Tool Request Context](/docs/v1/tools-mcp/overview#using-requestcontext)
-- [Advanced Tool Usage](/docs/v1/tools-mcp/advanced-usage)
+- [Tool Streaming](/docs/v1/streaming/tool-streaming)
+- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)

package/.docs/raw/reference/tools/document-chunker-tool.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: createDocumentChunkerTool() | Tools & MCP | Mastra Docs"
+title: "Reference: createDocumentChunkerTool() | Tools & MCP"
 description: Documentation for the Document Chunker Tool in Mastra, which splits documents into smaller chunks for efficient processing and retrieval.
 ---
 

package/.docs/raw/reference/tools/graph-rag-tool.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: createGraphRAGTool() | Tools & MCP | Mastra Docs"
+title: "Reference: createGraphRAGTool() | Tools & MCP"
 description: Documentation for the Graph RAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
 ---
 
@@ -10,13 +10,13 @@ The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { createGraphRAGTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     dimension: 1536,
     threshold: 0.7,
@@ -193,7 +193,7 @@ The default description focuses on:
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     dimension: 1536,
     threshold: 0.8, // Higher similarity threshold
@@ -209,7 +209,7 @@ const graphTool = createGraphRAGTool({
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: "openai/text-embedding-3-small	",
   description:
     "Analyze document relationships to find complex patterns and connections in our company's historical data",
 });
@@ -223,7 +223,7 @@ This example shows how to customize the tool description for a specific use case
 const graphTool = createGraphRAGTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: "openai/text-embedding-3-small	",
 });
 ```
 
@@ -254,7 +254,7 @@ const response = await agent.generate(
 For more information on request context, please see:
 
 - [Agent Request Context](/docs/v1/server-db/request-context)
-- [Tool Request Context](/docs/v1/tools-mcp/overview#using-requestcontext)
+- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
 
 ## Related