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

package/.docs/raw/server-db/{runtime-context.mdx → request-context.mdx}

@@ -1,19 +1,19 @@
 ---
-title: "Runtime Context | Server & DB | Mastra Docs"
-description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
+title: "Request Context | Server & DB | Mastra Docs"
+description: Learn how to use Mastra's RequestContext to provide dynamic, request-specific configuration to agents.
 ---
 
-# Runtime Context
+# Request Context
 
-Agents, tools, and workflows can all accept `RuntimeContext` as a parameter, making request-specific values available to the underlying primitives.
+Agents, tools, and workflows can all accept `RequestContext` as a parameter, making request-specific values available to the underlying primitives.
 
-## When to use `RuntimeContext`
+## When to use `RequestContext`
 
-Use `RuntimeContext` when a primitive’s behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
+Use `RequestContext` when a primitive’s behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
 
 :::note
 
-**Note:** `RuntimeContext` is primarily used for passing data into specific
+**Note:** `RequestContext` is primarily used for passing data into specific
 requests. It's distinct from agent memory, which handles conversation
 history and state persistence across multiple calls.
 
@@ -21,7 +21,7 @@ history and state persistence across multiple calls.
 
 ## Setting values
 
-Pass `runtimeContext` into an agent, network, workflow, or tool call to make values available to all underlying primitives during execution. Use `.set()` to define values before making the call.
+Pass `requestContext` into an agent, network, workflow, or tool call to make values available to all underlying primitives during execution. Use `.set()` to define values before making the call.
 
 The `.set()` method takes two arguments:
 
@@ -29,54 +29,54 @@ The `.set()` method takes two arguments:
 2. **value**: The data to associate with that key.
 
 ```typescript showLineNumbers
-import { RuntimeContext } from "@mastra/core/runtime-context";
+import { RequestContext } from "@mastra/core/request-context";
 
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
 
-const runtimeContext = new RuntimeContext<UserTier>();
-runtimeContext.set("user-tier", "enterprise");
+const requestContext = new RequestContext<UserTier>();
+requestContext.set("user-tier", "enterprise");
 
 const agent = mastra.getAgent("weatherAgent");
 await agent.generate("What's the weather in London?", {
-  runtimeContext,
+  requestContext,
 });
 
 const routingAgent = mastra.getAgent("routingAgent");
 routingAgent.network("What's the weather in London?", {
-  runtimeContext,
+  requestContext,
 });
 
-const run = await mastra.getWorkflow("weatherWorkflow").createRunAsync();
+const run = await mastra.getWorkflow("weatherWorkflow").createRun();
 await run.start({
   inputData: {
     location: "London",
   },
-  runtimeContext,
+  requestContext,
 });
 await run.resume({
   resumeData: {
     city: "New York",
   },
-  runtimeContext,
+  requestContext,
 });
 
 await weatherTool.execute({
   context: {
     location: "London",
   },
-  runtimeContext,
+  requestContext,
 });
 ```
 
 ### Setting values based on request headers
 
-You can populate `runtimeContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
+You can populate `requestContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
-import { RuntimeContext } from "@mastra/core/runtime-context";
+import { Mastra } from "@mastra/core";
+import { RequestContext } from "@mastra/core/request-context";
 import { testWeatherAgent } from "./agents/test-weather-agent";
 
 export const mastra = new Mastra({
@@ -85,9 +85,9 @@ export const mastra = new Mastra({
     middleware: [
       async (context, next) => {
         const country = context.req.header("CF-IPCountry");
-        const runtimeContext = context.get("runtimeContext");
+        const requestContext = context.get("requestContext");
 
-        runtimeContext.set(
+        requestContext.set(
           "temperature-unit",
           country === "US" ? "fahrenheit" : "celsius",
         );
@@ -99,11 +99,11 @@ export const mastra = new Mastra({
 });
 ```
 
-> See [Middleware](/docs/server-db/middleware) for how to use server middleware.
+> See [Middleware](/docs/v1/server-db/middleware) for how to use server middleware.
 
 ## Accessing values with agents
 
-You can access the `runtimeContext` argument from any supported configuration options in agents. These functions can be sync or `async`. Use the `.get()` method to read values from `runtimeContext`.
+You can access the `requestContext` argument from any supported configuration options in agents. These functions can be sync or `async`. Use the `.get()` method to read values from `requestContext`.
 
 ```typescript {7-8,15,18,21} title="src/mastra/agents/weather-agent.ts" showLineNumbers
 export type UserTier = {
@@ -111,34 +111,35 @@ export type UserTier = {
 };
 
 export const weatherAgent = new Agent({
-  name: "weather-agent",
-  instructions: async ({ runtimeContext }) => {
-    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+  id: "weather-agent",
+  name: "Weather Agent",
+  instructions: async ({ requestContext }) => {
+    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
     if (userTier === "enterprise") {
       // ...
     }
     // ...
   },
-  model: ({ runtimeContext }) => {
+  model: ({ requestContext }) => {
     // ...
   },
-  tools: ({ runtimeContext }) => {
+  tools: ({ requestContext }) => {
     // ...
   },
-  memory: ({ runtimeContext }) => {
+  memory: ({ requestContext }) => {
     // ...
   },
 });
 ```
 
-You can also use `runtimeContext` with other options like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
+You can also use `requestContext` with other options like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
 
-> See [Agent](/reference/agents/agent) for a full list of configuration options.
+> See [Agent](/reference/v1/agents/agent) for a full list of configuration options.
 
 ## Accessing values from workflow steps
 
-You can access the `runtimeContext` argument from a workflow step's `execute` function. This function can be sync or async. Use the `.get()` method to read values from `runtimeContext`.
+You can access the `requestContext` argument from a workflow step's `execute` function. This function can be sync or async. Use the `.get()` method to read values from `requestContext`.
 
 ```typescript {7-8} title="src/mastra/workflows/weather-workflow.ts" showLineNumbers copy
 export type UserTier = {
@@ -147,8 +148,8 @@ export type UserTier = {
 
 const stepOne = createStep({
   id: "step-one",
-  execute: async ({ runtimeContext }) => {
-    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+  execute: async ({ requestContext }) => {
+    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
     if (userTier === "enterprise") {
       // ...
@@ -158,11 +159,11 @@ const stepOne = createStep({
 });
 ```
 
-> See [createStep()](/reference/workflows/step) for a full list of configuration options.
+> See [createStep()](/reference/v1/workflows/step) for a full list of configuration options.
 
 ## Accessing values with tools
 
-You can access the `runtimeContext` argument from a tool’s `execute` function. This function is `async`. Use the `.get()` method to read values from `runtimeContext`.
+You can access the `requestContext` argument from a tool’s `execute` function. This function is `async`. Use the `.get()` method to read values from `requestContext`.
 
 ```typescript {7-8} title="src/mastra/tools/weather-tool.ts" showLineNumbers
 export type UserTier = {
@@ -171,8 +172,8 @@ export type UserTier = {
 
 export const weatherTool = createTool({
   id: "weather-tool",
-  execute: async ({ runtimeContext }) => {
-    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+  execute: async ({ requestContext }) => {
+    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
     if (userTier === "enterprise") {
       // ...
@@ -182,12 +183,12 @@ export const weatherTool = createTool({
 });
 ```
 
-> See [createTool()](/reference/tools/create-tool) for a full list of configuration options.
+> See [createTool()](/reference/v1/tools/create-tool) for a full list of configuration options.
 
 ## Related
 
-- [Runtime Context Example](/examples/agents/runtime-context)
-- [Agent Runtime Context](/docs/agents/overview#using-runtimecontext)
-- [Workflow Runtime Context](../workflows/overview#using-runtimecontext)
-- [Tool Runtime Context](../tools-mcp/overview#using-runtimecontext)
-- [Server Middleware Runtime Context](/docs/server-db/middleware)
+- [Request Context Example](/examples/v1/agents/request-context)
+- [Agent Request Context](/docs/v1/agents/overview#using-requestcontext)
+- [Workflow Request Context](../workflows/overview#using-requestcontext)
+- [Tool Request Context](../tools-mcp/overview#using-requestcontext)
+- [Server Middleware Request Context](/docs/v1/server-db/middleware)

package/.docs/raw/server-db/storage.mdx

@@ -31,11 +31,12 @@ Mastra provides different storage providers, but you can treat them as interchan
 Mastra can be configured with a default storage option:
 
 ```typescript copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
 const mastra = new Mastra({
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: "file:./mastra.db",
   }),
 });
@@ -246,8 +247,6 @@ Stores user-specific data for resource-scoped working memory. Each resource repr
   ]}
 />
 
-**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.
-
 </TabItem>
   <TabItem value="workflows" label="Workflows">
 When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.
@@ -474,37 +473,46 @@ Captures OpenTelemetry traces for monitoring and debugging.
 
 ### Querying Messages
 
-Messages are stored in a V2 format internally, which is roughly equivalent to the AI SDK's `UIMessage` format. When querying messages using `getMessages`, you can specify the desired output format, defaulting to `v1` for backwards compatibility:
+Messages are stored in the `MastraDBMessage` format, which provides a consistent structure across the entire Mastra system:
 
 ```typescript copy
-// Get messages in the default V1 format (roughly equivalent to AI SDK's CoreMessage format)
-const messagesV1 = await mastra
+// Get messages for a thread with pagination
+const result = await mastra
   .getStorage()
-  .getMessages({ threadId: "your-thread-id" });
-
-// Get messages in the V2 format (roughly equivalent to AI SDK's UIMessage format)
-const messagesV2 = await mastra
+  .listMessages({
+    threadId: "your-thread-id",
+    page: 0,
+    perPage: 50
+  });
+
+console.log(result.messages); // MastraDBMessage[]
+console.log(result.total); // Total count
+console.log(result.hasMore); // Whether more pages exist
+
+// Get messages by their IDs
+const messages = await mastra
   .getStorage()
-  .getMessages({ threadId: "your-thread-id", format: "v2" });
+  .listMessagesById({ messageIds: messageIdArr });
 ```
 
-You can also retrieve messages using an array of message IDs. Note that unlike `getMessages`, this defaults to the V2 format:
+All message queries return `MastraDBMessage[]` format. If you need to convert messages to AI SDK formats for UI rendering, use the conversion utilities from `@mastra/ai-sdk/ui`:
 
 ```typescript copy
-const messagesV1 = await mastra
-  .getStorage()
-  .getMessagesById({ messageIds: messageIdArr, format: "v1" });
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
 
-const messagesV2 = await mastra
+const result = await mastra
   .getStorage()
-  .getMessagesById({ messageIds: messageIdArr });
+  .listMessages({ threadId: "your-thread-id" });
+
+// Convert to AI SDK v5 UIMessage format for UI rendering
+const uiMessages = toAISdkV5Messages(result.messages);
 ```
 
 ## Storage Providers
 
 Mastra supports the following providers:
 
-- For local development, check out [LibSQL Storage](/reference/storage/libsql)
-- For production, check out [PostgreSQL Storage](/reference/storage/postgresql)
-- For serverless deployments, check out [Upstash Storage](/reference/storage/upstash)
-- For document-based storage, check out [MongoDB Storage](/reference/storage/mongodb)
+- For local development, check out [LibSQL Storage](/reference/v1/storage/libsql)
+- For production, check out [PostgreSQL Storage](/reference/v1/storage/postgresql)
+- For serverless deployments, check out [Upstash Storage](/reference/v1/storage/upstash)
+- For document-based storage, check out [MongoDB Storage](/reference/v1/storage/mongodb)

package/.docs/raw/streaming/events.mdx

@@ -56,7 +56,7 @@ for await (const chunk of stream) {
 }
 ```
 
-> See [Agent.stream()](/reference/streaming/agents/stream) for more information.
+> See [Agent.stream()](/reference/v1/streaming/agents/stream) for more information.
 
 ### Example agent output
 
@@ -94,7 +94,7 @@ Iterate over the `stream` with a `for await` loop to inspect all emitted event c
 ```typescript {5,11} showLineNumbers copy
 const testWorkflow = mastra.getWorkflow("testWorkflow");
 
-const run = await testWorkflow.createRunAsync();
+const run = await testWorkflow.createRun();
 
 const stream = await run.stream({
   inputData: {
@@ -148,7 +148,7 @@ for await (const chunk of networkStream) {
 }
 ```
 
-> See [Agent.network()](/reference/agents/network) for more information.
+> See [Agent.network()](/reference/v1/agents/network) for more information.
 
 ### Example network output
 

package/.docs/raw/streaming/overview.mdx

@@ -34,7 +34,7 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-> See [Agent.stream()](/reference/streaming/agents/stream) for more information.
+> See [Agent.stream()](/reference/v1/streaming/agents/stream) for more information.
 
 ### Output from `Agent.stream()`
 
@@ -91,7 +91,7 @@ for await (const chunk of networkStream) {
 }
 ```
 
-> See [Agent.network()](/reference/agents/network) for more information.
+> See [Agent.network()](/reference/v1/agents/network) for more information.
 
 #### Network stream properties
 
@@ -119,14 +119,14 @@ console.log("Token usage:", await networkStream.usage);
 
 ## Streaming with workflows
 
-Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRunAsync()`.
+Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRun()`.
 
 ### Using `Run.streamVNext()`
 
 This is the experimental API. It returns a `ReadableStream` of events directly.
 
 ```typescript {3,9} showLineNumbers copy
-const run = await testWorkflow.createRunAsync();
+const run = await testWorkflow.createRun();
 
 const stream = await run.streamVNext({
   inputData: {
@@ -172,5 +172,5 @@ A workflow stream provides access to various response properties:
 ## Related
 
 - [Streaming events](./events)
-- [Using Agents](/docs/agents/overview)
+- [Using Agents](/docs/v1/agents/overview)
 - [Workflows overview](../workflows/overview)

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

@@ -9,8 +9,8 @@ Tool streaming in Mastra enables tools to send incremental results while they ru
 
 Streams can be written to in two main ways:
 
-- **From within a tool**: every tool receives a `writer` argument, which is a writable stream you can use to push updates as execution progresses.
-- **From an agent stream**: you can also pipe an agent’s `stream` output directly into a tool’s writer, making it easy to chain agent responses into tool results without extra glue code.
+- **From within a tool**: every tool receives a `context.writer` object, which is a writable stream you can use to push updates as execution progresses.
+- **From an agent stream**: you can also pipe an agent's `stream` output directly into a tool's writer, making it easy to chain agent responses into tool results without extra glue code.
 
 By combining writable tool streams with agent streaming, you gain fine grained control over how intermediate results flow through your system and into the user experience.
 
@@ -25,16 +25,17 @@ import { Agent } from "@mastra/core/agent";
 import { testTool } from "../tools/test-tool";
 
 export const testAgent = new Agent({
-  name: "test-agent",
+  id: "test-agent",
+  name: "Test Agent",
   instructions: "You are a weather agent.",
   model: openai("gpt-4o-mini"),
   tools: { testTool },
 });
 ```
 
-### Using the `writer` argument
+### Using `context.writer`
 
-The `writer` argument is passed to a tool’s `execute` function and can be used to emit custom events, data, or values into the active stream. This enables tools to provide intermediate results or status updates while execution is still in progress.
+The `context.writer` object is available in a tool's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables tools to provide intermediate results or status updates while execution is still in progress.
 
 :::warning
 
@@ -47,17 +48,17 @@ import { createTool } from "@mastra/core/tools";
 
 export const testTool = createTool({
   // ...
-  execute: async ({ context, writer }) => {
-    const { value } = context;
+  execute: async (inputData, context) => {
+    const { value } = inputData;
 
-   await writer?.write({
+   await context?.writer?.write({
       type: "custom-event",
       status: "pending"
     });
 
     const response = await fetch(...);
 
-   await writer?.write({
+   await context?.writer?.write({
       type: "custom-event",
       status: "success"
     });
@@ -77,17 +78,17 @@ import { createTool } from "@mastra/core/tools";
 
 export const testTool = createTool({
   // ...
-  execute: async ({ context, writer }) => {
-    const { value } = context;
+  execute: async (inputData, context) => {
+    const { value } = inputData;
 
-   await writer?.custom({
+   await context?.writer?.custom({
       type: "data-tool-progress",
       status: "pending"
     });
 
     const response = await fetch(...);
 
-   await writer?.custom({
+   await context?.writer?.custom({
       type: "data-tool-progress",
       status: "success"
     });
@@ -126,13 +127,13 @@ import { z } from "zod";
 
 export const testTool = createTool({
   // ...
-  execute: async ({ context, mastra, writer }) => {
-    const { city } = context;
+  execute: async (inputData, context) => {
+    const { city } = inputData;
 
-    const testAgent = mastra?.getAgent("testAgent");
+    const testAgent = context?.mastra?.getAgent("testAgent");
     const stream = await testAgent?.stream(`What is the weather in ${city}?`);
 
-    await stream!.textStream.pipeTo(writer!);
+    await stream!.textStream.pipeTo(context?.writer!);
 
     return {
       value: await stream!.text,

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

@@ -64,7 +64,7 @@ Events written to the stream are included in the emitted chunks. These chunks ca
 ```typescript showLineNumbers copy
 const testWorkflow = mastra.getWorkflow("testWorkflow");
 
-const run = await testWorkflow.createRunAsync();
+const run = await testWorkflow.createRun();
 
 const stream = await run.streamVNext({
   inputData: {

package/.docs/raw/tools-mcp/advanced-usage.mdx

@@ -23,20 +23,20 @@ export const longRunningTool = createTool({
   id: "long-computation",
   description: "Performs a potentially long computation",
   inputSchema: z.object({ /* ... */ }),
-  execute: async ({ context }, { abortSignal }) => {
+  execute: async (inputData, context) => {
     // Example: Forwarding signal to fetch
     const response = await fetch("https://api.example.com/data", {
-      signal: abortSignal, // Pass the signal here
+      signal: context?.abortSignal, // Pass the signal here
     });
 
-    if (abortSignal?.aborted) {
+    if (context?.abortSignal?.aborted) {
       console.log("Tool execution aborted.");
       throw new Error("Aborted");
     }
 
     // Example: Checking signal during a loop
     for (let i = 0; i < 1000000; i++) {
-      if (abortSignal?.aborted) {
+      if (context?.abortSignal?.aborted) {
         console.log("Tool execution aborted during loop.");
         throw new Error("Aborted");
       }
@@ -115,6 +115,7 @@ import { vercelWeatherTool } from "../tools/vercelWeatherTool"; // Vercel AI SDK
 import { mastraTool } from "../tools/mastraTool"; // Mastra createTool tool
 
 export const mixedToolsAgent = new Agent({
+  id: "mixed-tools-agent",
   name: "Mixed Tools Agent",
   instructions: "You can use tools defined in different formats.",
   model: openai("gpt-4o-mini"),