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

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/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,12 @@
 # @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.28-alpha.3",
+  "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.1",
+    "@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.1"
+    "@mastra/core": "1.28.0-alpha.2",
+    "@internal/types-builder": "0.0.60"
   },
   "homepage": "https://mastra.ai",
   "repository": {