@mastra/mcp-docs-server 1.1.26-alpha.2 → 1.1.26-alpha.22

package/.docs/reference/storage/cloudflare-d1.md

@@ -34,59 +34,59 @@ bun add @mastra/cloudflare-d1@latest
 
 ## Usage
 
-### Using with Cloudflare Workers
+### Using with Mastra CloudflareDeployer
 
-When using D1Store in a Cloudflare Worker, you need to access the D1 binding from the worker's `env` parameter at runtime. The `D1Database` in your type definition is only for TypeScript type checking—the actual binding is provided by the Workers runtime.
+The standard way to use D1Store with Mastra on Cloudflare is with `CloudflareDeployer`. Import `env` from `cloudflare:workers` and initialize `D1Store` inline inside `new Mastra({...})`.
 
 ```typescript
+import { env } from 'cloudflare:workers'
 import { D1Store } from '@mastra/cloudflare-d1'
 import { Mastra } from '@mastra/core'
 import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
 
-type Env = {
-  D1Database: D1Database // TypeScript type definition
-}
+export const mastra = new Mastra({
+  storage: new D1Store({ binding: env.DB }),
+  deployer: new CloudflareDeployer({
+    name: 'my-worker',
+    d1_databases: [
+      {
+        binding: 'DB',
+        database_name: 'your-database-name',
+        database_id: 'your-database-id',
+      },
+    ],
+  }),
+})
+```
+
+> **Note:** When using `import { env } from 'cloudflare:workers'`, `D1Store` must be initialized inline inside `new Mastra({...})` — not extracted to a module-level variable. Alternatively, initialize `D1Store` inside the `fetch` handler after `env` is available. See [CloudflareDeployer reference](https://mastra.ai/reference/deployer/cloudflare) for details.
 
-// Factory function to create Mastra with D1 binding
-function createMastra(env: Env) {
-  const storage = new D1Store({
-    binding: env.D1Database, // ✅ Access the actual binding from env
-    tablePrefix: 'dev_', // Optional: isolate tables per environment
-  })
-
-  return new Mastra({
-    storage,
-    deployer: new CloudflareDeployer({
-      name: 'my-worker',
-      d1_databases: [
-        {
-          binding: 'D1Database', // Must match the property name in Env type
-          database_name: 'your-database-name',
-          database_id: 'your-database-id',
-        },
-      ],
-    }),
-  })
+### Using in a Cloudflare Worker without HTTP routes
+
+If you want to call Mastra directly in a Worker — for example, to run an agent or trigger a workflow — without serving HTTP routes, you don't need `CloudflareDeployer`. Access the D1 binding from the worker's `env` parameter and call Mastra programmatically.
+
+```typescript
+import { D1Store } from '@mastra/cloudflare-d1'
+import { Mastra } from '@mastra/core'
+
+type Env = {
+  DB: D1Database
 }
 
-// Cloudflare Worker export
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-    const mastra = createMastra(env)
+    const mastra = new Mastra({
+      storage: new D1Store({ binding: env.DB }),
+    })
 
-    // Your handler logic here
-    return new Response('Hello from Mastra with D1!')
+    const agent = mastra.getAgent('my-agent')
+    const result = await agent.generate('Hello')
+
+    return Response.json({ text: result.text })
   },
 }
 ```
 
-> **Important: Understanding D1 Bindings:** In the `Env` type definition, `D1Database: D1Database` serves two purposes:
->
-> - The **property name** (`D1Database`) must match the `binding` name in your `wrangler.toml`
-> - The **type** (`: D1Database`) is from `@cloudflare/workers-types` for TypeScript type checking
->
-> At runtime, Cloudflare Workers provides the actual D1 database instance via `env.D1Database`. You can't use `D1Database` directly outside of the worker's context.
-
 ### Using with REST API
 
 For non-Workers environments (Node.js, serverless functions, etc.), use the REST API approach:
@@ -108,7 +108,7 @@ Add the D1 database binding to your `wrangler.toml`:
 
 ```toml
 [[d1_databases]]
-binding = "D1Database"  # Must match the property name in your Env type
+binding = "DB"
 database_name = "your-database-name"
 database_id = "your-database-id"
 ```
@@ -119,7 +119,7 @@ Or in `wrangler.jsonc`:
 {
   "d1_databases": [
     {
-      "binding": "D1Database",
+      "binding": "DB",
       "database_name": "your-database-name",
       "database_id": "your-database-id",
     },
@@ -158,14 +158,14 @@ import { Mastra } from '@mastra/core'
 import { D1Store } from '@mastra/cloudflare-d1'
 
 type Env = {
-  D1Database: D1Database
+  DB: D1Database
 }
 
 // In a Cloudflare Worker
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     const storage = new D1Store({
-      binding: env.D1Database, // ✅ Use env.D1Database
+      binding: env.DB,
     })
 
     const mastra = new Mastra({
@@ -184,7 +184,7 @@ If you're using storage directly without Mastra, you must call `init()` explicit
 import { D1Store } from '@mastra/cloudflare-d1'
 
 type Env = {
-  D1Database: D1Database
+  DB: D1Database
 }
 
 // In a Cloudflare Worker
@@ -192,7 +192,7 @@ export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     const storage = new D1Store({
       id: 'd1-storage',
-      binding: env.D1Database, // ✅ Use env.D1Database
+      binding: env.DB,
     })
 
     // Required when using storage directly

package/.docs/reference/streaming/agents/stream.md

@@ -206,6 +206,14 @@ const stream = await agent.stream('message for agent')
 
 **options.tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
 
+**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See \[Sub-agent versioning]\(/docs/editor/overview#sub-agent-versioning).
+
+**options.versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors.
+
+**options.versions.agents.versionId** (`string`): Target a specific version by ID.
+
+**options.versions.agents.status** (`'draft' | 'published'`): Target the latest version with this publication status.
+
 ## Returns
 
 **stream** (`MastraModelOutput<Output>`): Returns a MastraModelOutput instance that provides access to the streaming output.

package/.docs/reference/streaming/workflows/resumeStream.md

@@ -32,6 +32,8 @@ if (result!.status === 'suspended') {
 
 **step** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
 
+**forEachIndex** (`number`): Target a specific iteration of a suspended \`.foreach()\` step. Pass the zero-based index of the iteration to resume; other iterations remain suspended. Omit to resume all suspended iterations of the step with the same \`resumeData\`.
+
 **tracingOptions** (`TracingOptions`): Options for Tracing configuration.
 
 **tracingOptions.metadata** (`Record<string, any>`): Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.

package/.docs/reference/workflows/run-methods/resume.md

@@ -26,6 +26,8 @@ if (result.status === 'suspended') {
 
 **retryCount** (`number`): Optional retry count for nested workflow execution
 
+**forEachIndex** (`number`): Target a specific iteration of a suspended \`.foreach()\` step. Pass the zero-based index of the iteration you want to resume; other iterations remain suspended. Omit this field to resume all suspended iterations of the step with the same \`resumeData\`.
+
 **tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.
 
 **tracingContext.currentSpan** (`Span`): Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
@@ -67,6 +69,28 @@ if (result.status === 'suspended') {
 
 > **Note:** When exactly one step is suspended, you can omit the `step` parameter and the workflow will automatically resume that step. For workflows with multiple suspended steps, you must explicitly specify which step to resume.
 
+### Resuming a single [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) iteration
+
+When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, use `forEachIndex` (zero-based) to resume one iteration at a time with different `resumeData`. Iterations not targeted by `forEachIndex` remain suspended until resumed.
+
+```typescript
+// Resume only the second iteration (index 1) with its own data
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: true },
+  forEachIndex: 1,
+})
+
+// Later, resume the first iteration with different data
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: false },
+  forEachIndex: 0,
+})
+```
+
+If `forEachIndex` is omitted, every suspended iteration of the step is resumed with the same `resumeData`.
+
 ## Related
 
 - [Workflows overview](https://mastra.ai/docs/workflows/overview)

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

@@ -113,6 +113,19 @@ Each progress event payload contains:
 
 **iterationOutput** (`Record<string, any>`): Output of the iteration (present when iterationStatus is 'success')
 
+### Resuming a single iteration
+
+When a step inside `.foreach()` suspends, each iteration suspends independently. Pass `forEachIndex` to [`run.resume()`](https://mastra.ai/reference/workflows/run-methods/resume) to resume one iteration at a time with its own `resumeData`. Omitting `forEachIndex` resumes every suspended iteration with the same data.
+
+```typescript
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: true },
+  forEachIndex: 1,
+})
+```
+
 ## Related
 
-- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)
+- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)
+- [run.resume()](https://mastra.ai/reference/workflows/run-methods/resume)

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

@@ -0,0 +1,196 @@
+# DockerSandbox
+
+Executes commands inside Docker containers on the local machine. Uses long-lived containers with `docker exec` for command execution. Targets local development, CI/CD, air-gapped deployments, and cost-sensitive scenarios where cloud sandboxes are unnecessary.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/docker
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/docker
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/docker
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/docker
+```
+
+Requires [Docker Engine](https://docs.docker.com/engine/install/) running on the host machine.
+
+## Usage
+
+Add a `DockerSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { DockerSandbox } from '@mastra/docker'
+
+const workspace = new Workspace({
+  sandbox: new DockerSandbox({
+    image: 'node:22-slim',
+  }),
+})
+
+const agent = new Agent({
+  name: 'dev-agent',
+  model: 'anthropic/claude-opus-4-6',
+  workspace,
+})
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. Used for container naming and reconnection via labels. (Default: `Auto-generated`)
+
+**image** (`string`): Docker image to use for the container. (Default: `'node:22-slim'`)
+
+**command** (`string[]`): Container entrypoint command. Must keep the container alive for exec-based command execution. (Default: `['sleep', 'infinity']`)
+
+**env** (`Record<string, string>`): Environment variables to set in the container.
+
+**volumes** (`Record<string, string>`): Host-to-container bind mounts. Keys are host paths, values are container paths.
+
+**network** (`string`): Docker network to join.
+
+**privileged** (`boolean`): Run in privileged mode. (Default: `false`)
+
+**workingDir** (`string`): Working directory inside the container. (Default: `'/workspace'`)
+
+**labels** (`Record<string, string>`): Additional container labels. Mastra labels (mastra.sandbox, mastra.sandbox.id) are always included.
+
+**timeout** (`number`): Default command timeout in milliseconds. (Default: `300000 (5 minutes)`)
+
+**dockerOptions** (`Docker.DockerOptions`): Pass-through dockerode connection options for custom socket paths, remote hosts, or TLS certificates.
+
+**instructions** (`string | function`): Custom instructions that override the default instructions returned by getInstructions(). Pass an empty string to suppress instructions.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('DockerSandbox').
+
+**provider** (`string`): Provider identifier ('docker').
+
+**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
+
+**container** (`Container`): The underlying dockerode Container instance. Throws SandboxNotReadyError if the sandbox has not been started.
+
+**processes** (`DockerProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
+
+## Background processes
+
+`DockerSandbox` includes a built-in process manager for spawning and managing background processes. Processes run inside the container using `docker exec`.
+
+```typescript
+const sandbox = new DockerSandbox({ id: 'dev-sandbox' })
+await sandbox._start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+// Interact with the process
+console.log(handle.stdout)
+await handle.sendStdin('input\n')
+await handle.kill()
+```
+
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+## Environment variables
+
+Set environment variables at the container level with `env`. Per-command environment variables can also be passed when spawning processes:
+
+```typescript
+const sandbox = new DockerSandbox({
+  image: 'node:22-slim',
+  env: {
+    NODE_ENV: 'production',
+    DATABASE_URL: 'postgres://localhost:5432/mydb',
+  },
+})
+```
+
+## Bind mounts
+
+Mount host directories into the container using the `volumes` option:
+
+```typescript
+const sandbox = new DockerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/my/project': '/workspace/project',
+    '/shared/data': '/data',
+  },
+})
+```
+
+Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.
+
+## Reconnection
+
+`DockerSandbox` can reconnect to existing containers by matching labels. When `start()` is called, it checks for a container with the `mastra.sandbox.id` label matching the sandbox ID. If found:
+
+- A running container is reused directly.
+- A stopped container is restarted.
+
+```typescript
+// First run — creates a new container
+const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
+await sandbox._start()
+
+// Later — reconnects to the existing container
+const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
+await sandbox2._start()
+```
+
+## Docker connection options
+
+Connect to remote Docker hosts or use custom socket paths via `dockerOptions`:
+
+```typescript
+// Remote Docker host
+const sandbox = new DockerSandbox({
+  dockerOptions: {
+    host: '192.168.1.100',
+    port: 2376,
+    ca: fs.readFileSync('ca.pem'),
+    cert: fs.readFileSync('cert.pem'),
+    key: fs.readFileSync('key.pem'),
+  },
+})
+
+// Custom socket path
+const sandbox = new DockerSandbox({
+  dockerOptions: {
+    socketPath: '/var/run/docker.sock',
+  },
+})
+```
+
+## Related
+
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @mastra/mcp-docs-server
 
+## 1.1.26-alpha.21
+
+### Patch Changes
+
+- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
+  - @mastra/core@1.26.0-alpha.11
+
+## 1.1.26-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9)]:
+  - @mastra/core@1.26.0-alpha.10
+
+## 1.1.26-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [[`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0)]:
+  - @mastra/core@1.26.0-alpha.9
+
+## 1.1.26-alpha.16
+
+### Patch Changes
+
+- Updated dependencies [[`1bd5104`](https://github.com/mastra-ai/mastra/commit/1bd51048b6da93507276d6623e3fd96a9e1a8944)]:
+  - @mastra/core@1.26.0-alpha.8
+
+## 1.1.26-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`8786a61`](https://github.com/mastra-ai/mastra/commit/8786a61fa54ba265f85eeff9985ca39863d18bb6), [`8fb2405`](https://github.com/mastra-ai/mastra/commit/8fb2405138f2d208b7962ad03f121ca25bcc28c5)]:
+  - @mastra/core@1.26.0-alpha.7
+
+## 1.1.26-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`6315317`](https://github.com/mastra-ai/mastra/commit/63153175fe9a7b224e5be7c209bbebc01dd9b0d5), [`9d3b24b`](https://github.com/mastra-ai/mastra/commit/9d3b24b19407ae9c09586cf7766d38dc4dff4a69)]:
+  - @mastra/core@1.26.0-alpha.6
+
+## 1.1.26-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a)]:
+  - @mastra/core@1.26.0-alpha.5
+
+## 1.1.26-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3)]:
+  - @mastra/core@1.26.0-alpha.4
+
+## 1.1.26-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`fdd54cf`](https://github.com/mastra-ai/mastra/commit/fdd54cf612a9af876e9fdd85e534454f6e7dd518), [`30456b6`](https://github.com/mastra-ai/mastra/commit/30456b6b08c8fd17e109dd093b73d93b65e83bc5), [`9d11a8c`](https://github.com/mastra-ai/mastra/commit/9d11a8c1c8924eb975a245a5884d40ca1b7e0491), [`d246696`](https://github.com/mastra-ai/mastra/commit/d246696139a3144a5b21b042d41c532688e957e1), [`354f9ce`](https://github.com/mastra-ai/mastra/commit/354f9ce1ca6af2074b6a196a23f8ec30012dccca), [`e9837b5`](https://github.com/mastra-ai/mastra/commit/e9837b53699e18711b09e0ca010a4106376f2653)]:
+  - @mastra/core@1.26.0-alpha.3
+  - @mastra/mcp@1.5.1-alpha.1
+
+## 1.1.26-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`3d83d06`](https://github.com/mastra-ai/mastra/commit/3d83d06f776f00fb5f4163dddd32a030c5c20844), [`7e0e63e`](https://github.com/mastra-ai/mastra/commit/7e0e63e2e485e84442351f4c7a79a424c83539dc), [`9467ea8`](https://github.com/mastra-ai/mastra/commit/9467ea87695749a53dfc041576410ebf9ee7bb67), [`7338d94`](https://github.com/mastra-ai/mastra/commit/7338d949380cf68b095342e8e42610dc51d557c1), [`c65aec3`](https://github.com/mastra-ai/mastra/commit/c65aec356cc037ee7c4b30ccea946807d4c4f443)]:
+  - @mastra/core@1.26.0-alpha.2
+  - @mastra/mcp@1.5.1-alpha.1
+
 ## 1.1.26-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.26-alpha.2",
+  "version": "1.1.26-alpha.22",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,26 +29,26 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.25.1-alpha.1",
-    "@mastra/mcp": "^1.5.1-alpha.0"
+    "@mastra/core": "1.26.0-alpha.11",
+    "@mastra/mcp": "^1.5.1-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
     "@types/jsdom": "^21.1.7",
     "@types/node": "22.19.15",
-    "@vitest/coverage-v8": "4.0.18",
-    "@vitest/ui": "4.0.18",
+    "@vitest/coverage-v8": "4.1.4",
+    "@vitest/ui": "4.1.4",
     "@wong2/mcp-cli": "^1.13.0",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.4",
+    "eslint": "^10.2.1",
     "hono": "^4.12.8",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "4.0.18",
-    "@internal/lint": "0.0.83",
+    "vitest": "4.1.4",
     "@internal/types-builder": "0.0.58",
-    "@mastra/core": "1.25.1-alpha.1"
+    "@internal/lint": "0.0.83",
+    "@mastra/core": "1.26.0-alpha.11"
   },
   "homepage": "https://mastra.ai",
   "repository": {