@mastra/mcp-docs-server 1.2.23-alpha.1 → 1.2.23-alpha.11

package/.docs/reference/tools/isolated-vm-transport.md

@@ -38,7 +38,7 @@ bun add @mastra/isolated-vm
 
 `isolated-vm` is a native addon. It provides prebuilt binaries for common platforms, so installation usually needs no extra setup. A C++ toolchain is only needed on platforms without a matching prebuild, where it falls back to compiling from source.
 
-On Node.js 20 and later, the host process must be started with the `--no-node-snapshot` flag, otherwise creating an isolate crashes the process. The constructor throws an error when the flag is missing. Pass the flag when starting your server, or set it through `NODE_OPTIONS`:
+On Node.js 20 and later, creating an isolate crashes unless the host process starts with `--no-node-snapshot`. The constructor reports the missing flag as an error. Pass it when starting the server or through `NODE_OPTIONS`:
 
 ```bash
 NODE_OPTIONS=--no-node-snapshot npm run dev

package/.docs/reference/tools/mcp-client.md

@@ -349,7 +349,7 @@ console.log(instructionsByServer.db)
 
 ### `authenticate()`
 
-Runs the interactive OAuth authorization-code flow for a server configured with an `MCPOAuthClientProvider` whose redirect URL points at a loopback address. Starts a local callback server, delivers the authorization URL through the provider's `onRedirectToAuthorization` callback, waits for the browser to return the authorization code, exchanges it for tokens, and reconnects. See [Interactive browser authentication](#interactive-browser-authentication).
+Runs the interactive OAuth authorization-code flow for a server whose `MCPOAuthClientProvider` uses a loopback redirect URL. A local callback server passes the authorization URL to the provider's `onRedirectToAuthorization` callback and waits for the browser to return the code. It then exchanges the code for tokens and reconnects. See [Interactive browser authentication](#interactive-browser-authentication).
 
 The optional `timeoutMs` bounds how long the flow waits for the browser to return the authorization code before rejecting, and defaults to 5 minutes.
 
@@ -1056,7 +1056,7 @@ try {
 
 Concurrent `authenticate()` calls for the same server join the pending flow. Different servers authenticate independently. With valid stored tokens the call reconnects without opening a browser.
 
-Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server and validates the OAuth `state` parameter before resolving with the code. It creates a plain HTTP server, so it's only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
+Hosts that drive the flow can capture the authorization code with the exported `createOAuthCallbackServer` helper. It creates a one-shot loopback server that validates the OAuth `state` parameter before resolving with the code. Because the server uses plain HTTP, use it only for local loopback redirects. Web applications with an HTTPS redirect URL must host their own callback endpoint and drive the provider directly:
 
 ```typescript
 import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'

package/.docs/reference/vectors/couchbase.md

@@ -216,7 +216,7 @@ try {
 
 - **Index Deletion Caveat:** Deleting a Search index doesn't delete the vectors/documents in the associated Couchbase collection. Data remains unless explicitly removed.
 - **Required Permissions:** The Couchbase user must have permissions to connect, read/write documents in the target collection (`kv` role), and manage Search Indexes (`search_admin` role on the relevant bucket/scope).
-- **Index Definition Details & Document Structure:** The `createIndex` method constructs a Search Index definition that indexes the `embedding` field (as type `vector`) and the `content` field (as type `text`), targeting documents within the specified `scopeName.collectionName`. Each document stores the vector in the `embedding` field and metadata in the `metadata` field. If `metadata` contains a `text` property, its value is also copied to a top-level `content` field, which is indexed for text search.
+- **Index Definition Details & Document Structure:** The `createIndex` method builds a Search Index definition for documents in `scopeName.collectionName`. It indexes the `embedding` field as a vector and the `content` field as text. Each document stores its vector in `embedding`, with metadata kept in `metadata`. A `text` property within `metadata` is also copied to the top-level `content` field for text search.
 - **Replication & Durability:** Consider using Couchbase's built-in replication and persistence features for data durability. Monitor index statistics regularly to ensure efficient search.
 
 ## Limitations

package/.docs/reference/vectors/mongodb.md

@@ -222,7 +222,7 @@ const results = await store.textQuery({
 
 ### `hybridQuery()`
 
-Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may require a MongoDB support case for enablement. It runs where enabled, including MongoDB Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
+Runs a hybrid search that fuses vector similarity with full-text results through MongoDB's server-side `$rankFusion`. The feature requires MongoDB 8.0 or later and is generally available from 8.1. MongoDB Atlas 8.0.x supports it where enabled, although enablement may require a support case. A full-text search index must exist. Managed indexes create one automatically, while bring-your-own collections require an explicit `createSearchIndex()` call.
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -255,7 +255,7 @@ const results = await store.hybridQuery({
 })
 ```
 
-`hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as MongoDB Atlas 8.0.x. If you're running an older version, or `$rankFusion` isn't enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
+`hybridQuery()` requires MongoDB 8.0 or later for the `$rankFusion` stage, which is generally available from 8.1. On 8.0.x, the stage runs where enabled, including MongoDB Atlas, but enablement may require a support case. If your deployment is older or lacks `$rankFusion`, run `query()` and `textQuery()` separately before merging the results client-side.
 
 ### `describeIndex()`
 

package/.docs/reference/voice/overview.md

@@ -1090,7 +1090,7 @@ const voice = new CompositeVoice({
   output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech
 })
 
-// Works seamlessly with your agent
+// Works directly with your agent
 const voiceAgent = new Agent({
   id: 'aisdk-voice-agent',
   name: 'AI SDK Voice Agent',

package/.docs/reference/workflows/workflow-methods/agent.md

@@ -12,9 +12,9 @@ Unlike wrapping an agent with `createStep()`, `.agent()` records a declarative e
 
 ```typescript
 workflow
-  .map({ prompt: mapVariable({ initData: workflow, path: "topic" }) })
+  .map({ prompt: mapVariable({ initData: workflow, path: 'topic' }) })
   .agent(testAgent)
-  .commit();
+  .commit()
 ```
 
 ## Parameters
@@ -42,7 +42,7 @@ workflow
       }),
     },
   })
-  .commit();
+  .commit()
 ```
 
 ## Referencing an agent by ID
@@ -50,7 +50,7 @@ workflow
 Pass a string to reference a registered agent without importing it. The agent must be registered on the Mastra instance when the workflow runs:
 
 ```typescript
-workflow.agent("test-agent", { maxSteps: 3 }).commit();
+workflow.agent('test-agent', { maxSteps: 3 }).commit()
 ```
 
 ## Persisting agent steps

package/.docs/reference/workflows/workflow-methods/foreach.md

@@ -26,7 +26,7 @@ workflow.foreach(step1, { concurrency: 2 })
 
 ### Execution and waiting
 
-The `.foreach()` method processes all items before the next step executes. The step following `.foreach()` only runs after every iteration has completed, regardless of concurrency settings. With `concurrency: 1` (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.
+The `.foreach()` method processes every item before the next step executes, regardless of concurrency settings. The default `concurrency: 1` processes items sequentially. Higher values use parallel batches, but the next step still waits for every batch to finish.
 
 If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple `.foreach()` calls. See [Nested workflows inside foreach](https://mastra.ai/docs/workflows/control-flow) for examples.
 

package/.docs/reference/workflows/workflow-methods/tool.md

@@ -11,7 +11,7 @@ Unlike wrapping a tool with `createStep()`, `.tool()` records a declarative entr
 ## Usage example
 
 ```typescript
-workflow.tool(testTool).commit();
+workflow.tool(testTool).commit()
 ```
 
 ## Parameters
@@ -31,7 +31,7 @@ workflow.tool(testTool).commit();
 Pass a string to reference a registered tool without importing it. The tool must be registered on the Mastra instance when the workflow runs:
 
 ```typescript
-workflow.tool("lookup-customer", { retries: 2 }).commit();
+workflow.tool('lookup-customer', { retries: 2 }).commit()
 ```
 
 ## Persisting tool steps

package/.docs/reference/workspace/platform-sandbox.md

@@ -175,9 +175,11 @@ await sandbox.start()
 
 `createRepoTemplate()` accepts the same `cpuCount` and `memoryMB` sizing as the `Template()` builder methods, as plain options. They carry the identity and stale-fallback semantics described above. Omit them for the provider defaults.
 
-`getRepositoryAccess` mirrors the resolver a Factory sandbox context carries, so a host can pass its context straight through; when it's absent, `createRepoTemplate()` returns `undefined` and the sandbox boots the provider default. The resolver doesn't run when `PlatformSandbox` reattaches to an existing `sandboxId`. It resolves the repository's default-branch head at fresh-start time, then Platform starts or reuses the corresponding template build. If the repository head can't be resolved or the provider build fails, sandbox creation continues with the provider's default template so runtime setup can perform a cold checkout. For private repositories, the short-lived authorization token is sent as an ephemeral build environment value that stays out of the serialized definition and the persisted template record. It has no effect on content identity.
+`setupCommand` also accepts an array. Each entry runs as its own cached build step. `workingDirectory` sets the cwd for the build and the sandbox, and the repository is cloned to `<workingDirectory>/<repo>`. `buildEnv` passes environment variables to the build steps only. They never enter the serialized definition.
 
-`createRepoTemplate()` also attaches a commit-independent `family` key (`repo:<cloneUrl>:<workdir>`, with the workdir derived from the clone URL) to the definition. `family` groups successive builds of the "same thing", so every commit of the same repository belongs to the same family. Platform uses it to find a prior ready build in the same family and boot the new commit on that warm filesystem while the exact commit template builds in the background. For E2B, stale lookup is also partitioned by the effective CPU and memory settings so a fallback can't silently change the requested machine size. Callers using the raw `Template()` builder can attach their own family key with `.withFamily(key)` (any non-empty string up to 200 characters). Omit it to opt out of family fallback. The family key never influences the content-addressed template identity: two definitions that differ only in `family` share the same cache slot.
+`getRepositoryAccess` mirrors the resolver a Factory sandbox context carries, so a host can pass its context straight through; when it's absent, `createRepoTemplate()` returns `undefined` and the sandbox boots the provider default. The resolver skips reattachment to an existing `sandboxId`; on a fresh start, it resolves the repository's default-branch head before Platform starts or reuses the corresponding template build. If the repository head can't be resolved or the provider build fails, sandbox creation continues with the provider's default template so runtime setup can perform a cold checkout. For private repositories, the short-lived authorization token is sent as an ephemeral build environment value that stays out of the serialized definition and the persisted template record. It has no effect on content identity.
+
+`createRepoTemplate()` also attaches a commit-independent `family` key (`repo:<cloneUrl>:<workingDirectory>/<repo>`) to the definition. `family` groups successive builds of the "same thing", so every commit of the same repository belongs to the same family. Platform uses it to find a prior ready build in the same family and boot the new commit on that warm filesystem while the exact commit template builds in the background. For E2B, stale lookup is also partitioned by the effective CPU and memory settings so a fallback can't silently change the requested machine size. Callers using the raw `Template()` builder can attach their own family key with `.withFamily(key)` (any non-empty string up to 200 characters). Omit it to opt out of family fallback. The family key never influences the content-addressed template identity: two definitions that differ only in `family` share the same cache slot.
 
 Platform stores build state under the definition's server-derived content hash within the selected environment and provider.
 
@@ -289,6 +291,8 @@ console.log(result.exitCode)
 
 **env** (`Record<string, string>`): Environment variables baked into the sandbox at creation time. Per-command environment variables can also be passed to executeCommand.
 
+**workingDirectory** (`string`): Default directory for command execution when no per-command cwd is given. A per-command cwd always wins. Use an absolute path.
+
 **timeout** (`number`): Default command execution timeout in milliseconds. Overridable per call via ExecuteCommandOptions.timeout.
 
 **instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.

package/.docs/reference/workspace/process-manager.md

@@ -60,7 +60,7 @@ const handle = await sandbox.processes.spawn('npm run dev', {
 
 **options.env** (`NodeJS.ProcessEnv`): Environment variables for the process.
 
-**options.cwd** (`string`): Working directory for the process.
+**options.cwd** (`string`): Working directory for the process. Defaults to the sandbox's configured workingDirectory, then the provider default.
 
 **options.onStdout** (`(data: string) => void`): Callback for stdout chunks. Called as data arrives.
 

package/.docs/reference/workspace/sandbox.md

@@ -41,7 +41,7 @@ Provider implementations plug into the start lifecycle at one of three rungs; th
 2. **`start()` override returning `SandboxStartResult`**: for providers whose API is a fused get-or-create where decomposition would add round-trips (`PlatformSandbox`, `RailwaySandbox`).
 3. **`start()` override returning `void`**: legacy providers, where the outcome is unknown.
 
-Concurrent `start()` calls on one instance coalesce onto a single in-flight attempt, and joined callers share that attempt's result (all observe `outcome: 'created'` when the shared attempt created the VM). The in-flight slot is cleared when the attempt settles, so a failed start can be retried. While the sandbox is already `running`, `start()` resolves `{ outcome: 'connected' }` without re-invoking the provider.
+Concurrent `start()` calls on one instance coalesce onto a single in-flight attempt, and joined callers share that attempt's result (all observe `outcome: 'created'` when the shared attempt created the VM). The in-flight slot is cleared when the attempt settles, so a failed start can be retried. For a sandbox already in the `running` state, `start()` resolves `{ outcome: 'connected' }` without re-invoking the provider.
 
 The result is also forwarded to the `onStart` lifecycle hook as `{ sandbox, outcome }`.
 
@@ -94,6 +94,23 @@ Semantics:
 - Each call wraps the current hook, so attach once per sandbox instance. Attaching on a path that runs per request stacks duplicate work on every start.
 - Only starts that begin after the call see the new hook.
 
+### `workingDirectory` (constructor option)
+
+Sets the default directory for command execution and process spawns. When a command provides no per-command `cwd`, the sandbox runs it from this directory. A per-command `cwd` always wins. When neither is provided, each provider keeps its own default (E2B home, Docker `/workspace`, Vercel serverless `/tmp`, and so on).
+
+```typescript
+const sandbox = new E2BSandbox({ workingDirectory: '/home/user/my-repo' })
+await sandbox.executeCommand('pwd') // /home/user/my-repo
+await sandbox.executeCommand('pwd', [], { cwd: '/tmp' }) // /tmp
+```
+
+The effective value is readable through the `sandbox.workingDirectory` getter. Providers that compute their value, such as Daytona's automatic probe or Docker's `/workspace` default, report the effective directory through the same getter.
+
+Semantics:
+
+- The value passes to the provider as-is, and the sandbox doesn't create the directory. Absolute paths are recommended: `~`-prefixed paths only work where the provider documents expansion.
+- Some providers keep earlier option names as deprecated aliases feeding the same field: `workingDir` on Docker and Apple container, `workdir` on Modal. When both the alias and `workingDirectory` are set, `workingDirectory` wins.
+
 ### `stop()`
 
 Stop the sandbox.
@@ -139,7 +156,7 @@ const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
 
 **options.timeout** (`number`): Execution timeout in milliseconds
 
-**options.cwd** (`string`): Working directory for the command
+**options.cwd** (`string`): Working directory for this command. Defaults to the sandbox's configured workingDirectory, then the provider default.
 
 **options.env** (`Record<string, string>`): Additional environment variables for this command. These take precedence over the sandbox environment for this command execution only.
 
@@ -167,7 +184,7 @@ The runtime environment applies to commands executed through the sandbox rather
 
 ### `getEnv()`
 
-Returns a copy of the sandbox's current runtime environment. Mutating the returned object doesn't change the sandbox, so use `setEnv()` for updates.
+Returns a copy of the sandbox's current runtime environment; because mutations to the returned object don't change the sandbox, use `setEnv()` for updates.
 
 ```typescript
 const token = sandbox.getEnv().GH_TOKEN

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

@@ -243,7 +243,7 @@ Stop the workspace's live resources without destroying them.
 await workspace.stop()
 ```
 
-`stop()` shuts down language servers and closes the browser, then stops the sandbox provider. Remote sandbox providers suspend or pause the sandbox so it can resume later. `LocalSandbox` kills its background processes and unmounts filesystems. Stopping isn't a teardown. The filesystem, search index, and skills keep working, and the next sandbox operation starts the sandbox again.
+`stop()` shuts down language servers and the browser before stopping the sandbox provider. Remote providers suspend or pause the sandbox for later resumption, while `LocalSandbox` kills background processes and unmounts filesystems. Stopping isn't a teardown. The filesystem and search index remain available along with skills, and the next sandbox operation starts the sandbox again.
 
 `mastra.shutdown()` calls `stop()` for registered workspaces, so a process restart suspends remote sandboxes instead of deleting them. To fully tear a workspace down, call `destroy()` or `mastra.removeWorkspace(id, { destroy: true })` explicitly.
 
@@ -390,7 +390,7 @@ if (workspace.hasFilesystemConfig()) {
 
 #### `resolveFilesystem({ requestContext })`
 
-Resolve the filesystem for a 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.
+Resolve the filesystem for a request context by calling a configured resolver with `requestContext` or returning a configured static filesystem directly. Returns `undefined` when no filesystem is configured.
 
 ```typescript
 import { RequestContext } from '@mastra/core/request-context'
@@ -421,7 +421,7 @@ if (workspace.hasSandboxConfig()) {
 
 #### `resolveSandbox({ requestContext })`
 
-Resolve the sandbox for a request context. When a resolver function is configured, calls it with the provided `requestContext`. When a static sandbox is configured, returns it directly. Returns `undefined` if no sandbox is configured.
+Resolve the sandbox for a request context by calling a configured resolver with `requestContext` or returning a configured static sandbox directly. Returns `undefined` when no sandbox is configured.
 
 ```typescript
 import { RequestContext } from '@mastra/core/request-context'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.23-alpha.1",
+  "version": "1.2.23-alpha.11",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,7 @@
   "files": [
     "dist",
     ".docs",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "exports": {
     ".": {
@@ -28,8 +27,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.63.3-alpha.0",
-    "@mastra/mcp": "^1.17.2"
+    "@mastra/core": "1.64.0-alpha.5",
+    "@mastra/mcp": "^1.17.3-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,8 +44,8 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "@mastra/core": "1.63.3-alpha.0",
     "@internal/lint": "0.0.129",
+    "@mastra/core": "1.64.0-alpha.5",
     "@internal/types-builder": "0.0.104"
   },
   "homepage": "https://mastra.ai",