@mastra/mcp-docs-server 1.1.37-alpha.1 → 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/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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

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}\``;
       }),