@mastra/mcp-docs-server 1.2.4-alpha.1 → 1.2.4-alpha.5

package/.docs/reference/workspace/apple-container-sandbox.md

@@ -0,0 +1,257 @@
+# AppleContainerSandbox
+
+Executes commands inside local OCI Linux containers through Apple's [`container`](https://github.com/apple/container) CLI. The provider starts a long-lived container and uses `container exec` for workspace commands.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/apple-container
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/apple-container
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/apple-container
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/apple-container
+```
+
+Requires an Apple silicon Mac running macOS 26 or newer with Apple's `container` CLI installed. Start the container system before using the provider:
+
+```bash
+container system start
+```
+
+## Usage
+
+Add an `AppleContainerSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { AppleContainerSandbox } from '@mastra/apple-container'
+
+const workspace = new Workspace({
+  sandbox: new AppleContainerSandbox({
+    image: 'node:22-slim',
+    volumes: {
+      '/Users/me/project': '/workspace',
+    },
+    workingDir: '/workspace',
+  }),
+})
+
+const agent = new Agent({
+  id: 'dev-agent',
+  name: 'Dev Agent',
+  instructions: 'You are a coding assistant working in this workspace.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+
+const response = await agent.generate('Run `node --version`.')
+console.log(response.text)
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**name** (`string`): Apple container name passed to \`container run --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`): OCI image to use for the container. (Default: `'node:22-slim'`)
+
+**command** (`string[]`): Container init 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 and on command execs.
+
+**volumes** (`Record<string, string>`): Host-to-container bind mounts. Keys are host paths, values are container paths.
+
+**mounts** (`string[]`): Raw \`container run --mount\` specs.
+
+**network** (`string`): Apple container network attachment spec.
+
+**publishedPorts** (`string[]`): Port publish specs passed as \`--publish\`.
+
+**publishedSockets** (`string[]`): Socket publish specs passed as \`--publish-socket\`.
+
+**cpus** (`number | string`): Number of CPUs to allocate.
+
+**memory** (`string`): Memory allocation, for example '1G'.
+
+**platform** (`string`): OCI platform, for example 'linux/arm64'.
+
+**arch** (`string`): Image architecture when selecting a multi-arch image.
+
+**os** (`string`): Image operating system when selecting a multi-platform image.
+
+**rosetta** (`boolean`): Enable Rosetta in the container. (Default: `false`)
+
+**readonlyRootfs** (`boolean`): Mount the container root filesystem as read-only. (Default: `false`)
+
+**ssh** (`boolean`): Forward the host SSH agent socket. (Default: `false`)
+
+**init** (`boolean`): Enable Apple's init process in the container. (Default: `true`)
+
+**virtualization** (`boolean`): Expose virtualization capabilities to the container. (Default: `false`)
+
+**capAdd** (`string[]`): Linux capabilities to add.
+
+**capDrop** (`string[]`): Linux capabilities to drop.
+
+**tmpfs** (`string[]`): tmpfs destination paths passed as \`--tmpfs\`, for example \`/tmp\`.
+
+**dns** (`string[]`): DNS nameserver IPs.
+
+**dnsSearch** (`string[]`): DNS search domains.
+
+**noDns** (`boolean`): Do not configure DNS in the container. (Default: `false`)
+
+**labels** (`Record<string, string>`): Additional container labels. Mastra labels (mastra.sandbox, mastra.sandbox.id) are always included.
+
+**workingDir** (`string`): Working directory inside the container. (Default: `'/workspace'`)
+
+**timeout** (`number`): Default command timeout in milliseconds. (Default: `300000 (5 minutes)`)
+
+**deleteOnDestroy** (`boolean`): Delete the Apple container when the sandbox is destroyed. When false, destroy stops the container instead. (Default: `true`)
+
+**containerBinary** (`string`): Path or name for the Apple container CLI. (Default: `'container'`)
+
+**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 ('AppleContainerSandbox').
+
+**provider** (`string`): Provider identifier ('apple-container').
+
+**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
+
+**containerId** (`string`): Apple container ID when known, otherwise the configured container name.
+
+## Environment variables
+
+Set environment variables at the container level with `env`. Per-command environment variables can also be passed through `executeCommand` options:
+
+```typescript
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  env: {
+    NODE_ENV: 'development',
+  },
+})
+
+await sandbox.executeCommand('node', ['-e', 'console.log(process.env.TASK_ID)'], {
+  env: { TASK_ID: '42' },
+})
+```
+
+## Bind mounts
+
+Mount host directories into the container using the `volumes` option:
+
+```typescript
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/Users/me/project': '/workspace/project',
+    '/Users/me/.npm': '/root/.npm',
+  },
+})
+```
+
+Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.
+
+## Resource and platform options
+
+Apple container CLI options can be passed through the constructor:
+
+```typescript
+const sandbox = new AppleContainerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/Users/me/project': '/workspace',
+  },
+  cpus: 2,
+  memory: '2G',
+  platform: 'linux/arm64',
+  readonlyRootfs: true,
+  tmpfs: ['/tmp'],
+})
+```
+
+These options are only applied when a new container is created. If the sandbox reconnects to an existing container with the same name, destroy and recreate the sandbox to apply changed runtime options. Apple `--tmpfs` accepts container paths only, such as `/tmp`; it does not accept Docker-style option specs like `/tmp:rw,size=256m`. When `readonlyRootfs` is enabled, make sure `workingDir` points to a path supplied by the image, a bind mount, or a writable tmpfs.
+
+## Security model
+
+`AppleContainerSandbox` runs local containers through the host Apple `container` service. Treat constructor options as trusted server-side configuration:
+
+- `volumes`, `mounts`, and `publishedSockets` can expose host paths to containerized code.
+- `publishedPorts` can expose in-container services on the host or network; bind to `127.0.0.1` when only local access is intended.
+- `ssh` forwards the host SSH agent socket.
+- `capAdd` and `virtualization` can expand what containerized code can do.
+- `containerBinary` is a constructor-only escape hatch for trusted code and is not part of the serializable editor provider schema.
+
+Use the narrowest mounts and capabilities your workload needs. Existing containers are only reconnected when they carry Mastra ownership labels for the sandbox ID. Containers created by this provider also include a config-hash label; when that label is present, reconnect fails if immutable runtime options such as image, command, mounts, ports, capabilities, or working directory changed.
+
+## Limitations
+
+`AppleContainerSandbox` implements foreground workspace command execution with `executeCommand()`. It does not yet expose a `SandboxProcessManager` for background processes or LSP sessions.
+
+Command timeouts are enforced inside the container so timed-out commands are cleaned up by the container runtime. Abort signals cancel the host CLI wait path and should not be used as a substitute for command timeouts when in-container cleanup matters.
+
+## Reconnection
+
+`AppleContainerSandbox` reconnects by inspecting a container with the configured name. When `start()` is called:
+
+- A running container is reused.
+- A stopped container is restarted.
+- A missing container is created from the configured image.
+- A container with the configured name but without matching Mastra ownership labels fails instead of being managed.
+- A Mastra-owned container with a config-hash label that does not match immutable runtime options fails instead of being reused.
+
+```typescript
+const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
+await sandbox.start()
+
+const sandbox2 = new AppleContainerSandbox({ id: 'persistent-sandbox' })
+await sandbox2.start()
+```
+
+## Editor provider
+
+Register the provider with `MastraEditor` to hydrate stored sandbox configs:
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+import { appleContainerSandboxProvider } from '@mastra/apple-container'
+
+const editor = new MastraEditor({
+  sandboxes: {
+    [appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
+  },
+})
+```
+
+## Related
+
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [DockerSandbox reference](https://mastra.ai/reference/workspace/docker-sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

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

@@ -48,6 +48,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

package/.docs/reference/workspace/azure-blob-filesystem.md

@@ -47,6 +47,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -48,6 +48,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -47,6 +47,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

package/.docs/reference/workspace/files-sdk-filesystem.md

@@ -57,6 +57,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -48,6 +48,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -0,0 +1,319 @@
+# MesaFilesystem
+
+Stores workspace files in [Mesa](https://docs.mesa.dev/content/getting-started/introduction) repos through the standard Mastra `WorkspaceFilesystem` interface.
+
+Use `MesaFilesystem` when agents need versioned file storage. For a local directory, use [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem). For object storage, use [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem), [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem), or [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem).
+
+> **Info:** `MesaFilesystem` runs in the Mastra process.
+>
+> [Mesa's POSIX mount](https://docs.mesa.dev/content/mesafs/posix-mount) (for using a Mesa filesystem within a sandbox) is not yet part of the `@mastra/mesa` package. Support is coming soon.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/mesa
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mesa
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mesa
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mesa
+```
+
+## Usage example
+
+Mount one Mesa repo and pass the filesystem to a workspace:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { MesaFilesystem } from '@mastra/mesa'
+
+const workspace = new Workspace({
+  filesystem: new MesaFilesystem({
+    apiKey: process.env.MESA_API_KEY,
+    org: 'acme',
+    repos: [{ name: 'docs', bookmark: 'main' }],
+  }),
+})
+
+const agent = new Agent({
+  id: 'file-agent',
+  name: 'file-agent',
+  model: 'anthropic/claude-opus-4-7',
+  workspace,
+})
+```
+
+`apiKey` falls back to `MESA_API_KEY` when omitted.
+
+## Constructor parameters
+
+**apiKey** (`string`): Mesa API key. Falls back to \`MESA\_API\_KEY\` when omitted.
+
+**org** (`string`): Mesa org slug. When omitted, the Mesa SDK resolves the default org.
+
+**repos** (`RepoConfig[]`): Mesa repos to mount.
+
+**cache** (`{ diskCache?: { path: string; maxSizeBytes?: number } }`): Mesa filesystem cache configuration.
+
+**ttl** (`number`): Mesa mount token lifetime in seconds.
+
+**readOnly** (`boolean`): Mount all repos as read-only. (Default: `false`)
+
+## Properties
+
+**id** (`string`): Filesystem instance identifier.
+
+**name** (`string`): Provider name (\`'MesaFilesystem'\`).
+
+**provider** (`string`): Provider identifier (\`'mesa'\`).
+
+**readOnly** (`boolean | undefined`): Whether write operations are blocked.
+
+**client** (`Mesa | undefined`): Mesa SDK client created by this provider. Undefined before initialization.
+
+**filesystem** (`MesaFileSystem`): Active Mesa filesystem. Access this after initialization when you need the raw Mesa SDK filesystem.
+
+**change** (`MesaFileSystem["change"]`): Mesa change management operations for the mounted filesystem.
+
+**bookmark** (`MesaFileSystem["bookmark"]`): Mesa bookmark management operations for the mounted filesystem.
+
+## Methods
+
+`MesaFilesystem` implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
+
+### File operations
+
+#### `readFile(path, options?)`
+
+Reads a file from Mesa.
+
+```typescript
+const content = await filesystem.readFile('/acme/docs/README.md', {
+  encoding: 'utf-8',
+})
+```
+
+Returns: `Promise<string | Buffer>`
+
+#### `writeFile(path, content, options?)`
+
+Writes a file to Mesa.
+
+```typescript
+await filesystem.writeFile('/acme/docs/report.md', '# Report')
+```
+
+Returns: `Promise<void>`
+
+#### `appendFile(path, content)`
+
+Appends content to a file.
+
+```typescript
+await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')
+```
+
+Returns: `Promise<void>`
+
+#### `deleteFile(path, options?)`
+
+Deletes a file.
+
+```typescript
+await filesystem.deleteFile('/acme/docs/old-report.md')
+```
+
+Returns: `Promise<void>`
+
+#### `copyFile(src, dest, options?)`
+
+Copies a file.
+
+```typescript
+await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')
+```
+
+Returns: `Promise<void>`
+
+#### `moveFile(src, dest, options?)`
+
+Moves or renames a file.
+
+```typescript
+await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')
+```
+
+Returns: `Promise<void>`
+
+### Directory operations
+
+#### `mkdir(path, options?)`
+
+Creates a directory.
+
+```typescript
+await filesystem.mkdir('/acme/docs/reports', { recursive: true })
+```
+
+Returns: `Promise<void>`
+
+#### `rmdir(path, options?)`
+
+Removes a directory.
+
+```typescript
+await filesystem.rmdir('/acme/docs/reports', { recursive: true })
+```
+
+Returns: `Promise<void>`
+
+#### `readdir(path, options?)`
+
+Lists directory entries.
+
+```typescript
+const entries = await filesystem.readdir('/acme/docs', {
+  recursive: true,
+  extension: '.md',
+})
+```
+
+Returns: `Promise<FileEntry[]>`
+
+### Path operations
+
+#### `exists(path)`
+
+Checks whether a path exists.
+
+```typescript
+const exists = await filesystem.exists('/acme/docs/README.md')
+```
+
+Returns: `Promise<boolean>`
+
+#### `stat(path)`
+
+Returns file or directory metadata.
+
+```typescript
+const stat = await filesystem.stat('/acme/docs/README.md')
+```
+
+Returns: `Promise<FileStat>`
+
+#### `realpath(path)`
+
+Returns the canonical path from Mesa.
+
+```typescript
+const realPath = await filesystem.realpath('/acme/docs/README.md')
+```
+
+Returns: `Promise<string>`
+
+### Mesa operations
+
+#### `bash(options?)`
+
+Creates a Mesa-backed Bash runtime for this filesystem.
+
+```typescript
+const bash = await filesystem.bash({
+  cwd: '/acme/docs',
+})
+```
+
+Returns: `Promise<Bash>`
+
+## Path semantics
+
+Methods expect absolute paths. For `MesaFilesystem`, paths are rooted at the Mesa mount and must include the org slug and repo name:
+
+```typescript
+await filesystem.readFile('/acme/docs/README.md')
+```
+
+Do not omit the leading slash:
+
+```typescript
+await filesystem.readFile('acme/docs/README.md') // Incorrect
+await filesystem.readFile('/acme/docs/README.md') // Correct
+```
+
+The org comes from `org` in the constructor, or from the Mesa SDK's default org inference when `org` is omitted. It still appears as the first path segment.
+
+When you mount multiple repos, each repo is available under the org segment:
+
+```typescript
+const filesystem = new MesaFilesystem({
+  org: 'acme',
+  repos: [
+    { name: 'docs', bookmark: 'main' },
+    { name: 'website', bookmark: 'main' },
+  ],
+})
+
+await filesystem.readFile('/acme/docs/README.md')
+await filesystem.readFile('/acme/website/package.json')
+```
+
+## Mesa versioning APIs
+
+Access the underlying Mesa filesystem for Mesa-specific change and bookmark operations:
+
+```typescript
+await filesystem.writeFile('/acme/docs/draft.md', 'Draft')
+
+const current = await filesystem.change.current({
+  repo: 'docs',
+})
+
+await filesystem.bookmark.move({
+  repo: 'docs',
+  name: 'main',
+  changeId: current.changeId,
+})
+```
+
+More details on versioning semantics can be found in [Mesa's docs](https://docs.mesa.dev/content/concepts/versioning).
+
+## Read-only mode
+
+Set `readOnly: true` to block write operations through Mastra:
+
+```typescript
+const filesystem = new MesaFilesystem({
+  repos: [{ name: 'docs', bookmark: 'main' }],
+  readOnly: true,
+})
+```
+
+Read operations still work. Write operations throw `WorkspaceReadOnlyError`.
+
+## Concurrency
+
+`overwrite: false` and `expectedMtime` use preflight checks before writing. These checks are not atomic unless Mesa adds native conditional writes for app mounts.
+
+## Related
+
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
+- [Filesystem docs](https://mastra.ai/docs/workspace/filesystem)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Mesa documentation](https://docs.mesa.dev/content/getting-started/introduction)

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

@@ -49,6 +49,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'anthropic/claude-opus-4-7',
   workspace,

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

@@ -50,6 +50,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-sonnet-4-6',
   workspace,

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp-docs-server
 
+## 1.2.4-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`1340fb7`](https://github.com/mastra-ai/mastra/commit/1340fb76262a3ca062130aa71859f07257a0a5a4)]:
+  - @mastra/core@1.49.0-alpha.2
+
+## 1.2.4-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`cc440a3`](https://github.com/mastra-ai/mastra/commit/cc440a39400d8ce06655462b26c1666a1b3d4320), [`ea6327b`](https://github.com/mastra-ai/mastra/commit/ea6327ba2d63ca647804bc97b347e03a58617162), [`3439fa8`](https://github.com/mastra-ai/mastra/commit/3439fa836ecfcaa257b40c20b30ac2a8be22e9ea), [`85107f2`](https://github.com/mastra-ai/mastra/commit/85107f2758b527147fccbedff962961927c2d3b8), [`06ff9e0`](https://github.com/mastra-ai/mastra/commit/06ff9e0befd1d642ab87ff749285ee4091205c7e), [`7f5e1ff`](https://github.com/mastra-ai/mastra/commit/7f5e1ff695a92f672bb3976363925d1e9136b54a), [`b8375c1`](https://github.com/mastra-ai/mastra/commit/b8375c1f8fe905df8ae2ae9a893bb365f17aec4e), [`9ab5faa`](https://github.com/mastra-ai/mastra/commit/9ab5faaff673ee9953ab4604cec217ee57875cd5), [`003f35d`](https://github.com/mastra-ai/mastra/commit/003f35d19e07b23b4bacc591c8bc0c59b42124ae)]:
+  - @mastra/core@1.49.0-alpha.1
+  - @mastra/mcp@1.13.0-alpha.0
+
 ## 1.2.4-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.4-alpha.1",
+  "version": "1.2.4-alpha.5",
   "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.48.1-alpha.0",
-    "@mastra/mcp": "^1.12.1"
+    "@mastra/core": "1.49.0-alpha.2",
+    "@mastra/mcp": "^1.13.0-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -47,7 +47,7 @@
     "vitest": "4.1.8",
     "@internal/lint": "0.0.110",
     "@internal/types-builder": "0.0.85",
-    "@mastra/core": "1.48.1-alpha.0"
+    "@mastra/core": "1.49.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {