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

package/.docs/raw/server-db/runtime-context.mdx

@@ -0,0 +1,178 @@
+---
+title: "Runtime Context | Agents | Mastra Docs"
+description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
+---
+
+import { Callout } from "nextra/components";
+
+# Runtime Context
+
+Agents, tools, and workflows can all accept `RuntimeContext` as a parameter, making request-specific values available to the underlying primitives.
+
+## When to use `RuntimeContext`
+
+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.
+
+<Callout>
+  **Note:** `RuntimeContext` 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.
+</Callout>
+
+## Setting values
+
+Pass `runtimeContext` into an agent, 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:
+
+1. **key**: The name used to identify the value.
+2. **value**: The data to associate with that key.
+
+```typescript {7,9,13,21,28} showLineNumbers
+import { RuntimeContext } from "@mastra/core/runtime-context";
+
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
+
+const runtimeContext = new RuntimeContext<UserTier>();
+
+runtimeContext.set("user-tier", "enterprise");
+
+const agent = mastra.getAgent("weatherAgent");
+await agent.generate("What's the weather in London?", {
+  runtimeContext
+})
+
+const run = await mastra.getWorkflow("weatherWorkflow").createRunAsync();
+await run.start({
+  inputData: {
+    location: "London"
+  },
+  runtimeContext
+});
+
+await weatherTool.execute({
+  context: {
+    location: "London"
+  },
+  runtimeContext
+});
+```
+
+### 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.
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { RuntimeContext } from "@mastra/core/runtime-context";
+import { testWeatherAgent } from "./agents/test-weather-agent";
+
+export const mastra = new Mastra({
+  agents: { testWeatherAgent },
+  server: {
+    middleware: [
+      async (context, next) => {
+        const country = context.req.header("CF-IPCountry");
+        const runtimeContext = context.get("runtimeContext");
+
+        runtimeContext.set("temperature-unit", country === "US" ? "fahrenheit" : "celsius");
+
+        await next();
+      }
+    ]
+  }
+});
+```
+
+> See [Middleware](../server-db/middleware.mdx) 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`.
+
+```typescript {7-8,15,18,21} filename="src/mastra/agents/weather-agent.ts" showLineNumbers
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
+
+export const weatherAgent = new Agent({
+  name: "weather-agent",
+  instructions: async ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+
+    if (userTier === "enterprise") {
+      // ...
+    }
+    // ...
+  },
+  model: ({ runtimeContext }) => {
+    // ...
+  },
+  tools: ({ runtimeContext }) => {
+    // ...
+  },
+  memory: ({ runtimeContext }) => {
+    // ...
+  },
+});
+```
+
+You can also use `runtimeContext` with other options like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
+
+> See [Agent](../../reference/agents/agent.mdx) 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`.
+
+```typescript {7-8} filename="src/mastra/workflows/weather-workflow.ts" showLineNumbers copy
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
+
+const stepOne = createStep({
+  id: "step-one",
+  execute: async ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+
+    if (userTier === "enterprise") {
+      // ...
+    }
+    // ...
+  }
+});
+```
+
+> See [createStep()](../../reference/workflows/step.mdx) 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`.
+
+```typescript {7-8} filename="src/mastra/tools/weather-tool.ts" showLineNumbers
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
+
+export const weatherTool = createTool({
+  id: "weather-tool",
+  execute: async ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+
+    if (userTier === "enterprise") {
+      // ...
+    }
+   // ...
+  }
+});
+```
+
+> See [createTool()](../../reference/tools/create-tool.mdx) for a full list of configuration options.
+
+## Related
+
+- [RuntimeContext Example](../../examples/agents/runtime-context.mdx)
+- [Tool Runtime Context](../tools-mcp/runtime-context.mdx)
+- [Server Middleware Runtime Context](../server-db/middleware.mdx)

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

@@ -18,6 +18,10 @@ By combining writable workflow streams with agent streaming, you gain fine-grain
 
 ### Using the `writer` argument
 
+<Callout type="warning">
+The writer is only available when using `streamVNext`.
+</Callout>
+
 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">
@@ -60,7 +64,7 @@ const testWorkflow = mastra.getWorkflow("testWorkflow");
 
 const run = await testWorkflow.createRunAsync();
 
-const stream = await run.stream({
+const stream = await run.streamVNext({
   inputData: {
     value: "initial data"
   }

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

@@ -56,18 +56,36 @@ When creating tools, keep tool descriptions simple and focused on **what** the t
 
 To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on [Using Tools and MCP with Agents](/docs/agents/using-tools-and-mcp#add-tools-to-an-agent).
 
-## Compatibility Layer for Tool Schemas
+## Using `RuntimeContext`
 
-Different models interpret schemas differently. Some error when certain schema properties are passed and some ignore certain schema properties but don't throw an error. Mastra adds a compatibility layer for tool schemas, ensuring tools work consistently across different model providers and that the schema constraints are respected.
+Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
-Some providers that we include this layer for:
+```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
+
+const advancedTools = () => {
+  // ...
+};
 
-- **Google Gemini & Anthropic:** Remove unsupported schema properties and append relevant constraints to the tool description.
-- **OpenAI (including reasoning models):** Strip or adapt schema fields that are ignored or unsupported, and add instructions to the description for agent guidance.
-- **DeepSeek & Meta:** Apply similar compatibility logic to ensure schema alignment and tool usability.
+const baseTools =  () => {
+  // ...
+};
 
-This approach makes tool usage more reliable and model-agnostic for both custom and MCP tools.
+export const testTool = createTool({
+  // ...
+  execute: async ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+
+    return userTier === "enterprise"
+      ? advancedTools
+      : baseTools;
+  }
+});
+```
 
+> See [Runtime Context](../server-db/runtime-context.mdx) for more information.
 
 ## Testing tools locally
 There are two ways to run and test tools.

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

@@ -83,7 +83,11 @@ export const testWorkflow = createWorkflow({
   }),
   outputSchema: z.object({
     output: z.string()
-  })
+  }),
+  options: {
+    // enables runtime validation of inputs and applies zod default values.
+    validateInputs: true, 
+  }
 })
   .then(step1)
   .commit();
@@ -171,6 +175,29 @@ export const mastra = new Mastra({
 });
 ```
 
+## Using `RuntimeContext`
+
+Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+
+```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers
+export type UserTier = {
+  "user-tier": "enterprise" | "pro";
+};
+
+const stepOne = createStep({
+  // ...
+  execute: async ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
+
+    const maxResults = userTier === "enterprise"
+      ? 1000
+      : 50;
+
+    return { maxResults };
+  }
+});
+```
+
 ## Testing workflows locally
 There are two ways to run and test workflows.
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 0.13.30-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`f59fc1e`](https://github.com/mastra-ai/mastra/commit/f59fc1e406b8912e692f6bff6cfd4754cc8d165c)]:
+  - @mastra/core@0.21.0-alpha.2
+
+## 0.13.30-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`1ed9670`](https://github.com/mastra-ai/mastra/commit/1ed9670d3ca50cb60dc2e517738c5eef3968ed27), [`158381d`](https://github.com/mastra-ai/mastra/commit/158381d39335be934b81ef8a1947bccace492c25), [`fb703b9`](https://github.com/mastra-ai/mastra/commit/fb703b9634eeaff1a6eb2b5531ce0f9e8fb04727), [`37a2314`](https://github.com/mastra-ai/mastra/commit/37a23148e0e5a3b40d4f9f098b194671a8a49faf), [`05a9dee`](https://github.com/mastra-ai/mastra/commit/05a9dee3d355694d28847bfffb6289657fcf7dfa), [`e3c1077`](https://github.com/mastra-ai/mastra/commit/e3c107763aedd1643d3def5df450c235da9ff76c), [`1bccdb3`](https://github.com/mastra-ai/mastra/commit/1bccdb33eb90cbeba2dc5ece1c2561fb774b26b6), [`5ef944a`](https://github.com/mastra-ai/mastra/commit/5ef944a3721d93105675cac2b2311432ff8cc393), [`d6b186f`](https://github.com/mastra-ai/mastra/commit/d6b186fb08f1caf1b86f73d3a5ee88fb999ca3be), [`65493b3`](https://github.com/mastra-ai/mastra/commit/65493b31c36f6fdb78f9679f7e1ecf0c250aa5ee), [`a998b8f`](https://github.com/mastra-ai/mastra/commit/a998b8f858091c2ec47683e60766cf12d03001e4), [`8a37bdd`](https://github.com/mastra-ai/mastra/commit/8a37bddb6d8614a32c5b70303d583d80c620ea61)]:
+  - @mastra/core@0.21.0-alpha.1
+
 ## 0.13.30-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.30-alpha.0",
+  "version": "0.13.30-alpha.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@mastra/core": "0.21.0-alpha.0",
+    "@mastra/core": "0.21.0-alpha.2",
     "@mastra/mcp": "^0.13.5-alpha.0"
   },
   "devDependencies": {
@@ -42,7 +42,7 @@
     "@types/node": "^20.19.0",
     "@types/turndown": "^5.0.5",
     "@wong2/mcp-cli": "^1.10.0",
-    "cross-env": "^7.0.3",
+    "cross-env": "^10.1.0",
     "eslint": "^9.36.0",
     "hono": "^4.9.7",
     "tsup": "^8.5.0",
@@ -50,7 +50,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@internal/lint": "0.0.48",
-    "@mastra/core": "0.21.0-alpha.0"
+    "@mastra/core": "0.21.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/raw/agents/runtime-context.mdx

@@ -1,106 +0,0 @@
----
-title: "Runtime Context | Agents | Mastra Docs"
-description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
----
-
-# Runtime Context
-
-Agents use `RuntimeContext` to access request-specific values sent alongside user messages. These values let a single agent change its behavior, functionality, model, tools, or memory usage based on the needs of each request.
-
-![Agents Runtime Context](/image/agents/agents-runtime-context.jpg)
-
-## When to use `RuntimeContext`
-
-Use `RuntimeContext` when an agent's behavior should change based on the request or environment. For example, you might switch models or storage providers based on user details, or adjust instructions or tool selection based on the user's language.
-
-## Configuring agents with `RuntimeContext`
-
-You can access the `runtimeContext` argument from any of the agent’s supported parameters. These functions can be sync or `async`, allowing you to use context values to fetch data, apply logic, or adjust behavior at runtime.
-
-```typescript {3,6,9,12} filename="src/dynamic-agent.ts" showLineNumbers copy
-export const dynamicAgent = new Agent({
-  name: "dynamic-agent",
-  instructions: async ({ runtimeContext }) => {
-    // ...
-  },
-  model: ({ runtimeContext }) => {
-    // ...
-  },
-  tools: ({ runtimeContext }) => {
-    // ...
-  },
-  memory: ({ runtimeContext }) => {
-    // ...
-  },
-});
-```
-
-You can also use `runtimeContext` with other parameters like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
-
-> See [Agent](../../reference/agents/agent.mdx) for a full list of configuration options.
-
-## Setting values
-
-To set variables in `runtimeContext`, create a new instance using `new RuntimeContext()` and call `.set()` to define the values you want to include.
-
-The `.set()` method takes two arguments:
-
-1. **key**: The name used to identify the value.
-2. **value**: The data to associate with that key.
-
-After setting the values, pass the `runtimeContext` to `.generate()` or `.stream()` to make them available to the agent.
-
-```typescript {8,11} filename="src/test-dynamic-agent.ts" showLineNumbers copy
-import { mastra } from "./mastra";
-import { RuntimeContext } from "@mastra/core/runtime-context";
-import { UserTier } from "./mastra/agents/dynamic-agent"
-
-const agent = mastra.getAgent("dynamicAgent");
-
-const runtimeContext = new RuntimeContext<UserTier>();
-runtimeContext.set("user-tier", "enterprise");
-
-const response = await agent.generate("Help plan my day.", {
-  runtimeContext
-});
-```
-
-## Accessing values
-
-The example below accesses a `user-tier` value from `runtimeContext` to determine which model and instructions to use. The context is typed to provide safety and autocomplete when working with `.get()` and `.set()`.
-
-```typescript {12,19} filename="src/mastra/agents/dynamic-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { RuntimeContext } from "@mastra/core/runtime-context";
-
-export type UserTier = {
-  "user-tier": "enterprise" | "pro";
-};
-
-export const dynamicAgent = new Agent({
-  name: "dynamic-agent",
-  instructions: async ({ runtimeContext }: { runtimeContext: RuntimeContext<UserTier> }) => {
-    const userTier = runtimeContext.get("user-tier");
-
-    const result = await db.query("SELECT instructions FROM config WHERE tier = ?", [userTier]);
-
-    return result[0].instructions;
-  },
-  model: ({ runtimeContext }: { runtimeContext: RuntimeContext<UserTier> }) => {
-    const userTier = runtimeContext.get("user-tier");
-
-    return userTier === "enterprise"
-      ? openai("gpt-4o-mini")
-      : openai("gpt-4.1-nano");
-  }
-});
-```
-
-For a complete implementation example that demonstrates all runtime context capabilities including dynamic model selection, tools, memory, input/output processors, and quality scoring based on user subscription tiers, see our [Runtime Context Example](../../examples/agents/runtime-context.mdx).
-
-## Related
-
-- [Runtime Context Example](../../examples/agents/runtime-context.mdx)
-- [Tool Runtime Context](../tools-mcp/runtime-context.mdx)
-- [Server Middleware Runtime Context](../server-db/middleware.mdx)