@mastra/mcp-docs-server 1.1.28-alpha.1 → 1.1.28-alpha.4

package/.docs/docs/browser/browser-viewer.md

@@ -133,34 +133,7 @@ const viewer = new BrowserViewer({
 })
 ```
 
-## Configuration
-
-| Option           | Type                                               | Default    | Description                                             |
-| ---------------- | -------------------------------------------------- | ---------- | ------------------------------------------------------- |
-| `cli`            | `'agent-browser' \| 'browser-use' \| 'browse-cli'` | Required   | Which CLI the agent uses                                |
-| `headless`       | `boolean`                                          | `false`    | Run browser in headless mode                            |
-| `cdpUrl`         | `string`                                           | —          | Connect to an existing browser instead of launching one |
-| `cdpPort`        | `number`                                           | `0` (auto) | Port for Chrome remote debugging                        |
-| `viewport`       | `{ width, height }`                                | `1280×720` | Browser viewport size                                   |
-| `userDataDir`    | `string`                                           | —          | Chrome profile directory for persistent state           |
-| `executablePath` | `string`                                           | —          | Path to a Chrome executable                             |
-
-## Connecting to an existing browser
-
-To connect to a browser that is already running, pass a `cdpUrl`:
-
-```typescript
-const viewer = new BrowserViewer({
-  cli: 'browser-use',
-  cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
-})
-```
-
-BrowserViewer connects via the CDP endpoint and enables screencast without launching its own browser.
-
-## External CDP connections
-
-When the agent provides its own CDP URL in a command (for example, `browser-use --cdp-url wss://cloud.example.com/session`), BrowserViewer detects this and skips injection. It connects to the external browser for screencast only, without managing the browser lifecycle.
+> **Note:** See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
 
 ## Related
 

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/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3720 models from 104 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3723 models from 104 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/cortecs.md

@@ -1,6 +1,6 @@
 # ![Cortecs logo](https://models.dev/logos/cortecs.svg)Cortecs
 
-Access 33 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
+Access 34 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
 
 Learn more in the [Cortecs documentation](https://cortecs.ai).
 
@@ -57,6 +57,7 @@ for await (const chunk of stream) {
 | `cortecs/kimi-k2-instruct`               | 131K    |       |           |       |       |       | $0.55      | $3          |
 | `cortecs/kimi-k2-thinking`               | 262K    |       |           |       |       |       | $0.66      | $3          |
 | `cortecs/kimi-k2.5`                      | 256K    |       |           |       |       |       | $0.55      | $3          |
+| `cortecs/kimi-k2.6`                      | 256K    |       |           |       |       |       | $0.81      | $4          |
 | `cortecs/llama-3.1-405b-instruct`        | 128K    |       |           |       |       |       | —          | —           |
 | `cortecs/minimax-m2`                     | 400K    |       |           |       |       |       | $0.39      | $2          |
 | `cortecs/minimax-m2.1`                   | 196K    |       |           |       |       |       | $0.34      | $1          |

package/.docs/models/providers/openai.md

@@ -1,6 +1,6 @@
 # ![OpenAI logo](https://models.dev/logos/openai.svg)OpenAI
 
-Access 50 OpenAI models through Mastra's model router. Authentication is handled automatically using the `OPENAI_API_KEY` environment variable.
+Access 51 OpenAI models through Mastra's model router. Authentication is handled automatically using the `OPENAI_API_KEY` environment variable.
 
 Learn more in the [OpenAI documentation](https://platform.openai.com/docs/models).
 
@@ -66,6 +66,7 @@ for await (const chunk of stream) {
 | `openai/gpt-5.4-mini`           | 400K    |       |           |       |       |       | $0.75      | $5          |
 | `openai/gpt-5.4-nano`           | 400K    |       |           |       |       |       | $0.20      | $1          |
 | `openai/gpt-5.4-pro`            | 1.1M    |       |           |       |       |       | $30        | $180        |
+| `openai/gpt-5.5`                | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `openai/gpt-image-1`            | —       |       |           |       |       |       | —          | —           |
 | `openai/gpt-image-1-mini`       | —       |       |           |       |       |       | —          | —           |
 | `openai/gpt-image-1.5`          | —       |       |           |       |       |       | —          | —           |

package/.docs/models/providers/poe.md

@@ -1,6 +1,6 @@
 # ![Poe logo](https://models.dev/logos/poe.svg)Poe
 
-Access 118 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
+Access 119 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
 
 Learn more in the [Poe documentation](https://creator.poe.com/docs/external-applications/openai-compatible-api).
 
@@ -126,6 +126,7 @@ for await (const chunk of stream) {
 | `poe/openai/gpt-image-1`               | 128K    |       |           |       |       |       | —          | —           |
 | `poe/openai/gpt-image-1-mini`          | —       |       |           |       |       |       | —          | —           |
 | `poe/openai/gpt-image-1.5`             | 128K    |       |           |       |       |       | —          | —           |
+| `poe/openai/gpt-image-2`               | —       |       |           |       |       |       | $5         | $32         |
 | `poe/openai/o1`                        | 200K    |       |           |       |       |       | $14        | $54         |
 | `poe/openai/o1-pro`                    | 200K    |       |           |       |       |       | $140       | $540        |
 | `poe/openai/o3`                        | 200K    |       |           |       |       |       | $2         | $7          |

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

@@ -44,7 +44,7 @@ When `cdpUrl` is provided, `BrowserViewer` connects to the existing browser inst
 
 **cli** (`'agent-browser' | 'browser-use' | 'browse-cli'`): Which CLI the agent uses for browser automation. The CLI connects to Chrome via the CDP URL.
 
-**headless** (`boolean`): Whether to run Chrome in headless mode. (Default: `false`)
+**headless** (`boolean`): Whether to run Chrome in headless mode. (Default: `true`)
 
 **cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL for connecting to an existing browser instead of launching one.
 
@@ -54,12 +54,8 @@ When `cdpUrl` is provided, `BrowserViewer` connects to the existing browser inst
 
 **viewport** (`{ width: number; height: number }`): Browser viewport dimensions. (Default: `{ width: 1280, height: 720 }`)
 
-**userDataDir** (`string`): Path to Chrome user data directory. Persists cookies, localStorage, and extensions across sessions.
-
 **executablePath** (`string`): Path to a Chrome executable. Uses Playwright's bundled Chromium by default.
 
-**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
-
 **onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked after the browser is ready.
 
 **onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked before the browser closes.

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

@@ -34,7 +34,7 @@ export const browserAgent = new Agent({
 
 **viewport** (`{ width: number; height: number }`): Browser viewport dimensions. Controls the size of the browser window. (Default: `{ width: 1280, height: 720 }`)
 
-**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
+**timeout** (`number`): Default timeout in milliseconds. Each provider defines its own semantics and default. See the provider reference for details.
 
 **cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL, HTTP endpoint, or sync/async provider function. When provided, connects to an existing browser instead of launching a new one. HTTP endpoints are resolved to WebSocket internally. Can't be used with scope: 'thread' (automatically uses shared scope).
 

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

@@ -52,7 +52,7 @@ Use stagehand_extract to get data from pages.`,
 
 **scope** (`'shared' | 'thread'`): Browser instance scope across threads. (Default: `'thread' (or 'shared' when cdpUrl is provided)`)
 
-**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
+**timeout** (`number`): Default timeout in milliseconds for Stagehand operations. (Default: `30000`)
 
 **onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked after the browser is ready.
 

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,19 @@
 # @mastra/mcp-docs-server
 
+## 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
+
+- Updated dependencies [[`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9)]:
+  - @mastra/core@1.28.0-alpha.1
+
 ## 1.1.28-alpha.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.28-alpha.1",
+  "version": "1.1.28-alpha.4",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.28.0-alpha.0",
+    "@mastra/core": "1.28.0-alpha.2",
     "@mastra/mcp": "^1.5.1"
   },
   "devDependencies": {
@@ -47,8 +47,8 @@
     "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.0"
+    "@mastra/core": "1.28.0-alpha.2",
+    "@internal/types-builder": "0.0.60"
   },
   "homepage": "https://mastra.ai",
   "repository": {