@mastra/mcp-docs-server 1.1.42-alpha.4 → 1.1.42-alpha.5

package/.docs/reference/workspace/agentcore-runtime-sandbox.md

@@ -0,0 +1,202 @@
+# AgentCoreRuntimeSandbox
+
+Executes shell commands in an [AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html) session by using `InvokeAgentRuntimeCommand`.
+
+Use `AgentCoreRuntimeSandbox` when your agent already runs in AgentCore Runtime and you want Mastra workspace command execution to use the same runtime session.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+> **Warning:** `AgentCoreRuntimeSandbox` only supports one-shot command execution. It does not support background process management, stdin, or filesystem mounts. AgentCore Code Interpreter is a separate AWS service and is not part of this provider.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/agentcore
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/agentcore
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/agentcore
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/agentcore
+```
+
+## Usage
+
+Add an `AgentCoreRuntimeSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { AgentCoreRuntimeSandbox } from '@mastra/agentcore'
+
+const workspace = new Workspace({
+  sandbox: new AgentCoreRuntimeSandbox({
+    region: 'us-west-2',
+    agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!,
+    runtimeSessionId: '12345678-1234-1234-1234-123456789012',
+  }),
+})
+
+const agent = new Agent({
+  name: 'dev-agent',
+  model: 'anthropic/claude-sonnet-4-6',
+  instructions: 'You are a helpful development assistant.',
+  workspace,
+})
+```
+
+Run commands programmatically through the sandbox:
+
+```typescript
+const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
+  cwd: '/workspace',
+  env: {
+    NODE_ENV: 'test',
+  },
+  timeout: 300_000,
+})
+
+if (!result?.success) {
+  console.error(result?.stderr)
+}
+```
+
+## Constructor parameters
+
+**agentRuntimeArn** (`string`): AgentCore Runtime ARN where commands execute.
+
+**region** (`string`): AWS region for the Bedrock AgentCore client. Falls back to the AWS SDK default region chain.
+
+**runtimeSessionId** (`string`): AgentCore Runtime session ID. Defaults to a generated UUID, which satisfies AgentCore Runtime session ID length requirements. (Default: `Generated UUID`)
+
+**qualifier** (`string`): Agent runtime qualifier or endpoint. (Default: `DEFAULT`)
+
+**contentType** (`string`): MIME type sent for command requests. (Default: `application/json`)
+
+**accept** (`string`): Accept header used for command event streams. (Default: `application/vnd.amazon.eventstream`)
+
+**commandTimeout** (`number`): Default command timeout in milliseconds. (Default: `300000`)
+
+**stopSessionOnLifecycle** (`boolean`): Whether \`stop()\` and \`destroy()\` should call \`StopRuntimeSession\`. Defaults to false because AgentCore Runtime sessions are often shared with agent invocations outside the sandbox instance. (Default: `false`)
+
+**stopClientToken** (`string`): Client token used when \`StopRuntimeSession\` is called. (Default: `Generated UUID`)
+
+**client** (`BedrockAgentCoreClient`): Preconfigured AWS SDK client. Use this for custom credentials, retry behavior, or tests.
+
+**instructions** (`string | ((opts) => string)`): Custom instructions that override the default instructions returned by \`getInstructions()\`. Pass a string to replace the defaults, or a function to extend them.
+
+## Properties
+
+**id** (`string`): Runtime session ID used by this sandbox instance.
+
+**name** (`'AgentCoreRuntimeSandbox'`): Human-readable name.
+
+**provider** (`'agentcore'`): Provider type identifier.
+
+**status** (`ProviderStatus`): Current lifecycle status: \`'pending'\`, \`'starting'\`, \`'running'\`, \`'stopping'\`, \`'stopped'\`, \`'destroying'\`, \`'destroyed'\`, or \`'error'\`.
+
+**runtimeSessionId** (`string`): AgentCore Runtime session ID used for command execution.
+
+**agentRuntimeArn** (`string`): AgentCore Runtime ARN where commands execute.
+
+## Methods
+
+### Command execution
+
+#### `executeCommand(command, args?, options?)`
+
+Runs a one-shot shell command in the AgentCore Runtime session and returns stdout, stderr, exit code, and timeout status.
+
+```typescript
+const result = await sandbox.executeCommand('npm', ['test'], {
+  cwd: '/workspace',
+  env: {
+    NODE_ENV: 'test',
+  },
+  timeout: 300_000,
+})
+```
+
+Returns: `Promise<CommandResult>`.
+
+`options.timeout` is specified in milliseconds. AgentCore Runtime accepts command timeouts from 1 to 3600 seconds. The provider converts milliseconds to seconds before sending the request.
+
+### Lifecycle
+
+#### `start()`
+
+Runs the sandbox lifecycle start hook. This provider does not create an AgentCore Runtime session during `start()`.
+
+```typescript
+await sandbox.start()
+```
+
+#### `stop()`
+
+Stops the AgentCore Runtime session only when `stopSessionOnLifecycle` is `true`.
+
+```typescript
+await sandbox.stop()
+```
+
+#### `stopRuntimeSession()`
+
+Explicitly stops the AgentCore Runtime session used by this sandbox.
+
+Use this when the sandbox owns the runtime session and you want to clean it up directly. `destroy()` does not call this method unless `stopSessionOnLifecycle` is `true`, because AgentCore Runtime sessions can be shared with agent invocations outside the Workspace sandbox lifecycle.
+
+```typescript
+await sandbox.stopRuntimeSession()
+```
+
+#### `destroy()`
+
+Destroys the sandbox instance. If this instance owns its AWS SDK client, `destroy()` also destroys the client. If `stopSessionOnLifecycle` is `true`, it calls `StopRuntimeSession`.
+
+```typescript
+await sandbox.destroy()
+```
+
+### Metadata
+
+#### `getInfo()`
+
+Returns sandbox status and AgentCore Runtime metadata.
+
+```typescript
+const info = await sandbox.getInfo()
+```
+
+Returns: `Promise<SandboxInfo>`.
+
+## Limitations
+
+`AgentCoreRuntimeSandbox` follows AgentCore Runtime command execution semantics:
+
+- **One-shot commands**: Each command runs to completion or timeout.
+- **No persistent shell**: Shell state does not carry over between commands. Encode state in each command, for example `cd /workspace && npm test`.
+- **Background processes are not supported**: The provider does not expose a `processes` manager.
+- **Interactive stdin is unavailable**: Runtime command execution does not provide an interactive stdin stream through this provider.
+- **Workspace filesystem mounts are unsupported**: Workspace filesystem mounting is not supported by this provider.
+- **Container-dependent tools**: Commands can only use tools installed in the AgentCore Runtime container image.
+
+## Related
+
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
+- [Sandbox overview](https://mastra.ai/docs/workspace/sandbox)
+- [AWS Bedrock AgentCore Runtime command execution](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)

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

@@ -61,6 +61,7 @@ const workspace = new Workspace({
   sandbox: new BlaxelSandbox({
     image: 'node:20-slim',
     memory: 8192,
+    region: 'auto',
     timeout: '10m',
   }),
 })
@@ -76,6 +77,8 @@ const workspace = new Workspace({
 
 **timeout** (`string`): Execution timeout as a duration string (e.g. '5m', '1h'). Maps to the Blaxel sandbox TTL.
 
+**region** (`string`): Blaxel region where the sandbox should be created. Use 'auto' to choose a region automatically, or set a concrete region like 'us-pdx-1'. (Default: `process.env.BL_REGION || 'auto'`)
+
 **env** (`Record<string, string>`): Environment variables to set in the sandbox.
 
 **labels** (`Record<string, string>`): Custom labels for the sandbox.

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

@@ -56,7 +56,9 @@ const agent = new Agent({
 
 ## Constructor parameters
 
-**id** (`string`): Unique identifier for this sandbox instance. Used for container naming and reconnection via labels. (Default: `Auto-generated`)
+**id** (`string`): Unique identifier for this sandbox instance. Used for label-based reconnection. (Default: `Auto-generated`)
+
+**name** (`string`): Container display name passed to Docker as \`--name\`. Characters outside \`\[a-zA-Z0-9\_.-]\` are replaced with \`-\` and the result is prefixed if it would not start with an alphanumeric character. (Default: `` The sandbox `id` ``)
 
 **image** (`string`): Docker image to use for the container. (Default: `'node:22-slim'`)
 

package/.docs/reference/workspace/vercel-microvm-sandbox.md

@@ -0,0 +1,199 @@
+# VercelMicroVMSandbox
+
+Executes commands inside [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) — an ephemeral [Firecracker](https://firecracker-microvm.github.io/) MicroVM running Amazon Linux 2023. Provides a persistent in-session filesystem, `sudo` access, exposed ports, and background processes.
+
+> **Info:** For interface details, see the [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+> **Note:** This is distinct from [`VercelSandbox`](https://mastra.ai/reference/workspace/vercel), which runs commands as stateless Vercel serverless **Functions**. `VercelMicroVMSandbox` runs a full Linux MicroVM with a persistent filesystem and long-running processes.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/vercel
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/vercel
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/vercel
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/vercel
+```
+
+## Authentication
+
+The `@vercel/sandbox` SDK uses a Vercel OIDC token automatically when available.
+
+**OIDC (recommended)**:
+
+For local development, link the project and pull a development token:
+
+```bash
+vercel link
+vercel env pull
+```
+
+On Vercel, authentication is handled automatically — no configuration needed.
+
+**Access token (.env)**:
+
+For environments without OIDC, provide all three values together:
+
+```bash
+VERCEL_TOKEN=your-token
+VERCEL_TEAM_ID=your-team-id
+VERCEL_PROJECT_ID=your-project-id
+```
+
+**Constructor**:
+
+```typescript
+new VercelMicroVMSandbox({
+  token: 'your-token',
+  teamId: 'your-team-id',
+  projectId: 'your-project-id',
+})
+```
+
+## Usage
+
+Add a `VercelMicroVMSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { VercelMicroVMSandbox } from '@mastra/vercel'
+
+const workspace = new Workspace({
+  sandbox: new VercelMicroVMSandbox({
+    runtime: 'node24',
+    timeout: 600_000,
+  }),
+})
+
+const agent = new Agent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  instructions: 'You are a coding assistant working in this workspace.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+
+const response = await agent.generate('Print "Hello, world!" and show the Node.js version.')
+
+console.log(response.text)
+```
+
+### Resources and exposed ports
+
+Allocate vCPUs (2048 MB of memory per vCPU) and expose ports to reach network services running inside the sandbox:
+
+```typescript
+const sandbox = new VercelMicroVMSandbox({
+  runtime: 'node24',
+  resources: { vcpus: 4 },
+  ports: [3000],
+})
+
+const workspace = new Workspace({ sandbox })
+await sandbox._start()
+
+// The public HTTPS domain for an exposed port is available via getInfo()
+const { metadata } = sandbox.getInfo()
+console.log(metadata?.domains) // { 3000: 'https://....vercel.run' }
+```
+
+### Streaming output
+
+Stream command output in real time via `onStdout` and `onStderr` callbacks:
+
+```typescript
+await sandbox.executeCommand('sh', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
+  onStdout: chunk => process.stdout.write(chunk),
+  onStderr: chunk => process.stderr.write(chunk),
+})
+```
+
+Both callbacks are optional and can be used independently.
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**sandboxName** (`string`): Optional name passed to the Vercel API. Auto-generated if omitted.
+
+**token** (`string`): Vercel API token. Falls back to the VERCEL\_TOKEN environment variable. Omit to use the OIDC token.
+
+**teamId** (`string`): Vercel team ID. Falls back to the VERCEL\_TEAM\_ID environment variable.
+
+**projectId** (`string`): Vercel project ID. Falls back to the VERCEL\_PROJECT\_ID environment variable.
+
+**runtime** (`'node24' | 'node22' | 'node26' | 'python3.13'`): Sandbox runtime. (Default: `'node24'`)
+
+**timeout** (`number`): Timeout in milliseconds before the sandbox auto-terminates. (Default: `300000 (5 minutes)`)
+
+**resources** (`{ vcpus?: number }`): Resource allocation. Each vCPU comes with 2048 MB of memory.
+
+**ports** (`number[]`): Ports to expose from the sandbox (up to 4). Public HTTPS domains are available via getInfo().metadata.domains.
+
+**env** (`Record<string, string>`): Default environment variables inherited by all commands. (Default: `{}`)
+
+**metadata** (`Record<string, unknown>`): Custom metadata surfaced via getInfo(). (Default: `{}`)
+
+**instructions** (`string | ((opts) => string)`): Override the default instructions returned by getInstructions(). Pass a string to replace them, or a function to extend the defaults.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('VercelMicroVMSandbox').
+
+**provider** (`string`): Provider identifier ('vercel-microvm').
+
+**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
+
+**sandbox** (`Sandbox`): The underlying @vercel/sandbox Sandbox instance. Throws SandboxNotReadyError if the sandbox has not been started.
+
+**processes** (`VercelMicroVMProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
+
+## Background processes
+
+`VercelMicroVMSandbox` includes a process manager for spawning and managing background processes. Each spawned process runs as a detached command inside the MicroVM, with output streamed through the command logs.
+
+```typescript
+const sandbox = new VercelMicroVMSandbox({ runtime: 'node24', ports: [3000] })
+await sandbox.start()
+
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+console.log(handle.stdout)
+await handle.kill()
+```
+
+See the [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+> **Note:** The Vercel Sandbox SDK does not expose a stdin channel for running commands, so `handle.sendStdin()` throws. Filesystem mounting (FUSE) is also not supported by this provider.
+
+## Limits
+
+- Up to 8 vCPUs, with 2048 MB of memory per vCPU.
+- Up to 4 exposed ports.
+- The filesystem is ephemeral — persisted only within the session and lost when the sandbox stops.
+- Maximum runtime is plan-dependent (45 minutes on Hobby, up to 5 hours on Pro/Enterprise), with a default of 5 minutes.
+
+See the [Vercel Sandbox documentation](https://vercel.com/docs/vercel-sandbox) for current limits and pricing.

package/.docs/reference/workspace/vercel.md

@@ -6,6 +6,8 @@ Executes commands as [Vercel](https://vercel.com) serverless functions. Provides
 
 > **Warning:** VercelSandbox is stateless. There is no persistent filesystem, no interactive shell, and no support for long-running or background processes. Only `/tmp` is writable and is ephemeral between invocations.
 
+> **Note:** For a full Linux MicroVM with a persistent filesystem, `sudo` access, exposed ports, and background processes, use [`VercelMicroVMSandbox`](https://mastra.ai/reference/workspace/vercel-microvm-sandbox), which is backed by the [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) product.
+
 ## Installation
 
 **npm**:

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @mastra/mcp-docs-server
 
+## 1.1.42-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`8ace89d`](https://github.com/mastra-ai/mastra/commit/8ace89df77f762e622d3b9f7f65ad7524350d050), [`fa63872`](https://github.com/mastra-ai/mastra/commit/fa6387280954e6b667bec5714b55ba082bc627ff), [`f07b646`](https://github.com/mastra-ai/mastra/commit/f07b64604ab7d25391179790b7fd4823df9e2dff), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`40f9297`](https://github.com/mastra-ai/mastra/commit/40f9297003b921c62373d3e8d3a4bda76c9f6de3), [`0f0d1ba`](https://github.com/mastra-ai/mastra/commit/0f0d1ba67bfcb2204e571401662f1eceefc03357), [`8c31bcd`](https://github.com/mastra-ai/mastra/commit/8c31bcdb00e597880d5939b1b7d7566fbe5dacae), [`95b14cd`](https://github.com/mastra-ai/mastra/commit/95b14cdd820e86d97ac05fe568424c513a252e31), [`0e51c36`](https://github.com/mastra-ai/mastra/commit/0e51c362be673502ac79626a75d1416479b0b76e), [`aa36be2`](https://github.com/mastra-ai/mastra/commit/aa36be23aa513b7dc53cb8ca16b7fab8f20e43ad), [`212c635`](https://github.com/mastra-ai/mastra/commit/212c635203e61d036ab41db8ff86c3893dc795b3), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`9aa5a73`](https://github.com/mastra-ai/mastra/commit/9aa5a73e7e110f6e9365eec69364a33d5f03bb56), [`f73c789`](https://github.com/mastra-ai/mastra/commit/f73c789e8ef21561580395d2c410119cab5848c8), [`8bd16da`](https://github.com/mastra-ai/mastra/commit/8bd16da73a4cb874d739373643dbd6a6e7f88684), [`c8630f8`](https://github.com/mastra-ai/mastra/commit/c8630f80d4f40cb5d22e60ab162b618b1907167a), [`47f71dc`](https://github.com/mastra-ai/mastra/commit/47f71dc6fbcbd12d71e21a979e676e20a02bd77d), [`50ceae2`](https://github.com/mastra-ai/mastra/commit/50ceae270878e2f8fb2b2c6c2faab09df0007c8a), [`8cdde58`](https://github.com/mastra-ai/mastra/commit/8cdde5875bbba6702d9df226f2b20232b8d75d6c), [`847ff1e`](https://github.com/mastra-ai/mastra/commit/847ff1e0d94368d94b2e173e4e0908e115568ef3), [`259d409`](https://github.com/mastra-ai/mastra/commit/259d409a514174299dbde1ff5e1121209b3ba850), [`9e16c68`](https://github.com/mastra-ai/mastra/commit/9e16c6818b6485ccb43df28aba6f3a2219d28662), [`cefca33`](https://github.com/mastra-ai/mastra/commit/cefca33ae666e69810c935fedf95a929c173d1d7), [`d00e8c5`](https://github.com/mastra-ai/mastra/commit/d00e8c50daebe5bce5bf2f48bde39c86fc3d2fe4), [`36fa7e2`](https://github.com/mastra-ai/mastra/commit/36fa7e24d14e58a1eb46147097b32f583e5b8775), [`87e9774`](https://github.com/mastra-ai/mastra/commit/87e97741c1e493cd6d62f478eb810b49bda4d57c), [`65a72e7`](https://github.com/mastra-ai/mastra/commit/65a72e70c25eedea8ff985a6624b96be2850236b), [`0f77241`](https://github.com/mastra-ai/mastra/commit/0f7724108806703799a8ba80ad0f09414afd5066), [`92ff509`](https://github.com/mastra-ai/mastra/commit/92ff5098ef8a990438ca038077021a5f7541ec1d), [`3fce5e7`](https://github.com/mastra-ai/mastra/commit/3fce5e70d011d289043e75003ef3336ed4aa43c3), [`a763592`](https://github.com/mastra-ai/mastra/commit/a763592c3db46963ef1011cfe16fe372816e775e), [`80c7737`](https://github.com/mastra-ai/mastra/commit/80c7737e32d7917b5f356957d67c169d01744fd3), [`3f1cf47`](https://github.com/mastra-ai/mastra/commit/3f1cf476f74c1e4cc2df908837e05853a5347e31)]:
+  - @mastra/core@1.38.0-alpha.3
+  - @mastra/mcp@1.9.0-alpha.0
+
 ## 1.1.42-alpha.3
 
 ### Patch Changes

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.42-alpha.4",
+  "version": "1.1.42-alpha.5",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": "dist/stdio.js",
   "files": [
     "dist",
     ".docs",
@@ -29,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.38.0-alpha.2",
-    "@mastra/mcp": "^1.8.1"
+    "@mastra/mcp": "^1.9.0-alpha.0",
+    "@mastra/core": "1.38.0-alpha.3"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +45,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.74",
     "@internal/lint": "0.0.99",
-    "@mastra/core": "1.38.0-alpha.2"
+    "@internal/types-builder": "0.0.74",
+    "@mastra/core": "1.38.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {
@@ -68,5 +67,8 @@
     "pretest": "pnpm turbo build --filter @mastra/mcp-docs-server",
     "test": "vitest run",
     "lint": "eslint ."
+  },
+  "bin": {
+    "mcp-docs-server": "dist/stdio.js"
   }
 }