@mastra/mcp-docs-server 1.1.36 → 1.1.37-alpha.4

package/.docs/reference/voice/xai-realtime.md

@@ -0,0 +1,267 @@
+# xAI Realtime voice
+
+The `XAIRealtimeVoice` class provides realtime voice interaction capabilities using the xAI Grok Voice Agent API. It implements Mastra's `MastraVoice` realtime contract and supports bidirectional audio streaming, text turns, server VAD, xAI voices, function tools, and xAI server-side tools.
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { getMicrophoneStream, playAudio } from '@mastra/node-audio'
+import { XAIRealtimeVoice } from '@mastra/voice-xai-realtime'
+
+const voice = new XAIRealtimeVoice({
+  apiKey: process.env.XAI_API_KEY,
+  model: 'grok-voice-think-fast-1.0',
+  speaker: 'eve',
+  instructions: 'You are a concise voice assistant.',
+  turnDetection: { type: 'server_vad' },
+})
+
+const agent = new Agent({
+  id: 'voice-agent',
+  name: 'Voice Agent',
+  instructions: 'You are a helpful voice assistant.',
+  model: 'xai/grok-4.3',
+  voice,
+})
+
+await agent.voice.connect()
+
+agent.voice.on('speaker', audioStream => {
+  playAudio(audioStream)
+})
+
+agent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`)
+})
+
+await agent.voice.speak('How can I help you today?')
+
+const microphoneStream = getMicrophoneStream()
+await agent.voice.send(microphoneStream)
+
+agent.voice.close()
+```
+
+## Configuration
+
+### Constructor options
+
+**apiKey** (`string`): xAI API key. Falls back to the XAI\_API\_KEY environment variable.
+
+**ephemeralToken** (`string`): Short-lived xAI token sent with the WebSocket protocol instead of an authorization header.
+
+**model** (`XAIRealtimeModel`): The Grok voice model to use. (Default: `'grok-voice-think-fast-1.0'`)
+
+**speaker** (`XAIVoice`): Voice ID to use for speech output. Built-in values are eve, ara, rex, sal, and leo. Custom xAI voice IDs are also supported. (Default: `'eve'`)
+
+**instructions** (`string`): System instructions sent in session.update.
+
+**turnDetection** (`XAITurnDetection`): Voice activity detection configuration. (Default: `{ type: 'server_vad' }`)
+
+**audio** (`XAIAudioConfig`): Input and output audio format configuration. (Default: `24 kHz audio/pcm input and output`)
+
+**serverTools** (`XAIServerTool[]`): xAI server-side tools to send in session.update. Supports file\_search, web\_search, x\_search, and mcp. These are merged with session.tools.
+
+**session** (`Partial<XAISessionConfig>`): Additional xAI session fields to merge into the initial session.update event.
+
+**url** (`string`): Override the xAI realtime WebSocket URL. (Default: `'wss://api.x.ai/v1/realtime'`)
+
+**debug** (`boolean`): Enable debug logging for received xAI events. Debug logs can include transcripts and tool-call arguments. (Default: `false`)
+
+### VoiceConfig pattern
+
+You can also use Mastra's shared voice configuration shape:
+
+```typescript
+const voice = new XAIRealtimeVoice({
+  speaker: 'ara',
+  realtimeConfig: {
+    model: 'grok-voice-think-fast-1.0',
+    apiKey: process.env.XAI_API_KEY,
+    options: {
+      instructions: 'Answer briefly.',
+      turnDetection: { type: 'server_vad', threshold: 0.85 },
+    },
+  },
+})
+```
+
+## Authentication
+
+Use `apiKey` or `XAI_API_KEY` for server-side applications. This provider is built for Node.js server-side runtimes. If you already mint xAI ephemeral tokens on your server, you can pass one as `ephemeralToken`; the provider uses the `xai-client-secret.<token>` WebSocket protocol instead of an authorization header. If both `apiKey` and `ephemeralToken` are configured, the provider uses the ephemeral token.
+
+## Methods
+
+### `connect()`
+
+Establishes the WebSocket connection and sends the initial `session.update`.
+
+**requestContext** (`RequestContext`): Optional Mastra request context passed to function tool executions.
+
+Returns: `Promise<void>`
+
+### `close()`
+
+Closes the WebSocket connection, ends active speaker streams, and clears queued events, pending function-call state, and request context. `disconnect()` is an alias for `close()`.
+
+Returns: `void`
+
+### `addInstructions()`
+
+Sets session instructions. If the WebSocket is open, the provider sends a `session.update`; passing `undefined` stores an empty string and clears the active instructions on the current session or the next connection.
+
+**instructions** (`string`): System instructions to send to xAI.
+
+Returns: `void`
+
+### `addTools()`
+
+Registers Mastra function tools and, when connected, refreshes the session tools with `session.update`.
+
+**tools** (`ToolsInput`): Mastra tools to expose as xAI function tools.
+
+Returns: `void`
+
+### `updateConfig()`
+
+Sends a `session.update` event with additional xAI session fields.
+
+**sessionConfig** (`Partial<XAISessionConfig>`): Session fields to update.
+
+Returns: `void`
+
+### `speak()`
+
+Sends a text turn using `conversation.item.create` and then requests a response.
+
+**input** (`string | NodeJS.ReadableStream`): Text or a readable text stream to send as user input.
+
+**options.speaker** (`XAIVoice`): Voice override. This updates the active xAI session voice and is used for subsequent turns.
+
+**options.response** (`Record<string, unknown>`): Additional xAI response.create fields.
+
+Returns: `Promise<void>`
+
+### `send()`
+
+Streams realtime audio chunks with `input_audio_buffer.append`.
+
+`send()` requires an open connection. Use it for live microphone audio after `connect()` resolves. Readable stream chunks must be binary audio chunks (`Buffer`, `ArrayBuffer`, or a typed array).
+
+**audioData** (`NodeJS.ReadableStream | Int16Array`): PCM audio stream or Int16Array audio data.
+
+**eventId** (`string`): Optional xAI event ID.
+
+Returns: `Promise<void>`
+
+### `listen()`
+
+Sends a finite audio stream with `input_audio_buffer.append`. By default it commits the input buffer and requests a response.
+
+**audioData** (`NodeJS.ReadableStream`): Audio stream to send.
+
+**options.commit** (`boolean`): Whether to send input\_audio\_buffer.commit after the audio item. (Default: `true`)
+
+**options.createResponse** (`boolean`): Whether to send response.create after the audio item. (Default: `true`)
+
+Returns: `Promise<void>`
+
+### `answer()`
+
+Sends `response.create` to ask xAI to continue the conversation.
+
+Returns: `Promise<void>`
+
+### `commitAudioBuffer()` and `clearAudioBuffer()`
+
+Send the matching xAI realtime client events for manual turn control.
+
+Returns: `Promise<void>`
+
+### `cancelResponse()`
+
+Sends `response.cancel` to interrupt an in-flight response.
+
+**responseId** (`string`): Optional xAI response ID to cancel.
+
+**eventId** (`string`): Optional xAI event ID.
+
+Returns: `Promise<void>`
+
+## Events
+
+`XAIRealtimeVoice` maps xAI realtime server events onto Mastra voice events:
+
+- `speaker`: emits a readable stream for assistant audio.
+- `speaking`: emits assistant audio deltas.
+- `speaking.done`: emits when an assistant audio response completes.
+- `writing`: emits assistant text deltas and user input transcriptions.
+- `error`: emits xAI errors, provider execution errors, tool execution errors, and malformed function-call arguments. Tool errors include `details.call_id` and `details.name`.
+- `close`: emits when the WebSocket closes.
+- `tool-call-start`: emits before a Mastra function tool is executed.
+- `tool-call-result`: emits after a Mastra function tool returns.
+
+Raw xAI event names are also emitted, so you can subscribe to events such as `response.output_audio.delta`, `response.text.delta`, `response.function_call_arguments.done`, and `response.done`.
+
+## Tools
+
+### Mastra function tools
+
+Tools added with `addTools()` are converted into xAI function tools and included in `session.update`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const weatherTool = createTool({
+  id: 'getWeather',
+  description: 'Get current weather for a location.',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  execute: async ({ location }) => {
+    return { location, temperature: 22 }
+  },
+})
+
+voice.addTools({ getWeather: weatherTool })
+```
+
+When xAI emits `response.function_call_arguments.done`, the provider executes the matching Mastra tool and sends a `function_call_output` item. If xAI emits multiple function calls for one response, the provider waits for every tool result and the response's `response.done` event before sending one continuation `response.create`.
+
+### xAI server-side tools
+
+xAI server-side tools are passed through in the session configuration and executed by xAI. Tools passed in `session.tools` and `serverTools` are merged:
+
+```typescript
+const voice = new XAIRealtimeVoice({
+  apiKey: process.env.XAI_API_KEY,
+  serverTools: [
+    { type: 'web_search' },
+    { type: 'x_search', allowed_x_handles: ['xai'] },
+    { type: 'file_search', vector_store_ids: ['collection_123'], max_num_results: 10 },
+    {
+      type: 'mcp',
+      server_url: 'https://mcp.example.com/mcp',
+      server_label: 'business-tools',
+      allowed_tools: ['lookup_order'],
+    },
+  ],
+})
+```
+
+## Audio formats
+
+The default input and output format is 24 kHz PCM16. You can also configure supported PCM sample rates or telephony codecs:
+
+```typescript
+const voice = new XAIRealtimeVoice({
+  audio: {
+    input: { format: { type: 'audio/pcm', rate: 16000 } },
+    output: { format: { type: 'audio/pcm', rate: 16000 } },
+  },
+})
+```
+
+Supported format types are `audio/pcm`, `audio/pcmu`, and `audio/pcma`. PCM supports the documented sample rates from 8 kHz through 48 kHz. `audio/pcmu` and `audio/pcma` are G.711 telephony codecs and use 8 kHz.

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

@@ -70,6 +70,30 @@ const agent = new Agent({
 
 **privileged** (`boolean`): Run in privileged mode. (Default: `false`)
 
+**memory** (`number`): Memory limit in bytes. Docker treats 0 as unlimited. Maps to Docker HostConfig.Memory.
+
+**memorySwap** (`number`): Total memory plus swap in bytes. Maps to Docker HostConfig.MemorySwap.
+
+**cpuShares** (`number`): CPU shares relative weight. Maps to Docker HostConfig.CpuShares.
+
+**cpuQuota** (`number`): CPU quota in microseconds per period. Maps to Docker HostConfig.CpuQuota.
+
+**cpuPeriod** (`number`): CPU period in microseconds. Maps to Docker HostConfig.CpuPeriod.
+
+**pidsLimit** (`number`): Maximum number of process IDs in the container. Maps to Docker HostConfig.PidsLimit.
+
+**readonlyRootfs** (`boolean`): Mount the container root filesystem as read-only. Maps to Docker HostConfig.ReadonlyRootfs.
+
+**capDrop** (`string[]`): Linux capabilities to drop. Use \['ALL'] to drop all capabilities before adding specific ones. Maps to Docker HostConfig.CapDrop.
+
+**capAdd** (`string[]`): Linux capabilities to add back after drops, such as NET\_BIND\_SERVICE. Maps to Docker HostConfig.CapAdd.
+
+**securityOpt** (`string[]`): Docker security options, such as \['no-new-privileges:true']. Maps to Docker HostConfig.SecurityOpt.
+
+**ulimits** (`Array<{ name: string; soft: number; hard: number }>`): Ulimit entries for the container. Maps to Docker HostConfig.Ulimits.
+
+**tmpfs** (`Record<string, string>`): tmpfs mount paths and options. Maps to Docker HostConfig.Tmpfs.
+
 **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.
@@ -146,6 +170,42 @@ const sandbox = new DockerSandbox({
 
 Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.
 
+## Hardening
+
+Use Docker-specific resource and hardening options to limit a sandbox container. The following example caps memory and process count, limits CPU to a single core with matching `cpuPeriod` and `cpuQuota` values, drops Linux capabilities, makes the root filesystem read-only, and mounts `/tmp` as writable scratch space:
+
+```typescript
+const sandbox = new DockerSandbox({
+  image: 'node:22-slim',
+  memory: 512 * 1024 * 1024,
+  memorySwap: 512 * 1024 * 1024,
+  cpuPeriod: 100_000,
+  cpuQuota: 100_000,
+  pidsLimit: 256,
+  readonlyRootfs: true,
+  capDrop: ['ALL'],
+  capAdd: ['NET_BIND_SERVICE'],
+  securityOpt: ['no-new-privileges:true'],
+  ulimits: [{ name: 'nofile', soft: 1024, hard: 2048 }],
+  tmpfs: {
+    '/tmp': 'rw,noexec,nosuid,size=64m',
+  },
+})
+```
+
+These options map directly to Docker `HostConfig` fields and aren't set unless you pass them.
+
+Review these trade-offs before enabling hardening:
+
+- `readonlyRootfs`: In-container package installs and tools that write outside mounted paths can fail. Add `tmpfs` entries for writable scratch paths such as `/tmp`, and mount tmpfs or volumes for package-manager caches such as `~/.npm` when needed.
+- `capDrop`: Dropping all capabilities disables commands that need Linux capabilities, including `ping`, mount operations, and FUSE-backed tools. Add back only the capabilities your workload needs.
+- `memory`: Docker treats `0` as unlimited. Omit `memory` or pass `0` only when you don't want a memory cap.
+- `memorySwap`: Docker memory and swap behavior depends on the host and Docker daemon configuration. When you set `memory` without `memorySwap`, Docker allows swap up to twice the memory limit by default. Set `memorySwap` equal to `memory` when you want to disable swap for the container; Docker also accepts `-1` for unlimited swap.
+- `pidsLimit`: Very low values can break `docker exec` workloads because each command starts additional processes inside the long-lived container.
+- `privileged`: Privileged containers bypass capability and security-option controls. Don't combine `privileged: true` with capability or security options unless the workload requires it.
+- Reconnection: `DockerSandbox` reuses an existing container when the sandbox ID matches and warns if inspected `HostConfig` hardening values differ. Destroy and recreate the sandbox to apply changed hardening options. Docker can normalize inspected values, and changing `memorySwap` on reconnect can trigger a warning if the original container used Docker's default swap behavior.
+- Docker Desktop: Resource limits apply inside the Docker Desktop virtual machine on macOS and Windows, so the VM's allocated resources can cap what containers receive.
+
 ## 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:

package/.docs/reference/workspace/workspace-class.md

@@ -290,19 +290,39 @@ A workspace provides tools to agents based on what's configured.
 
 Added when a filesystem is configured:
 
-| Tool                          | Description                                                                                                                                                |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mastra_workspace_read_file`  | Read file contents. Supports optional line range for reading specific portions of large files.                                                             |
-| `mastra_workspace_write_file` | Create or overwrite a file with new content. Creates parent directories automatically.                                                                     |
-| `mastra_workspace_edit_file`  | Edit an existing file by finding and replacing text. Useful for targeted changes without rewriting the entire file.                                        |
-| `mastra_workspace_list_files` | List directory contents as a tree structure. Supports recursive listing with depth limits, glob patterns, and `.gitignore` filtering (enabled by default). |
-| `mastra_workspace_delete`     | Delete a file or directory. Supports recursive deletion for directories.                                                                                   |
-| `mastra_workspace_file_stat`  | Get metadata about a file or directory including size, type, and modification time.                                                                        |
-| `mastra_workspace_mkdir`      | Create a directory. Creates parent directories automatically if they don't exist.                                                                          |
-| `mastra_workspace_grep`       | Search file contents using regex patterns. Supports glob filtering, context lines, and case-insensitive search.                                            |
+| Tool                          | Description                                                                                                                                                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mastra_workspace_read_file`  | Read file contents. Text files return as text (with optional line range). Images and PDFs return as native media parts the model can view directly. Other binaries return metadata only unless an explicit `encoding` is passed. |
+| `mastra_workspace_write_file` | Create or overwrite a file with new content. Creates parent directories automatically.                                                                                                                                           |
+| `mastra_workspace_edit_file`  | Edit an existing file by finding and replacing text. Useful for targeted changes without rewriting the entire file.                                                                                                              |
+| `mastra_workspace_list_files` | List directory contents as a tree structure. Supports recursive listing with depth limits, glob patterns, and `.gitignore` filtering (enabled by default).                                                                       |
+| `mastra_workspace_delete`     | Delete a file or directory. Supports recursive deletion for directories.                                                                                                                                                         |
+| `mastra_workspace_file_stat`  | Get metadata about a file or directory including size, type, and modification time.                                                                                                                                              |
+| `mastra_workspace_mkdir`      | Create a directory. Creates parent directories automatically if they don't exist.                                                                                                                                                |
+| `mastra_workspace_grep`       | Search file contents using regex patterns. Supports glob filtering, context lines, and case-insensitive search.                                                                                                                  |
 
 With a static filesystem, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded when the filesystem is in read-only mode. With a [dynamic filesystem](https://mastra.ai/docs/workspace/filesystem), write tools are always included and read-only is enforced at runtime.
 
+The `read_file` tool accepts `mediaTypes` and `maxMediaBytes` options to control which mime types are surfaced to the model as native media parts and how large those files can be:
+
+**mediaTypes** (`string[] | ((mimeType: string) => boolean) | false`): Which mime types to surface to the model as media parts (file/image parts) rather than as text. Accepts an array of globs (e.g. \`\['image/\*']\`), a custom predicate function, or \`false\` to disable media detection. Defaults to the cross-provider-safe intersection of image formats plus PDF. Only applies when the caller doesn't pass an explicit \`encoding\`. (Default: `['image/png', 'image/jpeg', 'image/webp', 'application/pdf']`)
+
+**maxMediaBytes** (`number`): Maximum file size (in bytes) to inline as a media part. Files larger than this fall back to metadata-only output rather than being fully base64-encoded into context and persisted in storage on rehydration. (Default: `10 * 1024 * 1024 (10 MiB)`)
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  tools: {
+    [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: {
+      // Broaden to any image (including SVG, BMP, HEIC) — may fail on some providers
+      mediaTypes: ['image/*'],
+      // Raise the inline-media cap to 25 MiB
+      maxMediaBytes: 25 * 1024 * 1024,
+    },
+  },
+})
+```
+
 ### Sandbox tools
 
 Added when a sandbox is configured:

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @mastra/mcp-docs-server
 
+## 1.1.37-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`bdb4cbf`](https://github.com/mastra-ai/mastra/commit/bdb4cbf8ba4b685d7481f28bb9dc3de6c79c9ed2)]:
+  - @mastra/core@1.34.0-alpha.2
+
+## 1.1.37-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`fceae1f`](https://github.com/mastra-ai/mastra/commit/fceae1f5f5db4722cb078a663c6eb4bd22944123), [`bf02acb`](https://github.com/mastra-ai/mastra/commit/bf02acbb8a6110f638ac844e89f1ebf04cb7fe74), [`0fd3fbe`](https://github.com/mastra-ai/mastra/commit/0fd3fbe40fb63657aedd72f6e7b38c8e8ee6940d), [`fed0475`](https://github.com/mastra-ai/mastra/commit/fed0475ccfea31e4fc251469ac05640d0742c1f0), [`522f44d`](https://github.com/mastra-ai/mastra/commit/522f44d947214bfc06cff50599bae1ef3494880d)]:
+  - @mastra/core@1.34.0-alpha.1
+
+## 1.1.37-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`20787de`](https://github.com/mastra-ai/mastra/commit/20787de5965234a1af28fe35f49437c537dbfa0d), [`784ad98`](https://github.com/mastra-ai/mastra/commit/784ad989549de91dc5d33ab8ef36caa6f7dcd34e), [`0d53730`](https://github.com/mastra-ai/mastra/commit/0d53730c1ed87ef80c87caa5701c4170ea8028e6)]:
+  - @mastra/core@1.34.0-alpha.0
+
 ## 1.1.36
 
 ### Patch Changes

package/dist/stdio.js

@@ -1444,12 +1444,12 @@ var readSourceMapTool = {
     void logger.debug("Executing readMastraSourceMap tool", { args });
     const sourceMap = await readSourceMap(args.package, args.projectPath);
     if (!sourceMap) return `No SOURCE_MAP.json found for ${args.package}.`;
-    let exports$1 = Object.entries(sourceMap.exports);
+    let exports = Object.entries(sourceMap.exports);
     if (args.filter) {
       const filterLower = args.filter.toLowerCase();
-      exports$1 = exports$1.filter(([name]) => name.toLowerCase().includes(filterLower));
+      exports = exports.filter(([name]) => name.toLowerCase().includes(filterLower));
     }
-    if (exports$1.length === 0) {
+    if (exports.length === 0) {
       return args.filter ? `No exports matching "${args.filter}" in ${args.package}.
 
 Try running without a filter to see all available exports.` : `No exports found in ${args.package}.`;
@@ -1457,9 +1457,9 @@ Try running without a filter to see all available exports.` : `No exports found
     return [
       `# ${sourceMap.package} v${sourceMap.version} - API Exports`,
       "",
-      `Found ${exports$1.length} export(s)${args.filter ? ` matching "${args.filter}"` : ""}:`,
+      `Found ${exports.length} export(s)${args.filter ? ` matching "${args.filter}"` : ""}:`,
       "",
-      ...exports$1.map(([name, info]) => {
+      ...exports.map(([name, info]) => {
         const line = info.line ? `:${info.line}` : "";
         return `- **${name}**: \`${info.implementation}${line}\``;
       }),