@mastra/mcp-docs-server 1.1.28-alpha.3 → 1.1.28

package/.docs/docs/agents/structured-output.md

@@ -8,7 +8,7 @@ Use structured output when you need an agent to return a data object rather than
 
 ## Define schemas
 
-Agents can return structured data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). Zod is recommended because it provides TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
+Agents can return structured data by defining the expected output with either [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) or [JSON Schema](https://json-schema.org/). Libraries like Zod are recommended because they provide TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
 
 **Zod**:
 
@@ -31,6 +31,49 @@ const response = await testAgent.generate('Help me plan my day.', {
 console.log(response.object)
 ```
 
+**Valibot**:
+
+Define the `output` shape using [Valibot](https://valibot.dev/):
+
+```typescript
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: toStandardJsonSchema(
+      v.array(
+        v.object({
+          name: v.string(),
+          activities: v.array(v.string()),
+        }),
+      ),
+    ),
+  },
+})
+
+console.log(response.object)
+```
+
+**ArkType**:
+
+Define the `output` shape using [ArkType](https://arktype.io/):
+
+```typescript
+import { type } from 'arktype'
+
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: type({
+      name: 'string',
+      activities: 'string[]',
+    }).array(),
+  },
+})
+
+console.log(response.object)
+```
+
 **JSON Schema**:
 
 You can also use JSON Schema to define your output structure:

package/.docs/docs/agents/using-tools.md

@@ -57,6 +57,78 @@ export const weatherAgent = new Agent({
 })
 ```
 
+## Define schemas
+
+You can define the tool's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
+
+**Zod**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    weather: z.string(),
+  }),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
+**Valibot**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: toStandardJsonSchema(
+    v.object({
+      location: v.string(),
+    }),
+  ),
+  outputSchema: toStandardJsonSchema(
+    v.object({
+      weather: v.string(),
+    }),
+  ),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
+**ArkType**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { type } from 'arktype'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: type({
+    location: 'string',
+  }),
+  outputSchema: type({
+    weather: 'string',
+  }),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
 ## Multiple tools
 
 An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.

package/.docs/docs/browser/agent-browser.md

@@ -51,6 +51,7 @@ const browser = new AgentBrowser({
 
 export const browserAgent = new Agent({
   id: 'browser-agent',
+  name: 'Browser Agent',
   model: 'openai/gpt-5.4',
   browser,
   instructions: `You are a web automation assistant.
@@ -62,6 +63,8 @@ When interacting with pages:
 })
 ```
 
+> **Note:** For local launches (the default), AgentBrowser requires a Chromium binary installed via Playwright. This is normally downloaded automatically when you install `@mastra/agent-browser`. If launching the browser fails with `"browser executable is missing"`, run `npx playwright install chromium`. If you connect to a remote browser using the [`cdpUrl`](https://mastra.ai/reference/browser/agent-browser) option, no local Chromium is needed.
+
 ## Element refs
 
 AgentBrowser uses accessibility tree refs to identify elements. When an agent calls `browser_snapshot`, it receives a text representation of the page with refs like `@e1`, `@e2`, etc. The agent then uses these refs with other tools to interact with elements.

package/.docs/docs/browser/overview.md

@@ -70,6 +70,7 @@ import { browser } from '../browsers'
 
 export const webAgent = new Agent({
   id: 'web-agent',
+  name: 'Web Agent',
   model: 'openai/gpt-5.4',
   browser,
   instructions:

package/.docs/docs/browser/stagehand.md

@@ -52,6 +52,7 @@ const browser = new StagehandBrowser({
 
 export const stagehandAgent = new Agent({
   id: 'stagehand-agent',
+  name: 'Stagehand Agent',
   model: 'openai/gpt-5.4',
   browser,
   instructions: `You are a web automation assistant.

package/.docs/docs/evals/custom-scorers.md

@@ -402,7 +402,7 @@ Defines how the LLM should analyze the input and what structured output to retur
 The analysis step uses a prompt object to:
 
 - Provide a clear description of the analysis task
-- Define expected output structure with Zod schema (both boolean result and list of gluten sources)
+- Define expected output structure with a Standard JSON Schema (both boolean result and list of gluten sources)
 - Generate dynamic prompts based on the input content
 
 ### Score Generation

package/.docs/docs/evals/datasets/overview.md

@@ -68,7 +68,7 @@ console.log(dataset.id) // auto-generated UUID
 
 ### Defining schemas
 
-You can enforce the shape of `input` and `groundTruth` by passing Zod schemas. Mastra converts them to JSON Schema at creation time:
+You can enforce the shape of `input` and `groundTruth` by passing a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) when creating the dataset:
 
 ```typescript
 import { z } from 'zod'

package/.docs/docs/memory/working-memory.md

@@ -208,7 +208,7 @@ const paragraphMemory = new Memory({
 
 ## Structured working memory
 
-Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
+Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 
 **Important:** You must specify either `template` or `schema`, but not both.
 

package/.docs/docs/server/request-context.md

@@ -308,7 +308,7 @@ for (const [key, value] of ctx.entries()) {
 
 ## Schema validation
 
-Use `requestContextSchema` to define a Zod schema that validates request context values at runtime. This catches missing or invalid context values early, provides clear error messages, and gives you type inference within your component.
+Use `requestContextSchema` to define a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) that validates request context values at runtime. This catches missing or invalid context values early, provides clear error messages, and gives you type inference within your component.
 
 ### Agent schema validation
 

package/.docs/docs/workflows/agents-and-tools.md

@@ -104,7 +104,7 @@ export const testWorkflow = createWorkflow({})
   .commit()
 ```
 
-The `structuredOutput.schema` option accepts any Zod schema. The agent will generate output conforming to this schema, and the step's `outputSchema` will be automatically set to match.
+The `structuredOutput.schema` option accepts any Standard JSON Schema. The agent will generate output conforming to this schema, and the step's `outputSchema` will be automatically set to match.
 
 > **Info:** Visit [Structured Output](https://mastra.ai/docs/agents/structured-output) for more options like error handling strategies and streaming with structured output.
 

package/.docs/docs/workflows/overview.md

@@ -14,18 +14,21 @@ Use workflows for tasks that are clearly defined upfront and involve multiple st
 
 Mastra workflows operate using these principles:
 
-- Defining **steps** with `createStep`, specifying input/output schemas and business logic.
-- Composing **steps** with `createWorkflow` to define the execution flow.
+- Defining **steps** with [`createStep`](https://mastra.ai/reference/workflows/step), specifying input/output schemas and business logic.
+- Composing **steps** with [`createWorkflow`](https://mastra.ai/reference/workflows/workflow) to define the execution flow.
 - Running **workflows** to execute the entire sequence, with built-in support for suspension, resumption, and streaming results.
 
 ## Creating a workflow step
 
-Steps are the building blocks of workflows. Create a step using `createStep()` with `inputSchema` and `outputSchema` to define the data it accepts and returns.
+Steps are the building blocks of workflows. Create a step using `createStep()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. You can define both schemas using [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.).
 
 The `execute` function defines what the step does. Use it to call functions in your codebase, external APIs, agents, or tools.
 
+**Zod**:
+
 ```typescript
 import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
 
 const step1 = createStep({
   id: 'step-1',
@@ -45,6 +48,59 @@ const step1 = createStep({
 })
 ```
 
+**Valibot**:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: toStandardJsonSchema(
+    v.object({
+      message: v.string(),
+    }),
+  ),
+  outputSchema: toStandardJsonSchema(
+    v.object({
+      formatted: v.string(),
+    }),
+  ),
+  execute: async ({ inputData }) => {
+    const { message } = inputData
+
+    return {
+      formatted: message.toUpperCase(),
+    }
+  },
+})
+```
+
+**ArkType**:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { type } from 'arktype'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: type({
+    message: 'string',
+  }),
+  outputSchema: type({
+    formatted: 'string',
+  }),
+  execute: async ({ inputData }) => {
+    const { message } = inputData
+
+    return {
+      formatted: message.toUpperCase(),
+    }
+  },
+})
+```
+
 > **Info:** Visit [`Step`](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
 
 ### Using agents and tools
@@ -53,7 +109,9 @@ Workflow steps can also call registered agents or import and execute tools direc
 
 ## Creating a workflow
 
-Create a workflow using `createWorkflow()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. Add steps using `.then()` and complete the workflow with `.commit()`.
+Create a workflow using `createWorkflow()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. You can define both schemas using [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). Add steps using `.then()` and complete the workflow with `.commit()`.
+
+**Zod**:
 
 ```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -74,6 +132,49 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
+**Valibot**:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import * as v from "valibot";
+import { toStandardJsonSchema } from "@valibot/to-json-schema";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: toStandardJsonSchema(v.object({
+    message: v.string()
+  })),
+  outputSchema: toStandardJsonSchema(v.object({
+    output: v.string()
+  }))
+})
+  .then(step1)
+  .commit();
+```
+
+**ArkType**:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { type } from "arktype";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: type({
+    message: "string"
+  }),
+  outputSchema: type({
+    output: "string"
+  })
+})
+  .then(step1)
+  .commit();
+```
+
 > **Info:** Visit [Workflow Class](https://mastra.ai/reference/workflows/workflow) for a full list of configuration options.
 
 ### Understanding control flow

package/.docs/docs/workspace/filesystem.md

@@ -93,6 +93,58 @@ const workspace = new Workspace({
 
 When `contained` is `false`, absolute paths are treated as real filesystem paths with no restriction.
 
+## Dynamic filesystem
+
+The `filesystem` option accepts a resolver function instead of a static instance. The resolver receives `requestContext` and returns a filesystem per request, allowing a single workspace to serve different filesystems based on the caller's identity, role, or tenant.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: ({ requestContext }) => {
+    const role = requestContext.get('agent-role') || 'guest'
+    return new LocalFilesystem({
+      basePath: `/workspaces/${role}`,
+      readOnly: role !== 'admin',
+    })
+  },
+})
+
+const agent = new Agent({
+  id: 'multi-role-agent',
+  model: 'openai/gpt-4o',
+  workspace,
+})
+```
+
+Each request resolves its own filesystem at tool execution time:
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+// Admin request — reads and writes from /workspaces/admin/
+const adminCtx = new RequestContext([['agent-role', 'admin']])
+await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })
+
+// Viewer request — reads from /workspaces/viewer/, writes are blocked
+const viewerCtx = new RequestContext([['agent-role', 'viewer']])
+await agent.generate('Read info.txt', { requestContext: viewerCtx })
+```
+
+The resolver can also be asynchronous, for example to look up configuration from a database:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: async ({ requestContext }) => {
+    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
+    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
+  },
+})
+```
+
+> **Note:** `filesystem` and `mounts` are mutually exclusive. You cannot use a resolver function together with `mounts` in the same workspace.
+
 ## Read-only mode
 
 To prevent agents from modifying files, enable read-only mode:
@@ -106,7 +158,9 @@ const workspace = new Workspace({
 })
 ```
 
-When read-only, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) aren't added to the agent's toolset. The agent can still read and list files.
+With a static filesystem, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded from the agent's toolset entirely. The agent can still read and list files.
+
+When using a [dynamic filesystem](#dynamic-filesystem), write tools are always included because `readOnly` isn't known until the resolver runs. Instead, write operations are blocked at runtime — the tool returns an error if the resolved filesystem is read-only.
 
 ## Mounts and `CompositeFilesystem`
 

package/.docs/docs/workspace/overview.md

@@ -153,15 +153,34 @@ const workspace = new Workspace({
 
 The agent receives the `execute_command` tool.
 
+### Dynamic filesystem (per-request)
+
+Pass a resolver function to `filesystem` to return a different filesystem per request. This is useful for multi-tenant applications or multi-role agents where each request needs a different storage root or different permissions.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: ({ requestContext }) => {
+    const role = requestContext.get('agent-role') || 'guest'
+    return new LocalFilesystem({
+      basePath: `/workspaces/${role}`,
+      readOnly: role !== 'admin',
+    })
+  },
+})
+```
+
+One workspace instance serves all requests. The resolver runs at tool execution time, so each request gets its own filesystem. See [dynamic filesystem](https://mastra.ai/docs/workspace/filesystem) for details.
+
 ### Which pattern should I use?
 
-| Scenario                                              | Pattern                                               |
-| ----------------------------------------------------- | ----------------------------------------------------- |
-| Local development with files and commands             | `filesystem` + `sandbox` (both local, same directory) |
-| Cloud storage accessible inside a cloud sandbox       | `mounts` + `sandbox`                                  |
-| Multiple cloud providers in one sandbox               | `mounts` + `sandbox` (one mount per provider)         |
-| Agent reads/writes files, no command execution needed | `filesystem` only                                     |
-| Agent runs commands, no file tools needed             | `sandbox` only                                        |
+| Scenario                                                  | Pattern                                               |
+| --------------------------------------------------------- | ----------------------------------------------------- |
+| Local development with files and commands                 | `filesystem` + `sandbox` (both local, same directory) |
+| Cloud storage accessible inside a cloud sandbox           | `mounts` + `sandbox`                                  |
+| Multiple cloud providers in one sandbox                   | `mounts` + `sandbox` (one mount per provider)         |
+| Agent reads/writes files, no command execution needed     | `filesystem` only                                     |
+| Agent runs commands, no file tools needed                 | `sandbox` only                                        |
+| Multi-role or multi-tenant agent with per-request storage | `filesystem` with resolver function                   |
 
 ## Tool configuration
 

package/.docs/reference/agents/agent.md

@@ -132,7 +132,7 @@ export const agent = new Agent({
 
 **maxProcessorRetries** (`number`): Maximum number of times a processor can request retrying the LLM step.
 
-**requestContextSchema** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.
+**requestContextSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.
 
 ## Returns
 

package/.docs/reference/agents/generate.md

@@ -184,7 +184,7 @@ const response = await agent.generate('Help me organize my day', {
 
 **options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Options to fine tune your structured output generation.
 
-**options.structuredOutput.schema** (`z.ZodSchema<S>`): Zod schema defining the expected output structure.
+**options.structuredOutput.schema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the expected output structure.
 
 **options.structuredOutput.model** (`MastraLanguageModel`): Language model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured output
 

package/.docs/reference/browser/agent-browser.md

@@ -17,7 +17,8 @@ const browser = new AgentBrowser({
 })
 
 export const browserAgent = new Agent({
-  name: 'browser-agent',
+  id: 'browser-agent',
+  name: 'Browser Agent',
   instructions: `You can browse the web. Use browser_snapshot to see the page structure,
 then interact with elements using their refs (e.g., @e5).`,
   model: 'openai/gpt-5.4',

package/.docs/reference/browser/mastra-browser.md

@@ -21,7 +21,8 @@ const browser = new AgentBrowser({
 })
 
 export const browserAgent = new Agent({
-  name: 'browser-agent',
+  id: 'browser-agent',
+  name: 'Browser Agent',
   instructions: 'You can browse the web to find information.',
   model: 'openai/gpt-5.4',
   browser,

package/.docs/reference/browser/stagehand-browser.md

@@ -17,7 +17,8 @@ const browser = new StagehandBrowser({
 })
 
 export const browserAgent = new Agent({
-  name: 'browser-agent',
+  id: 'browser-agent',
+  name: 'Browser Agent',
   instructions: `You can browse the web using natural language.
 Use stagehand_act to perform actions like "click the login button".
 Use stagehand_extract to get data from pages.`,
@@ -265,11 +266,6 @@ const browser = new StagehandBrowser({
 })
 ```
 
-Supported providers:
-
-- OpenAI: `"openai/gpt-5.4"`, `"openai/gpt-5.4-mini"`
-- Anthropic: `"anthropic/claude-3-5-sonnet-20241022"`
-
 ## AgentBrowser vs StagehandBrowser
 
 | Aspect          | AgentBrowser               | StagehandBrowser      |

package/.docs/reference/datasets/create.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Creates a new dataset. Zod schemas passed as `inputSchema` or `groundTruthSchema` are automatically converted to JSON Schema.
+Creates a new dataset. Use Standard JSON Schema (Zod, Valibot, ArkType, etc.) for defining schemas.
 
 ## Usage example
 
@@ -21,7 +21,7 @@ const dataset = await mastra.datasets.create({
   metadata: { team: 'ml' },
 })
 
-// Create with Zod schemas
+// Create with Zod schema (library that supports Standard JSON Schema)
 const typedDataset = await mastra.datasets.create({
   name: 'Typed QA set',
   inputSchema: z.object({
@@ -40,9 +40,9 @@ const typedDataset = await mastra.datasets.create({
 
 **description** (`string`): Description of the dataset.
 
-**inputSchema** (`unknown`): JSON Schema or Zod schema for item inputs. Zod schemas are auto-converted.
+**inputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for item inputs.
 
-**groundTruthSchema** (`unknown`): JSON Schema or Zod schema for item ground truths. Zod schemas are auto-converted.
+**groundTruthSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for item ground truths.
 
 **metadata** (`Record<string, unknown>`): Arbitrary metadata.
 

package/.docs/reference/datasets/update.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Updates dataset metadata, name, description, and/or schemas. Zod schemas are automatically converted to JSON Schema.
+Updates dataset metadata, name, description, and/or schemas. Use Standard JSON Schema (Zod, Valibot, ArkType, etc.) for defining schemas.
 
 ## Usage example
 
@@ -22,7 +22,7 @@ const updated = await dataset.update({
   description: 'Revised evaluation set',
 })
 
-// Update with Zod schema (auto-converted to JSON Schema)
+// Update with Zod schema (library that supports Standard JSON Schema)
 const updated2 = await dataset.update({
   inputSchema: z.object({
     question: z.string(),
@@ -39,9 +39,9 @@ const updated2 = await dataset.update({
 
 **metadata** (`Record<string, unknown>`): Updated metadata.
 
-**inputSchema** (`unknown`): JSON Schema or Zod schema for item inputs.
+**inputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for item inputs.
 
-**groundTruthSchema** (`unknown`): JSON Schema or Zod schema for item ground truths.
+**groundTruthSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for item ground truths.
 
 ## Returns
 

package/.docs/reference/evals/create-scorer.md

@@ -164,7 +164,7 @@ The method can return any value. The returned value will be available to subsequ
 
 **description** (`string`): Description of what this preprocessing step does.
 
-**outputSchema** (`ZodSchema`): Zod schema for the expected output of the preprocess step.
+**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for the expected output of the preprocess step.
 
 **createPrompt** (`function`): Function: ({ run, results }) => string. Returns the prompt for the LLM.
 
@@ -193,7 +193,7 @@ The method can return any value. The returned value will be available to subsequ
 
 **description** (`string`): Description of what this analysis step does.
 
-**outputSchema** (`ZodSchema`): Zod schema for the expected output of the analyze step.
+**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for the expected output of the analyze step.
 
 **createPrompt** (`function`): Function: ({ run, results }) => string. Returns the prompt for the LLM.
 
@@ -224,7 +224,7 @@ The method must return a numerical score.
 
 **description** (`string`): Description of what this scoring step does.
 
-**outputSchema** (`ZodSchema`): Zod schema for the expected output of the generateScore step.
+**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for the expected output of the generateScore step.
 
 **createPrompt** (`function`): Function: ({ run, results }) => string. Returns the prompt for the LLM.
 

package/.docs/reference/harness/harness-class.md

@@ -44,7 +44,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **storage** (`MastraCompositeStore`): Storage backend for persistence (threads, messages, state).
 
-**stateSchema** (`z.ZodObject`): Zod schema defining the shape of harness state. Used for validation and extracting defaults.
+**stateSchema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the shape of harness state. Used for validation and extracting defaults.
 
 **initialState** (`Partial<z.infer<TState>>`): Initial state values. Must conform to the schema if provided.
 

package/.docs/reference/streaming/agents/stream.md

@@ -88,7 +88,7 @@ const stream = await agent.stream('message for agent')
 
 **options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Options to fine tune your structured output generation.
 
-**options.structuredOutput.schema** (`z.ZodSchema<S>`): Zod schema defining the expected output structure.
+**options.structuredOutput.schema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the expected output structure.
 
 **options.structuredOutput.model** (`MastraLanguageModel`): Language model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured output
 

package/.docs/reference/tools/create-tool.md

@@ -27,6 +27,78 @@ export const tool = createTool({
 })
 ```
 
+## Define schemas
+
+You can define the tool's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
+
+**Zod**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    weather: z.string(),
+  }),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
+**Valibot**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: toStandardJsonSchema(
+    v.object({
+      location: v.string(),
+    }),
+  ),
+  outputSchema: toStandardJsonSchema(
+    v.object({
+      weather: v.string(),
+    }),
+  ),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
+**ArkType**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { type } from 'arktype'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: type({
+    location: 'string',
+  }),
+  outputSchema: type({
+    weather: 'string',
+  }),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
 ## Example with strict tool inputs
 
 Set `strict: true` when you want Mastra to ask supported model providers to generate tool arguments that exactly match the tool schema.
@@ -144,23 +216,23 @@ export const weatherTool = createTool({
 
 **description** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
 
-**inputSchema** (`Zod schema`): A Zod schema defining the expected input parameters for the tool's \`execute\` function.
+**inputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected input parameters for the tool's \`execute\` function.
 
-**outputSchema** (`Zod schema`): A Zod schema defining the expected output structure of the tool's \`execute\` function.
+**outputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected output structure of the tool's \`execute\` function.
 
 **strict** (`boolean`): When true, Mastra enables strict tool input generation on model adapters that support it. This helps supported providers return arguments that match the tool schema more closely.
 
 **toModelOutput** (`(output: TSchemaOut) => unknown`): Optional function that transforms the tool's \`execute\` output before it is sent back to the model. Use this to return \`text\`, \`json\`, or \`content\`-shaped outputs (including multimodal parts like images/files) to the model while still keeping the full raw output in your application code.
 
-**suspendSchema** (`Zod schema`): A Zod schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
+**suspendSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
 
-**resumeSchema** (`Zod schema`): A Zod schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.
+**resumeSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.
 
 **requireApproval** (`boolean`): When true, the tool requires explicit approval before execution. The agent will emit a \`tool-call-approval\` chunk and pause until approved or declined.
 
 **mcp** (`MCPToolProperties`): MCP-specific properties for tools exposed via Model Context Protocol. Includes \`annotations\` (tool behavior hints like \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, \`openWorldHint\`) and \`\_meta\` (arbitrary metadata passed through to MCP clients).
 
-**requestContextSchema** (`Zod schema`): A Zod schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
+**requestContextSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
 
 **execute** (`function`): The function that contains the tool's logic. It receives two parameters: the validated input data (first parameter) and an optional execution context object (second parameter) containing \`requestContext\`, \`tracingContext\`, \`abortSignal\`, and other execution metadata.
 

package/.docs/reference/workflows/step.md

@@ -26,6 +26,87 @@ const step1 = createStep({
 })
 ```
 
+## Define schemas
+
+You can define the step's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
+
+**Zod**:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: z.object({
+    message: z.string(),
+  }),
+  outputSchema: z.object({
+    formatted: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const { message } = inputData
+
+    return {
+      formatted: message.toUpperCase(),
+    }
+  },
+})
+```
+
+**Valibot**:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: toStandardJsonSchema(
+    v.object({
+      message: v.string(),
+    }),
+  ),
+  outputSchema: toStandardJsonSchema(
+    v.object({
+      formatted: v.string(),
+    }),
+  ),
+  execute: async ({ inputData }) => {
+    const { message } = inputData
+
+    return {
+      formatted: message.toUpperCase(),
+    }
+  },
+})
+```
+
+**ArkType**:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { type } from 'arktype'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: type({
+    message: 'string',
+  }),
+  outputSchema: type({
+    formatted: 'string',
+  }),
+  execute: async ({ inputData }) => {
+    const { message } = inputData
+
+    return {
+      formatted: message.toUpperCase(),
+    }
+  },
+})
+```
+
 ## Creating steps from agents
 
 You can create a step directly from an agent. The step will use the agent's name as its ID.
@@ -60,7 +141,7 @@ const agentStep = createStep(testAgent, {
 
 ### Agent step options
 
-**structuredOutput** (`{ schema: z.ZodType<any> }`): When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.
+**structuredOutput** (`{ schema: StandardJSONSchemaV1 }`): When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.
 
 **onFinish** (`(result: AgentResult) => void`): Callback invoked when the agent completes generation.
 
@@ -70,17 +151,17 @@ const agentStep = createStep(testAgent, {
 
 **description** (`string`): Optional description of what the step does
 
-**inputSchema** (`z.ZodType<any>`): Zod schema defining the input structure
+**inputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the input structure
 
-**outputSchema** (`z.ZodType<any>`): Zod schema defining the output structure
+**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the output structure
 
-**resumeSchema** (`z.ZodType<any>`): Optional Zod schema for resuming the step
+**resumeSchema** (`StandardJSONSchemaV1`): Optional Standard JSON Schema for resuming the step
 
-**suspendSchema** (`z.ZodType<any>`): Optional Zod schema for suspending the step
+**suspendSchema** (`StandardJSONSchemaV1`): Optional Standard JSON Schema for suspending the step
 
-**stateSchema** (`z.ZodObject<any>`): Optional Zod schema for the step state. Automatically injected when using Mastra's state system. The stateSchema must be a subset of the workflow's stateSchema. If not specified, type is 'any'.
+**stateSchema** (`StandardJSONSchemaV1`): Optional Standard JSON Schema for the step state. Automatically injected when using Mastra's state system. The stateSchema must be a subset of the workflow's stateSchema. If not specified, type is 'any'.
 
-**requestContextSchema** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated before the step's execute() runs, failing the step if validation fails.
+**requestContextSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for validating request context values. When provided, the context is validated before the step's execute() runs, failing the step if validation fails.
 
 **execute** (`(params: ExecuteParams) => Promise<any>`): Async function containing step logic
 

package/.docs/reference/workflows/workflow.md

@@ -19,17 +19,85 @@ export const workflow = createWorkflow({
 })
 ```
 
+## Define schemas
+
+You can define the workflow's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
+
+**Zod**:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  })
+})
+  .then(step1)
+  .commit();
+```
+
+**Valibot**:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import * as v from "valibot";
+import { toStandardJsonSchema } from "@valibot/to-json-schema";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: toStandardJsonSchema(v.object({
+    message: v.string()
+  })),
+  outputSchema: toStandardJsonSchema(v.object({
+    output: v.string()
+  }))
+})
+  .then(step1)
+  .commit();
+```
+
+**ArkType**:
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { type } from "arktype";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: type({
+    message: "string"
+  }),
+  outputSchema: type({
+    output: "string"
+  })
+})
+  .then(step1)
+  .commit();
+```
+
 ## Constructor parameters
 
 **id** (`string`): Unique identifier for the workflow
 
-**inputSchema** (`z.ZodType<any>`): Zod schema defining the input structure for the workflow
+**inputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the input structure for the workflow
 
-**outputSchema** (`z.ZodType<any>`): Zod schema defining the output structure for the workflow
+**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema defining the output structure for the workflow
 
-**stateSchema** (`z.ZodObject<any>`): Optional Zod schema for the workflow state. Automatically injected when using Mastra's state system. If not specified, type is 'any'.
+**stateSchema** (`StandardJSONSchemaV1`): Optional Standard JSON Schema for the workflow state. Automatically injected when using Mastra's state system. If not specified, type is 'any'.
 
-**requestContextSchema** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated at the start of run.start(), throwing an error if validation fails.
+**requestContextSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for validating request context values. When provided, the context is validated at the start of run.start(), throwing an error if validation fails.
 
 **options** (`WorkflowOptions`): Optional options for the workflow
 

package/.docs/reference/workspace/workspace-class.md

@@ -29,7 +29,7 @@ const workspace = new Workspace({
 
 **name** (`string`): Human-readable name (Default: `workspace-{id}`)
 
-**filesystem** (`WorkspaceFilesystem`): Filesystem provider instance (e.g., LocalFilesystem)
+**filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives \`requestContext\` and returns a filesystem per request. See \[dynamic filesystem]\(/docs/workspace/filesystem#dynamic-filesystem).
 
 **sandbox** (`WorkspaceSandbox`): Sandbox provider instance (e.g., LocalSandbox)
 
@@ -122,7 +122,7 @@ Tool names must be unique across all workspace tools. Setting a custom name that
 
 **status** (`WorkspaceStatus`): 'pending' | 'initializing' | 'ready' | 'paused' | 'error' | 'destroying' | 'destroyed'
 
-**filesystem** (`WorkspaceFilesystem | undefined`): The filesystem provider
+**filesystem** (`WorkspaceFilesystem | undefined`): The static filesystem provider. Returns \`undefined\` when a resolver function is configured — use \`hasFilesystemConfig()\` to check availability.
 
 **sandbox** (`WorkspaceSandbox | undefined`): The sandbox provider
 
@@ -251,6 +251,37 @@ workspace.setToolsConfig(undefined)
 
 **config** (`WorkspaceToolsConfig | undefined`): New tool configuration to apply. Pass undefined to reset to defaults.
 
+### Dynamic filesystem
+
+#### `hasFilesystemConfig()`
+
+Check whether a filesystem is configured, either as a static instance or a resolver function. Use this instead of checking `workspace.filesystem` directly, because a resolver-based workspace returns `undefined` from the `filesystem` property.
+
+```typescript
+if (workspace.hasFilesystemConfig()) {
+  // Filesystem tools are available
+}
+```
+
+**Returns:** `boolean`
+
+#### `resolveFilesystem({ requestContext })`
+
+Resolve the filesystem for a given request context. When a resolver function is configured, calls it with the provided `requestContext`. When a static filesystem is configured, returns it directly. Returns `undefined` if no filesystem is configured.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const ctx = new RequestContext([['agent-role', 'admin']])
+const fs = await workspace.resolveFilesystem({ requestContext: ctx })
+```
+
+**Parameters:**
+
+**requestContext** (`RequestContext`): The request context to pass to the resolver function.
+
+**Returns:** `Promise<WorkspaceFilesystem | undefined>`
+
 ## Agent tools
 
 A workspace provides tools to agents based on what's configured.
@@ -270,7 +301,7 @@ Added when a filesystem is configured:
 | `mastra_workspace_mkdir`      | Create a directory. Creates parent directories automatically if they don't exist.                                                                          |
 | `mastra_workspace_grep`       | Search file contents using regex patterns. Supports glob filtering, context lines, and case-insensitive search.                                            |
 
-Write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded when the filesystem is in read-only mode.
+With a static filesystem, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded when the filesystem is in read-only mode. With a [dynamic filesystem](https://mastra.ai/docs/workspace/filesystem), write tools are always included and read-only is enforced at runtime.
 
 ### Sandbox tools
 

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp-docs-server
 
+## 1.1.28
+
+### Patch Changes
+
+- Updated dependencies [[`733bf53`](https://github.com/mastra-ai/mastra/commit/733bf53d9352aedd3ef38c3d501edb275b65b43c), [`5405b3b`](https://github.com/mastra-ai/mastra/commit/5405b3b35325c5b8fb34fc7ac109bd2feb7bb6fe), [`45e29cb`](https://github.com/mastra-ai/mastra/commit/45e29cb5b5737f3083eb3852db02b944b9cf37ed), [`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9), [`c321127`](https://github.com/mastra-ai/mastra/commit/c3211275fc195de9ad1ead2746b354beb8eae6e8), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1), [`696694e`](https://github.com/mastra-ai/mastra/commit/696694e00f29241a25dd1a1b749afa06c3a626b4), [`b084a80`](https://github.com/mastra-ai/mastra/commit/b084a800db0f82d62e1fc3d6e3e3480da1ba5a53), [`82b7a96`](https://github.com/mastra-ai/mastra/commit/82b7a964169636c1d1e0c694fc892a213b0179d5), [`e20a3d2`](https://github.com/mastra-ai/mastra/commit/e20a3d2cda9b94ca6625519da2e6492c335bd009), [`df97812`](https://github.com/mastra-ai/mastra/commit/df97812bd949dcafeb074b80ecab501724b49c3b), [`8bbe360`](https://github.com/mastra-ai/mastra/commit/8bbe36042af7fc4be0244dffd8913f6795179421), [`f6b8ba8`](https://github.com/mastra-ai/mastra/commit/f6b8ba8dbf533b7a8db90c72b6805ddc804a3a72), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1)]:
+  - @mastra/core@1.28.0
+  - @mastra/mcp@1.5.2
+
+## 1.1.28-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`45e29cb`](https://github.com/mastra-ai/mastra/commit/45e29cb5b5737f3083eb3852db02b944b9cf37ed), [`696694e`](https://github.com/mastra-ai/mastra/commit/696694e00f29241a25dd1a1b749afa06c3a626b4)]:
+  - @mastra/core@1.28.0-alpha.2
+
 ## 1.1.28-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.28-alpha.3",
+  "version": "1.1.28",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.28.0-alpha.1",
-    "@mastra/mcp": "^1.5.1"
+    "@mastra/mcp": "^1.5.2",
+    "@mastra/core": "1.28.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.1.5",
-    "@internal/lint": "0.0.85",
-    "@internal/types-builder": "0.0.60",
-    "@mastra/core": "1.28.0-alpha.1"
+    "@internal/lint": "0.0.86",
+    "@internal/types-builder": "0.0.61",
+    "@mastra/core": "1.28.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {