@mastra/mcp-docs-server 1.2.17-alpha.1 → 1.2.17-alpha.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/.docs/docs/agents/agent-approval.md +2 -0
  2. package/.docs/docs/agents/code-mode.md +2 -2
  3. package/.docs/docs/agents/processors.md +1 -1
  4. package/.docs/docs/agents/skills.md +1 -1
  5. package/.docs/docs/agents/using-tools.md +1 -1
  6. package/.docs/docs/capabilities/channels.md +34 -1
  7. package/.docs/docs/datasets/running-experiments.md +46 -0
  8. package/.docs/docs/harness/agent-controller.md +1 -1
  9. package/.docs/docs/mcp/overview.md +4 -5
  10. package/.docs/docs/server/request-context.md +21 -0
  11. package/.docs/docs/studio/overview.md +1 -1
  12. package/.docs/docs/workspace/filesystem.md +182 -153
  13. package/.docs/docs/workspace/lsp.md +4 -5
  14. package/.docs/docs/workspace/sandbox.md +234 -141
  15. package/.docs/docs/workspace/search.md +52 -4
  16. package/.docs/docs/workspace/skills.md +62 -33
  17. package/.docs/integrations/browsers/browser-viewer.md +2 -2
  18. package/.docs/integrations/databases/postgresql.md +2 -1
  19. package/.docs/integrations/file-storage/amazon-s3.md +1 -1
  20. package/.docs/integrations/file-storage/azure-blob.md +1 -1
  21. package/.docs/integrations/file-storage/google-cloud-storage.md +1 -1
  22. package/.docs/integrations/file-storage/mesa.md +1 -1
  23. package/.docs/integrations/file-storage/vercel-files.md +1 -1
  24. package/.docs/integrations/observability/opentelemetry.md +34 -2
  25. package/.docs/integrations/sandboxes/apple-container.md +1 -1
  26. package/.docs/integrations/sandboxes/daytona.md +1 -1
  27. package/.docs/integrations/sandboxes/docker.md +1 -1
  28. package/.docs/integrations/sandboxes/e2b.md +1 -1
  29. package/.docs/integrations/sandboxes/modal.md +1 -1
  30. package/.docs/models/environment-variables.md +3 -0
  31. package/.docs/models/gateways/openrouter.md +4 -1
  32. package/.docs/models/gateways/vercel.md +1 -2
  33. package/.docs/models/index.md +1 -1
  34. package/.docs/models/providers/abacus.md +14 -1
  35. package/.docs/models/providers/alibaba-token-plan-cn.md +2 -1
  36. package/.docs/models/providers/alibaba-token-plan.md +2 -1
  37. package/.docs/models/providers/amd.md +73 -0
  38. package/.docs/models/providers/baseten.md +2 -1
  39. package/.docs/models/providers/chutes.md +2 -1
  40. package/.docs/models/providers/cloudflare-workers-ai.md +3 -1
  41. package/.docs/models/providers/cortecs.md +5 -2
  42. package/.docs/models/providers/crossmodel.md +4 -3
  43. package/.docs/models/providers/deepinfra.md +7 -1
  44. package/.docs/models/providers/digitalocean.md +3 -2
  45. package/.docs/models/providers/edenai.md +233 -23
  46. package/.docs/models/providers/empiriolabs.md +11 -1
  47. package/.docs/models/providers/fireworks-ai.md +2 -1
  48. package/.docs/models/providers/huggingface.md +6 -1
  49. package/.docs/models/providers/hyper.md +9 -7
  50. package/.docs/models/providers/inferx.md +19 -13
  51. package/.docs/models/providers/kilo.md +17 -15
  52. package/.docs/models/providers/llmtr.md +35 -10
  53. package/.docs/models/providers/merge-gateway.md +4 -2
  54. package/.docs/models/providers/nano-gpt.md +19 -15
  55. package/.docs/models/providers/nvidia.md +2 -1
  56. package/.docs/models/providers/ofox.md +34 -3
  57. package/.docs/models/providers/opencode-go.md +4 -3
  58. package/.docs/models/providers/opencode.md +2 -1
  59. package/.docs/models/providers/perplexity-agent.md +4 -2
  60. package/.docs/models/providers/qvac.md +35 -0
  61. package/.docs/models/providers/requesty.md +3 -3
  62. package/.docs/models/providers/runinfra.md +76 -0
  63. package/.docs/models/providers/scnet-token-plan.md +85 -0
  64. package/.docs/models/providers/togetherai.md +2 -1
  65. package/.docs/models/providers/umans-ai-coding-plan.md +2 -1
  66. package/.docs/models/providers/umans-ai.md +2 -1
  67. package/.docs/models/providers/xai.md +2 -1
  68. package/.docs/models/providers/zai-coding-plan.md +3 -2
  69. package/.docs/models/providers/zhipuai-coding-plan.md +2 -1
  70. package/.docs/models/providers.md +3 -0
  71. package/.docs/reference/agent-controller/agent-controller-class.md +26 -1
  72. package/.docs/reference/browser/browser-viewer.md +1 -1
  73. package/.docs/reference/configuration.md +1 -1
  74. package/.docs/reference/core/removeWorkspace.md +1 -1
  75. package/.docs/reference/datasets/addItem.md +5 -0
  76. package/.docs/reference/datasets/addItems.md +12 -2
  77. package/.docs/reference/datasets/startExperiment.md +1 -1
  78. package/.docs/reference/datasets/updateItem.md +3 -0
  79. package/.docs/reference/file-based-agents/workspace.md +3 -3
  80. package/.docs/reference/memory/observational-memory.md +4 -0
  81. package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md +2 -0
  82. package/.docs/reference/processors/provider-history-compat.md +6 -5
  83. package/.docs/reference/processors/skill-search-processor.md +1 -1
  84. package/.docs/reference/pubsub/base.md +13 -3
  85. package/.docs/reference/pubsub/caching-pubsub.md +2 -0
  86. package/.docs/reference/pubsub/event-emitter.md +2 -0
  87. package/.docs/reference/pubsub/redis-streams.md +11 -3
  88. package/.docs/reference/tools/create-code-mode.md +1 -1
  89. package/.docs/reference/tools/create-tool.md +11 -3
  90. package/.docs/reference/tools/mcp-client.md +34 -5
  91. package/.docs/reference/tools/mcp-server.md +4 -1
  92. package/.docs/reference/workspace/local-filesystem.md +1 -1
  93. package/.docs/reference/workspace/local-sandbox.md +1 -1
  94. package/.docs/reference/workspace/workspace-class.md +52 -15
  95. package/CHANGELOG.md +50 -0
  96. package/package.json +4 -4
  97. package/.docs/docs/workspace/overview.md +0 -416
@@ -45,11 +45,12 @@ Mastra agents don't add this processor automatically. Add it explicitly when you
45
45
 
46
46
  `ProviderHistoryCompat` includes these built-in compatibility rules:
47
47
 
48
- | Rule | Provider | Timing | Behavior |
49
- | ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
50
- | `anthropic-tool-id-format` | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request. |
51
- | `cerebras-strip-reasoning-content` | Cerebras | Preemptive prompt rewrite | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
52
- | `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved. |
48
+ | Rule | Provider | Timing | Behavior |
49
+ | ------------------------------------------- | ------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
50
+ | `anthropic-tool-id-format` | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request. |
51
+ | `cerebras-strip-reasoning-content` | Cerebras | Preemptive prompt rewrite | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
52
+ | `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved. |
53
+ | `azure-system-reminder-transform` | Azure OpenAI | Preemptive prompt rewrite | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged. |
53
54
 
54
55
  Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call.
55
56
 
@@ -112,4 +112,4 @@ Reserve workspace file tools such as `mastra_workspace_read_file` for explicit f
112
112
 
113
113
  - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
114
114
  - [Processors](https://mastra.ai/docs/agents/processors)
115
- - [Workspace Skills](https://mastra.ai/docs/workspace/overview)
115
+ - [Workspace Skills](https://mastra.ai/docs/workspace/skills)
@@ -79,10 +79,16 @@ Registers a callback to receive events published to a topic. When `options.group
79
79
 
80
80
  Pass `options.batch` to opt in to batched delivery. The callback signature is unchanged: a batch of N events is delivered as N consecutive `cb(event, ack, nack)` calls in publish order. Batching is honored only when the backend's [`supportsNativeBatching`](#properties) is `true`. Other backends ignore the option and deliver events one at a time.
81
81
 
82
+ Set `options.startFrom` to `"latest"` to receive only events published after a new consumer group is created. The default, `"earliest"`, includes retained events. Existing consumer groups keep their current checkpoint.
83
+
82
84
  ```typescript
83
- await pubsub.subscribe('my-topic', (event, ack, nack) => {
84
- console.log(event)
85
- })
85
+ await pubsub.subscribe(
86
+ 'my-topic',
87
+ (event, ack, nack) => {
88
+ console.log(event)
89
+ },
90
+ { startFrom: 'latest' },
91
+ )
86
92
  ```
87
93
 
88
94
  #### `unsubscribe(topic, cb)`
@@ -151,6 +157,8 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
151
157
 
152
158
  **supportsNativeBatching** (`boolean`): Whether the implementation honors options.batch on subscribe(). Defaults to false. Backends that integrate batching internally override this and return true.
153
159
 
160
+ **supportsOffsets** (`boolean`): Whether subscribeFromOffset() honors numeric offsets. Defaults to false. A non-zero offset on an unsupported implementation falls back to replay subscription and emits a diagnostic warning when a logger is configured.
161
+
154
162
  ## Types
155
163
 
156
164
  ### `Event`
@@ -175,6 +183,8 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
175
183
 
176
184
  **batch** (`SubscribeBatchOptions`): Opt in to batched delivery for this subscription. When omitted, events are delivered one at a time. Honored only by backends where supportsNativeBatching is true.
177
185
 
186
+ **startFrom** (`"earliest" | "latest"`): Starting position used when a backend creates a new consumer group. "earliest" includes retained events. "latest" receives only events published after group creation. Existing groups keep their checkpoint. (Default: `"earliest"`)
187
+
178
188
  ### `SubscribeBatchOptions`
179
189
 
180
190
  Per-subscription batching policy. The callback signature doesn't change. A batch of N events becomes N consecutive callback invocations in publish order.
@@ -46,6 +46,8 @@ const pubsub = withCaching(new EventEmitterPubSub(), new InMemoryServerCache())
46
46
 
47
47
  **supportsNativeBatching** (`boolean`): Mirrors the inner pub/sub. Returns true only when the wrapped implementation supports batching.
48
48
 
49
+ **supportsOffsets** (`boolean`): Returns true. Cached events have sequential indexes that support numeric offset replay.
50
+
49
51
  ## Methods
50
52
 
51
53
  `CachingPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. It overrides the replay methods to read cached events. The methods below describe the caching behavior.
@@ -51,6 +51,8 @@ const pubsub = new EventEmitterPubSub(undefined, { logger })
51
51
 
52
52
  **supportsNativeBatching** (`boolean`): Returns true. Subscribers can opt in to batched delivery with options.batch.
53
53
 
54
+ **supportsOffsets** (`boolean`): Returns false. The in-memory emitter does not retain indexed event history.
55
+
54
56
  ## Methods
55
57
 
56
58
  `EventEmitterPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.
@@ -77,6 +77,8 @@ export const mastra = new Mastra({
77
77
 
78
78
  **supportedModes** (`ReadonlyArray<"pull" | "push">`): Returns \["pull"].
79
79
 
80
+ **supportsOffsets** (`boolean`): Returns false. Redis stream anchors support start positions, but not the numeric indexes used by subscribeFromOffset().
81
+
80
82
  ## Methods
81
83
 
82
84
  `RedisStreamsPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.
@@ -85,10 +87,16 @@ export const mastra = new Mastra({
85
87
 
86
88
  Subscribes to a topic. With `options.group`, members of the group share events through a Redis consumer group. Without a group, the subscriber receives every event through a private consumer group.
87
89
 
90
+ Set `options.startFrom` to `"latest"` to skip retained entries when Redis creates the consumer group. The default, `"earliest"`, reads retained entries first. This option doesn't reset an existing group's checkpoint.
91
+
88
92
  ```typescript
89
- await pubsub.subscribe('workflow.events', (event, ack, nack) => {
90
- console.log(event)
91
- })
93
+ await pubsub.subscribe(
94
+ 'workflow.events',
95
+ (event, ack, nack) => {
96
+ console.log(event)
97
+ },
98
+ { group: 'live-workers', startFrom: 'latest' },
99
+ )
92
100
  ```
93
101
 
94
102
  ### `flush()`
@@ -126,4 +126,4 @@ export const codeModeTool = createCodeModeTool({
126
126
 
127
127
  - [Code mode](https://mastra.ai/docs/agents/code-mode)
128
128
  - [createTool()](https://mastra.ai/reference/tools/create-tool)
129
- - [Workspace overview](https://mastra.ai/docs/workspace/overview)
129
+ - [Sandbox](https://mastra.ai/docs/workspace/sandbox)
@@ -89,7 +89,7 @@ The first `execute` parameter is the validated value from `inputSchema`. Destruc
89
89
 
90
90
  **onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Signature: ({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>.
91
91
 
92
- **onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
92
+ **onOutput** (`function`): Optional callback invoked after a server-executed tool returns output or after a successful client-executed tool result arrives on a follow-up request. Error results don't invoke the hook. For client-executed results, TSchemaOut is a static type only: the server doesn't validate the result against outputSchema, so treat the output as untrusted. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
93
93
 
94
94
  Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You don't need to configure them for ordinary `createTool()` usage.
95
95
 
@@ -440,7 +440,7 @@ export const tool = createTool({
440
440
 
441
441
  #### `onOutput`
442
442
 
443
- Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
443
+ Called after a server-executed tool returns output or after a successful client-executed tool result arrives on a follow-up request. Use it to log results or trigger follow-up actions.
444
444
 
445
445
  ```typescript
446
446
  export const tool = createTool({
@@ -459,9 +459,15 @@ export const tool = createTool({
459
459
  })
460
460
  ```
461
461
 
462
+ Client-executed tools don't define an `execute` function. The browser runs the tool and sends the result on a follow-up request. `onOutput` then runs on the server. Only a correlated successful result invokes the hook: error results, such as the AI SDK `error-text` and `error-json` output types, don't invoke `onOutput`.
463
+
464
+ For client-executed results, the follow-up request must include both the assistant tool call and the tool result, which `@mastra/client-js` sends automatically. A request that carries only the tool result doesn't fire the hook. In this case the callback receives `{ toolCallId, toolName, output, abortSignal }` only.
465
+
466
+ Delivery is at least once, so a retried request runs the hook again. Keep the hook idempotent and treat client output as untrusted data: the server doesn't validate the result against `outputSchema`, so the `output` type is a static type only.
467
+
462
468
  ### Hook execution order
463
469
 
464
- For a typical streaming tool call, the hooks are invoked in this order:
470
+ For a typical streaming tool call on a server-executed tool, the hooks are invoked in this order:
465
471
 
466
472
  1. **onInputStart**: Input streaming begins
467
473
  2. **onInputDelta**: Called multiple times as chunks arrive
@@ -469,6 +475,8 @@ For a typical streaming tool call, the hooks are invoked in this order:
469
475
  4. Tool's **execute** function runs
470
476
  5. **onOutput**: Tool has completed successfully
471
477
 
478
+ For a client-executed tool, steps 1-3 run while the model streams the tool call, the client runs the tool instead of a server-side `execute`, and `onOutput` runs on the follow-up request that carries a successful result.
479
+
472
480
  ### Hook parameters
473
481
 
474
482
  Hook callbacks receive these source-backed parameter shapes:
@@ -223,17 +223,23 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
223
223
  new Agent({ id: 'agent', tools: await mcp.listTools() })
224
224
  ```
225
225
 
226
- ### `listToolsWithErrors()`
226
+ ### `listToolsWithErrors(options?)`
227
227
 
228
228
  Retrieves all tools from all configured servers, with tool names namespaced by their server name. Also returns per-server errors for servers that failed to connect or list tools.
229
229
 
230
+ Set `perServerTimeoutMs` to limit how long discovery waits for each server. Servers that finish within the limit remain in `tools`. Timed-out servers appear in `errors`, and `durations` reports each server's discovery time in milliseconds.
231
+
230
232
  ```typescript
231
- const { tools, errors } = await mcp.listToolsWithErrors()
233
+ const { tools, errors, durations } = await mcp.listToolsWithErrors({
234
+ perServerTimeoutMs: 3_000,
235
+ })
232
236
 
233
237
  new Agent({ id: 'agent', tools })
234
- console.log(errors)
238
+ console.log(errors, durations)
235
239
  ```
236
240
 
241
+ When called without options, the method returns only `tools` and `errors`.
242
+
237
243
  ### `listToolsets()`
238
244
 
239
245
  Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed at runtime into the generate or stream method.
@@ -244,6 +250,21 @@ const res = await agent.stream(prompt, {
244
250
  })
245
251
  ```
246
252
 
253
+ ### `listToolsetsWithErrors(options?)`
254
+
255
+ Returns toolsets grouped by server name, along with per-server discovery errors. Set `perServerTimeoutMs` to limit each server independently and include per-server `durations` in milliseconds.
256
+
257
+ ```typescript
258
+ const { toolsets, errors, durations } = await mcp.listToolsetsWithErrors({
259
+ perServerTimeoutMs: 3_000,
260
+ })
261
+
262
+ const res = await agent.stream(prompt, { toolsets })
263
+ console.log(errors, durations)
264
+ ```
265
+
266
+ When called without options, the method returns only `toolsets` and `errors`.
267
+
247
268
  ### `listToolDefinitions()`
248
269
 
249
270
  Returns every server's tools as plain, serializable definitions, grouped by server name and keyed by the server's own tool name (without the `serverName_toolName` namespacing that `listTools()` applies).
@@ -256,18 +277,26 @@ const definitions = await mcp.listToolDefinitions()
256
277
  await cache.set('mcp-tools', JSON.stringify(definitions))
257
278
  ```
258
279
 
259
- ### `listToolDefinitionsWithErrors()`
280
+ ### `listToolDefinitionsWithErrors(options?)`
260
281
 
261
282
  Like `listToolDefinitions()`, but also returns per-server errors for servers that failed to connect. Use this when caching a catalog, so you don't persist a partial manifest that omits a server that was down at discovery time.
262
283
 
284
+ Set `perServerTimeoutMs` to limit each server independently. When options are provided, `durations` reports each server's discovery time in milliseconds.
285
+
263
286
  ```typescript
264
- const { definitions, errors } = await mcp.listToolDefinitionsWithErrors()
287
+ const { definitions, errors, durations } = await mcp.listToolDefinitionsWithErrors({
288
+ perServerTimeoutMs: 3_000,
289
+ })
265
290
 
266
291
  if (Object.keys(errors).length === 0) {
267
292
  await cache.set('mcp-tools', JSON.stringify(definitions))
268
293
  }
294
+
295
+ console.log(durations)
269
296
  ```
270
297
 
298
+ When called without options, the method returns only `definitions` and `errors`.
299
+
271
300
  ### `toolFromDefinition()`
272
301
 
273
302
  Rebuilds a single executable tool from a cached definition. No connection is opened here. The client connects lazily, the first time the tool is executed.
@@ -1637,6 +1637,9 @@ const calculatorTool = createTool({
1637
1637
  num2: z.number(),
1638
1638
  operation: z.enum(['add', 'subtract']),
1639
1639
  }),
1640
+ mcp: {
1641
+ _meta: { ui: { resourceUri: 'ui://calculator/main' } },
1642
+ },
1640
1643
  execute: async ({ num1, num2, operation }) => {
1641
1644
  const result = operation === 'add' ? num1 + num2 : num1 - num2
1642
1645
  return {
@@ -1660,7 +1663,7 @@ const server = new MCPServer({
1660
1663
  })
1661
1664
  ```
1662
1665
 
1663
- Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
1666
+ Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
1664
1667
 
1665
1668
  ## Related information
1666
1669
 
@@ -356,4 +356,4 @@ Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my
356
356
 
357
357
  - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
358
358
  - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
359
- - [Workspace overview](https://mastra.ai/docs/workspace/overview)
359
+ - [Sandbox](https://mastra.ai/docs/workspace/sandbox)
@@ -223,4 +223,4 @@ This separation prevents sandboxed processes from reading or modifying their own
223
223
  - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
224
224
  - [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
225
225
  - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
226
- - [Workspace Overview](https://mastra.ai/docs/workspace/overview)
226
+ - [Sandbox](https://mastra.ai/docs/workspace/sandbox)
@@ -31,9 +31,9 @@ const workspace = new Workspace({
31
31
 
32
32
  **name** (`string`): Human-readable name (Default: `workspace-{id}`)
33
33
 
34
- **filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives requestContext and returns a filesystem per request. See dynamic filesystem.
34
+ **filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives requestContext and returns a filesystem per request. See multi-tenant filesystems.
35
35
 
36
- **sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives requestContext and returns a sandbox per request. See dynamic sandbox.
36
+ **sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives requestContext and returns a sandbox per request. See multi-tenant sandboxes.
37
37
 
38
38
  **instructions.dynamicSandbox** (`'placeholder' | 'resolve' | (({ requestContext }) => string)`): Controls how a resolver-backed sandbox contributes to workspace instructions. 'placeholder' (default) emits stable text without calling the resolver. 'resolve' calls the resolver and uses the sandbox's own instructions. A function returns custom text without resolving. Has no effect on a static sandbox. (Default: `'placeholder'`)
39
39
 
@@ -57,15 +57,9 @@ const workspace = new Workspace({
57
57
 
58
58
  **tools** (`WorkspaceToolsConfig`): Per-tool configuration for enabling tools and setting safety options
59
59
 
60
- **tools.enabled** (`boolean`): Whether the tool is available to agents
60
+ **tools.enabled** (`boolean | ((context: ToolConfigContext) => boolean | Promise<boolean>)`): Default availability for all workspace tools. Per-tool settings take precedence.
61
61
 
62
- **tools.requireApproval** (`boolean`): Whether the tool requires user approval before execution
63
-
64
- **tools.name** (`string`): Custom name to expose this tool as. Replaces the default mastra\_workspace\_\* name. The config key must still use the original WORKSPACE\_TOOLS constant.
65
-
66
- **tools.requireReadBeforeWrite** (`boolean`): For write tools: require reading the file first to prevent overwrites
67
-
68
- **tools.maxOutputTokens** (`number`): Maximum tokens for tool output. Output exceeding this limit is truncated using tiktoken.
62
+ **tools.requireApproval** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): Default approval policy for all workspace tools. Per-tool settings take precedence.
69
63
 
70
64
  **tools.writeLockTimeoutMs** (`number`): Maximum time in milliseconds a write tool waits to acquire the per-file write lock before failing. Raise this for slow or cold-starting filesystems (e.g. remote sandboxes).
71
65
 
@@ -73,6 +67,17 @@ const workspace = new Workspace({
73
67
 
74
68
  **operationTimeout** (`number`): Timeout for operations in milliseconds
75
69
 
70
+ For a resolver-backed sandbox, the default `'placeholder'` mode avoids provisioning a sandbox while workspace instructions are built. Set `instructions.dynamicSandbox` to `'resolve'` when the instructions must come from the resolved sandbox:
71
+
72
+ ```typescript
73
+ const workspace = new Workspace({
74
+ sandbox: ({ requestContext }) => resolveSandbox(requestContext),
75
+ instructions: { dynamicSandbox: 'resolve' },
76
+ })
77
+ ```
78
+
79
+ This calls the resolver while building instructions. To describe a request-specific environment without provisioning it, pass a function that returns instruction text from `requestContext` instead.
80
+
76
81
  ## Tool configuration
77
82
 
78
83
  The `tools` option accepts a `WorkspaceToolsConfig` object that controls which workspace tools are enabled and their safety settings.
@@ -97,12 +102,44 @@ const workspace = new Workspace({
97
102
  })
98
103
  ```
99
104
 
100
- The config object has two parts:
105
+ The config object has two types of settings:
106
+
107
+ - **Global settings**: `enabled` and `requireApproval` apply to all workspace tools unless overridden. `hooks` and `writeLockTimeoutMs` are global-only and can't be configured per tool.
108
+ - **Per-tool overrides**: Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
109
+
110
+ Per-tool overrides accept the following options:
111
+
112
+ **enabled** (`boolean | ((context: ToolConfigContext) => boolean | Promise<boolean>)`): Whether the tool is available. Functions are evaluated when Mastra lists tools. (Default: `true`)
113
+
114
+ **requireApproval** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): Whether the tool requires approval. Functions are evaluated when the tool executes. (Default: `false`)
115
+
116
+ **name** (`string`): Name exposed to the model instead of the default mastra\_workspace\_\* name.
101
117
 
102
- - **Global defaults** (`enabled`, `requireApproval`): Apply to all tools unless overridden
103
- - **Per-tool overrides** - Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
118
+ **requireReadBeforeWrite** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): For write tools, require the agent to read an existing file before changing it. (Default: `false`)
119
+
120
+ **maxOutputTokens** (`number`): Maximum output tokens for tools that support token-based truncation.
121
+
122
+ `ToolConfigContext` contains `{ requestContext, workspace }`. Execution-time policies use `ToolConfigWithArgsContext`, which also contains the tool's `args`.
123
+
124
+ ```typescript
125
+ import { Workspace, WORKSPACE_TOOLS } from '@mastra/core/workspace'
126
+
127
+ const workspace = new Workspace({
128
+ id: 'my-workspace',
129
+ tools: {
130
+ enabled: ({ requestContext }) => requestContext.get('workspace-tools') === true,
131
+ [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
132
+ requireApproval: ({ args }) => (args.path as string).startsWith('/protected'),
133
+ requireReadBeforeWrite: true,
134
+ },
135
+ [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
136
+ maxOutputTokens: 5000,
137
+ },
138
+ },
139
+ })
140
+ ```
104
141
 
105
- See [workspace overview](https://mastra.ai/docs/workspace/overview) for more examples.
142
+ See [Filesystem tools](https://mastra.ai/docs/workspace/filesystem), [Sandbox tools](https://mastra.ai/docs/workspace/sandbox), [LSP inspection](https://mastra.ai/docs/workspace/lsp), and [Search tools](https://mastra.ai/docs/workspace/search) for capability-specific configuration.
106
143
 
107
144
  ### Tool name remapping
108
145
 
@@ -469,7 +506,7 @@ The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle
469
506
 
470
507
  **backgroundProcesses.abortSignal** (`AbortSignal | null | false`): Abort signal for background processes. undefined (default) uses the agent's signal. null or false disables abort — processes persist after agent shutdown.
471
508
 
472
- See [Background process callbacks](https://mastra.ai/docs/workspace/sandbox) for usage examples.
509
+ See [Background processes](https://mastra.ai/docs/workspace/sandbox) for callback examples.
473
510
 
474
511
  ### Search tools
475
512
 
package/CHANGELOG.md CHANGED
@@ -1,5 +1,55 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.2.17-alpha.12
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`940bf5c`](https://github.com/mastra-ai/mastra/commit/940bf5ccf04f2c9ebd8a1390431733222a03b1cd)]:
8
+ - @mastra/core@1.60.0-alpha.7
9
+
10
+ ## 1.2.17-alpha.10
11
+
12
+ ### Patch Changes
13
+
14
+ - Updated dependencies [[`0b4f108`](https://github.com/mastra-ai/mastra/commit/0b4f1089aa8d92e67c2a8e99726822c5ee410784), [`88ddc7c`](https://github.com/mastra-ai/mastra/commit/88ddc7ce01d40175f13a3228b789a906779680bd), [`a7dd322`](https://github.com/mastra-ai/mastra/commit/a7dd32247d95afc539f483ca37f4594af0387f59)]:
15
+ - @mastra/core@1.60.0-alpha.6
16
+
17
+ ## 1.2.17-alpha.8
18
+
19
+ ### Patch Changes
20
+
21
+ - Updated dependencies [[`74e5bd3`](https://github.com/mastra-ai/mastra/commit/74e5bd315b8b3a1e04cb6cf480bb0f5fc4951dc8)]:
22
+ - @mastra/core@1.60.0-alpha.5
23
+
24
+ ## 1.2.17-alpha.6
25
+
26
+ ### Patch Changes
27
+
28
+ - Updated dependencies [[`d7e6745`](https://github.com/mastra-ai/mastra/commit/d7e67456954863c55440ea9c49bc6ceb9949972d), [`9acb50f`](https://github.com/mastra-ai/mastra/commit/9acb50f71cec9c362f06820033f90ae6b1f8282f), [`46e9e3f`](https://github.com/mastra-ai/mastra/commit/46e9e3f73babe1bc70080a596cf2ac0b9da48519), [`3f9a190`](https://github.com/mastra-ai/mastra/commit/3f9a19057c027155867b9317294ee4ca7bd0581a), [`e8808e3`](https://github.com/mastra-ai/mastra/commit/e8808e3d8eb585a2565be53e56a7e0e1477352a4), [`d4be8c1`](https://github.com/mastra-ai/mastra/commit/d4be8c1739d22d621e3f78790e1dd5eb5ecc3589), [`a5d2eb1`](https://github.com/mastra-ai/mastra/commit/a5d2eb10347eade1ae2816d88f466c25186c54a5), [`13d49d8`](https://github.com/mastra-ai/mastra/commit/13d49d82f434f319d4bd9a4234369d8186f8e102), [`e81744c`](https://github.com/mastra-ai/mastra/commit/e81744cd13c46619c142dc521dc0baac47607a84)]:
29
+ - @mastra/core@1.60.0-alpha.4
30
+ - @mastra/mcp@1.17.0-alpha.0
31
+
32
+ ## 1.2.17-alpha.5
33
+
34
+ ### Patch Changes
35
+
36
+ - Updated dependencies [[`d8308a2`](https://github.com/mastra-ai/mastra/commit/d8308a2be3c07e777393d1017a381dcae3890d30), [`7aad631`](https://github.com/mastra-ai/mastra/commit/7aad631b43bc10db77d5b8c66b200d7a49d18bf2), [`1794a79`](https://github.com/mastra-ai/mastra/commit/1794a79178c418004a7261b1ad9114066f7ef01d)]:
37
+ - @mastra/core@1.60.0-alpha.3
38
+
39
+ ## 1.2.17-alpha.4
40
+
41
+ ### Patch Changes
42
+
43
+ - Updated dependencies [[`7e096f0`](https://github.com/mastra-ai/mastra/commit/7e096f02f0dddbf09b85d306458351245ed2f886), [`8f0a332`](https://github.com/mastra-ai/mastra/commit/8f0a3321bf180368d76fe7b36aa1a8f60f00b6de), [`b098de9`](https://github.com/mastra-ai/mastra/commit/b098de9d7cb9f672e0883a5c716465a3a689693d), [`ef6e295`](https://github.com/mastra-ai/mastra/commit/ef6e295b59bc25a5b61b633a89c97bcfce9fb465), [`208e1b3`](https://github.com/mastra-ai/mastra/commit/208e1b39f30f4b386e494394e9d71d96f0f90241), [`c938d34`](https://github.com/mastra-ai/mastra/commit/c938d34739936c8ecbabd67ad6a4a4396f41c4c6), [`1d9a0ea`](https://github.com/mastra-ai/mastra/commit/1d9a0ea4a9901baee6cd56737243bd6d1f631ac0), [`3667679`](https://github.com/mastra-ai/mastra/commit/3667679db057edfb086846d13369fdda4902ad65), [`49696e8`](https://github.com/mastra-ai/mastra/commit/49696e8e42f870674a0a58f5abcd22cc54dd2864), [`512100a`](https://github.com/mastra-ai/mastra/commit/512100a7d8b7e9c920f2590c6b3612f5de0d3cff), [`9ef432b`](https://github.com/mastra-ai/mastra/commit/9ef432b6faa534b57b0d182a610e13dd9a7123ff), [`b9cf308`](https://github.com/mastra-ai/mastra/commit/b9cf30846f97f99ac1906ee8a68f4f2d117b0378)]:
44
+ - @mastra/core@1.60.0-alpha.2
45
+
46
+ ## 1.2.17-alpha.2
47
+
48
+ ### Patch Changes
49
+
50
+ - Updated dependencies [[`15101bb`](https://github.com/mastra-ai/mastra/commit/15101bb53c0d934f31af6b8813b88191e382a5e5), [`c2c3deb`](https://github.com/mastra-ai/mastra/commit/c2c3debcf670c7082d0a5e553aa99818a864698c), [`33374ba`](https://github.com/mastra-ai/mastra/commit/33374ba359e4fb13eaa918ae925fe167a3c55414), [`c5f964d`](https://github.com/mastra-ai/mastra/commit/c5f964d3f77064e978f8066ec506eed77ba5c63c), [`f8f653f`](https://github.com/mastra-ai/mastra/commit/f8f653f10980d01a73706cc3c8689ca5e40ce808)]:
51
+ - @mastra/core@1.60.0-alpha.1
52
+
3
53
  ## 1.2.17-alpha.0
4
54
 
5
55
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.2.17-alpha.1",
3
+ "version": "1.2.17-alpha.13",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -28,8 +28,8 @@
28
28
  "jsdom": "^26.1.0",
29
29
  "local-pkg": "^1.1.2",
30
30
  "zod": "^4.4.3",
31
- "@mastra/core": "1.59.1-alpha.0",
32
- "@mastra/mcp": "^1.16.0"
31
+ "@mastra/core": "1.60.0-alpha.7",
32
+ "@mastra/mcp": "^1.17.0-alpha.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@hono/node-server": "^2.0.0",
@@ -47,7 +47,7 @@
47
47
  "vitest": "4.1.10",
48
48
  "@internal/lint": "0.0.123",
49
49
  "@internal/types-builder": "0.0.98",
50
- "@mastra/core": "1.59.1-alpha.0"
50
+ "@mastra/core": "1.60.0-alpha.7"
51
51
  },
52
52
  "homepage": "https://mastra.ai",
53
53
  "repository": {