@mastra/mcp-docs-server 1.2.13-alpha.4 → 1.2.13-alpha.8

package/.docs/reference/workers/overview.md

@@ -10,14 +10,14 @@ For usage patterns and deployment topologies, see [Workers](https://mastra.ai/do
 
 Controls which workers start in the current process.
 
-| Value                       | Behavior                                                              |
-| --------------------------- | --------------------------------------------------------------------- |
-| _(not set)_                 | Default workers are auto-created based on configuration               |
-| `"false"`                   | Disables all event processing. The process only serves HTTP requests. |
-| `"orchestration"`           | Only the orchestration worker starts                                  |
-| `"scheduler"`               | Only the scheduler worker starts                                      |
-| `"backgroundTasks"`         | Only the background task worker starts                                |
-| `"orchestration,scheduler"` | Multiple workers (comma-separated)                                    |
+| Value                       | Behavior                                                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(not set)_                 | Default workers are auto-created based on configuration                                                                                                   |
+| `"false"`                   | Disables worker event processing. The process serves HTTP requests and can still publish events to PubSub (e.g., workflow starts) without consuming them. |
+| `"orchestration"`           | Only the orchestration worker starts                                                                                                                      |
+| `"scheduler"`               | Only the scheduler worker starts                                                                                                                          |
+| `"backgroundTasks"`         | Only the background task worker starts                                                                                                                    |
+| `"orchestration,scheduler"` | Multiple workers (comma-separated)                                                                                                                        |
 
 Use this to run different worker types in separate containers from the same build artifact.
 
@@ -29,6 +29,8 @@ The base URL of the API server, used by the orchestration worker to execute work
 MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 ```
 
+Use HTTPS URLs in production. See [Security recommendations](https://mastra.ai/docs/server/auth/workers).
+
 The orchestration worker sends step execution requests to:
 
 ```text

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

@@ -4,7 +4,7 @@
 
 Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
 
-Use `PlatformFilesystem` when your agent runs on a Mastra Platform deployment and you want the filesystem to be backed by the platform-provisioned bucket. For direct S3 access, see [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem). For a local directory during development, see [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem).
+Related providers: [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) for direct S3 access, [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) for local directories.
 
 > **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
 
@@ -157,7 +157,8 @@ Filesystem-specific errors match the standard workspace error types:
 Other Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string):
 
 ```typescript
-import { FileNotFoundError, PlatformApiError } from '@mastra/platform-workspace'
+import { FileNotFoundError } from '@mastra/core/workspace'
+import { PlatformApiError } from '@mastra/platform-workspace'
 
 try {
   await fs.readFile('/missing.txt')
@@ -173,6 +174,8 @@ try {
 }
 ```
 
+`FileNotFoundError`, `FileExistsError`, and `WorkspaceReadOnlyError` are re-exports of the standard workspace error types from `@mastra/core/workspace`. `PlatformApiError` is specific to `@mastra/platform-workspace`.
+
 `code` and `proxyMessage` are `undefined` when the response body isn't JSON, for example an HTML 502 from a load balancer.
 
 ## Related

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

@@ -2,9 +2,11 @@
 
 # PlatformSandbox
 
-Executes commands inside a Mastra Platform sandbox tied to a Platform environment. Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed.
+Client for provisioning sandboxes in a Mastra Platform environment. Each `PlatformSandbox` instance owns one remote sandbox: `start()` provisions it, `executeCommand()` runs against it, and `destroy()` tears it down. Construct additional instances to own additional remote sandboxes; use `clone()` to derive them from a configured template (see [Cloning](#cloning-for-a-fleet-of-sandboxes)).
 
-Use `PlatformSandbox` when your agent runs on a Mastra Platform deployment and you want the sandbox to be provisioned and managed by the platform. For self-hosted Railway sandboxes, see [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox). For a local sandbox during development, see [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox).
+Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed. Pass a stable `id` to opt into [checkpoint recovery](#checkpoint-recovery) so a new sandbox boots from the previous one's filesystem.
+
+Related providers: [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox) for self-hosted Railway sandboxes, [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for local sandboxes.
 
 > **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
@@ -103,7 +105,7 @@ The default `ISOLATED` mode allows outbound internet access only, with no privat
 
 ### Reattaching to a running sandbox
 
-Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one. This is useful for stateful agents that resume between requests:
+Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one:
 
 ```typescript
 const sandbox = new PlatformSandbox({
@@ -116,6 +118,42 @@ const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
 
 When `sandboxId` is set, `environmentId` isn't required because the sandbox already exists.
 
+### Checkpoint recovery
+
+The constructor `id` (explicit or auto-generated) is sent to the platform on `POST /sandbox` as an advisory recovery key:
+
+- If the platform recognises the `id` from a previous session, the new sandbox boots from the most recent checkpoint of that earlier sandbox's filesystem instead of the base recipe.
+- If the `id` isn't recognised, the platform falls through to a fresh sandbox from the base recipe. Auto-generated ids never match, so omitting `id` disables checkpoint recovery.
+
+Pass a stable `id` to preserve a sandbox's filesystem across sessions or across a `destroy()`/`start()` cycle:
+
+```typescript
+const sandbox = new PlatformSandbox({
+  id: `project-${projectId}`,
+})
+await sandbox.start() // Boots from the most recent checkpoint for this id, or fresh if unknown
+```
+
+Checkpoint recovery is coarser than `sandboxId` reattachment. Reattaching (via `sandboxId`) rejoins the exact live sandbox and its running processes. Checkpoint recovery constructs a brand new sandbox and restores its filesystem from the latest checkpoint the platform captured for the previous sandbox with that `id`. Running processes and any filesystem writes made after the last checkpoint aren't restored.
+
+Each `id` maps to one independent filesystem. Reusing the same `id` across unrelated sandboxes causes the platform to boot them from each other's checkpoint.
+
+### Cloning for a fleet of sandboxes
+
+`clone()` returns an independent sibling `PlatformSandbox` that inherits credentials and defaults (access token, project, environment, network isolation, timeout, instructions, env, idle timeout) with per-instance overrides. The returned sandbox is unstarted and provisions on its own `start()`, so `clone()` performs no I/O:
+
+```typescript
+const template = new PlatformSandbox({
+  networkIsolation: 'PRIVATE',
+  idleTimeoutMinutes: 30,
+})
+
+const perProject = template.clone({ id: `project-${projectId}` })
+await perProject.start()
+```
+
+Combine `clone()` with a stable `id` per clone to opt each clone into [checkpoint recovery](#checkpoint-recovery) independently.
+
 ### Executing commands
 
 `executeCommand` runs a command on the remote sandbox and returns its output. Pass `args` to have arguments safely shell-quoted:
@@ -153,7 +191,7 @@ console.log(result.exitCode)
 
 **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.
 
-**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+**id** (`string`): Unique identifier for this sandbox instance. Sent to the platform as an advisory recovery key: if the platform recognizes the id from a previous sandbox, the new sandbox boots from that sandbox's most recent checkpoint instead of the base recipe. Unknown ids fall through to a fresh sandbox. Auto-generated when omitted, which disables checkpoint recovery. (Default: `Auto-generated`)
 
 **fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
 
@@ -169,6 +207,22 @@ console.log(result.exitCode)
 
 **processes** (`PlatformProcessManager`): Background process manager. See SandboxProcessManager reference.
 
+## Methods
+
+**start** (`() => Promise<void>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
+
+**destroy** (`() => Promise<void>`): Tear down the remote sandbox and clear the cached exec lease. A subsequent start() provisions a fresh sandbox (or restores from checkpoint when a stable id is set).
+
+**stop** (`() => Promise<void>`): Alias for destroy().
+
+**executeCommand** (`(command: string, args?: string[], options?: ExecuteCommandOptions) => Promise<CommandResult>`): Run a command on the remote sandbox and return its stdout, stderr, exitCode, and executionTimeMs. command is a shell string, args are safely shell-quoted.
+
+**clone** (`(options?: SandboxCloneOptions) => PlatformSandbox`): Construct an unstarted sibling PlatformSandbox that inherits credentials and defaults with per-instance overrides (id, sandboxId, env, idleTimeoutMinutes). Performs no I/O. Use to build a fleet of independent sandboxes from one configured template.
+
+**getInfo** (`() => Promise<SandboxInfo>`): Return the sandbox's platform id, provider, status, createdAt, and metadata (sandboxId, providerResourceId, platformStatus).
+
+**getInstructions** (`(opts?: { requestContext?: RequestContext }) => string`): Return the sandbox instructions the workspace surfaces in tool descriptions. Honors the instructions constructor option; otherwise returns platform-default instructions that include the current remote sandbox id when running.
+
 ## Errors
 
 Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string); the raw response body stays available on `.body`:
@@ -192,6 +246,28 @@ try {
 
 `code` and `proxyMessage` are `undefined` when the response body isn't JSON, for example an HTML 502 from a load balancer.
 
+`executeCommand` runs over the direct-exec data plane (a WebSocket to the Railway tcp-proxy) and can also throw two typed sandbox errors on unrecoverable failure:
+
+```typescript
+import { SandboxDestroyedError, SandboxExecTransportError } from '@mastra/platform-workspace'
+
+try {
+  await sandbox.executeCommand('pytest')
+} catch (err) {
+  if (err instanceof SandboxDestroyedError) {
+    // /exec-lease returned 410; the sandbox has been destroyed.
+    // The cached sandbox id and lease have already been cleared,
+    // so reusing the instance will reprovision on the next call.
+  } else if (err instanceof SandboxExecTransportError) {
+    // Both the initial WebSocket attempt and the built-in retry
+    // closed without an exit frame against a live sandbox.
+    console.error(err.closeCode, err.closeReason, err.wsEndpoint)
+  }
+}
+```
+
+`SandboxExecTransportError` carries diagnostic fields (`opened`, `closeCode`, `closeReason`, `wsEndpoint`, plus `sandboxId`, `command`, and `attempts`) so operators can distinguish a broken Railway data plane from a failed command.
+
 ## Related
 
 - [PlatformFilesystem reference](https://mastra.ai/reference/workspace/platform-filesystem)

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp-docs-server
 
+## 1.2.13-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`4844167`](https://github.com/mastra-ai/mastra/commit/4844167cff2d5ec5004e94edd34970833040fa3f), [`5faf93f`](https://github.com/mastra-ai/mastra/commit/5faf93f03e19daea394b9e2a923f2e4f833407f2), [`80ad891`](https://github.com/mastra-ai/mastra/commit/80ad891f8cd10379aa5b5af7510c763783b2ab56), [`c78aa4e`](https://github.com/mastra-ai/mastra/commit/c78aa4ecc422ba70476da73709c3e7d85edc71d6), [`a1cb98d`](https://github.com/mastra-ai/mastra/commit/a1cb98d11990b560b98482292a1f34aa1a2d9092), [`598ad82`](https://github.com/mastra-ai/mastra/commit/598ad82d41c41389a686338a1d0e50b7400e1938), [`1fd6aad`](https://github.com/mastra-ai/mastra/commit/1fd6aad1ea4a9d32f65efa832307c35e981a4c0a)]:
+  - @mastra/core@1.56.0-alpha.4
+  - @mastra/mcp@1.15.1-alpha.0
+
+## 1.2.13-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`594f7b2`](https://github.com/mastra-ai/mastra/commit/594f7b28f5263fb9982fd50d95c471fb971ea984), [`311f943`](https://github.com/mastra-ai/mastra/commit/311f943bee60e8fdf5c84499ea50e884276c936c), [`0c89896`](https://github.com/mastra-ai/mastra/commit/0c8989673fb7d106837098398131e570c6023b68), [`23b4238`](https://github.com/mastra-ai/mastra/commit/23b423844ad0bcf2a502a68dd62866d6160f9f6d), [`e320a76`](https://github.com/mastra-ai/mastra/commit/e320a763feaf65c6be3cebecf746defcbde161b3), [`03b4918`](https://github.com/mastra-ai/mastra/commit/03b4918c80d188ce375334c393e131c6e94bd7eb), [`14ef73a`](https://github.com/mastra-ai/mastra/commit/14ef73a4bbd73e7808414816eb0628ce1d80b5d7), [`1d677d5`](https://github.com/mastra-ai/mastra/commit/1d677d5f99d7db403f7828585e8c25f299f72628), [`93e28ec`](https://github.com/mastra-ai/mastra/commit/93e28ecce9031c02397e0ae8406593e5c7a95883), [`729dab4`](https://github.com/mastra-ai/mastra/commit/729dab408faccfaef0cbb048e5a4338f9172847e), [`484003d`](https://github.com/mastra-ai/mastra/commit/484003d33ff59330c86b19863e4a38732d7e4155), [`933d291`](https://github.com/mastra-ai/mastra/commit/933d291146b789c19442ad206f94da3e4be90c64)]:
+  - @mastra/core@1.56.0-alpha.3
+
 ## 1.2.13-alpha.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.13-alpha.4",
+  "version": "1.2.13-alpha.8",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.56.0-alpha.2",
-    "@mastra/mcp": "^1.15.0"
+    "@mastra/core": "1.56.0-alpha.4",
+    "@mastra/mcp": "^1.15.1-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.14",
@@ -46,8 +46,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
     "@internal/lint": "0.0.119",
-    "@internal/types-builder": "0.0.94",
-    "@mastra/core": "1.56.0-alpha.2"
+    "@mastra/core": "1.56.0-alpha.4",
+    "@internal/types-builder": "0.0.94"
   },
   "homepage": "https://mastra.ai",
   "repository": {