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

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,20 @@
 # @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
+
+- Updated dependencies [[`d779de3`](https://github.com/mastra-ai/mastra/commit/d779de3cd9d2e7ed8110547190e2f15e786a0e41), [`1750c97`](https://github.com/mastra-ai/mastra/commit/1750c975d6179fbf6db2813b15229d4f8f23fc55), [`0e32507`](https://github.com/mastra-ai/mastra/commit/0e32507962cdfa5569b7bda5bc6fb3dd34e40b03), [`3a081c1`](https://github.com/mastra-ai/mastra/commit/3a081c1255c5ae8c99f6dad91cc612934ef6f2bd), [`fe9eacd`](https://github.com/mastra-ai/mastra/commit/fe9eacd9545a0a9d64aad31c9fa90294a425289e), [`db79c86`](https://github.com/mastra-ai/mastra/commit/db79c86c60723d57e02f9636ca2611bd4515f194)]:
+  - @mastra/core@1.38.0-alpha.2
+
 ## 1.1.42-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.42-alpha.2",
+  "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.37.2-alpha.1",
-    "@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",
@@ -48,7 +47,7 @@
     "vitest": "4.1.5",
     "@internal/lint": "0.0.99",
     "@internal/types-builder": "0.0.74",
-    "@mastra/core": "1.37.2-alpha.1"
+    "@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"
   }
 }