@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/voice/voice.on.md

@@ -0,0 +1,111 @@
+# voice.on()
+
+The `on()` method registers event listeners for various voice events. This is particularly important for real-time voice providers, where events are used to communicate transcribed text, audio responses, and other state changes.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import Speaker from '@mastra/node-speaker'
+import chalk from 'chalk'
+
+// Initialize a real-time voice provider
+const voice = new OpenAIRealtimeVoice({
+  realtimeConfig: {
+    model: 'gpt-5.1-realtime',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+})
+
+// Connect to the real-time service
+await voice.connect()
+
+// Register event listener for transcribed text
+voice.on('writing', event => {
+  if (event.role === 'user') {
+    process.stdout.write(chalk.green(event.text))
+  } else {
+    process.stdout.write(chalk.blue(event.text))
+  }
+})
+
+// Listen for audio data and play it
+const speaker = new Speaker({
+  sampleRate: 24100,
+  channels: 1,
+  bitDepth: 16,
+})
+
+voice.on('speaker', stream => {
+  stream.pipe(speaker)
+})
+
+// Register event listener for errors
+voice.on('error', ({ message, code, details }) => {
+  console.error(`Error ${code}: ${message}`, details)
+})
+```
+
+## Parameters
+
+**event:** (`string`): Name of the event to listen for. See the \[Voice Events]\(./voice.events) documentation for a list of available events.
+
+**callback:** (`function`): Callback function that will be called when the event occurs. The callback signature depends on the specific event.
+
+## Return Value
+
+This method does not return a value.
+
+## Events
+
+For a comprehensive list of events and their payload structures, see the [Voice Events](https://mastra.ai/reference/voice/voice.events) documentation.
+
+Common events include:
+
+- `speaking`: Emitted when audio data is available
+- `speaker`: Emitted with a stream that can be piped to audio output
+- `writing`: Emitted when text is transcribed or generated
+- `error`: Emitted when an error occurs
+- `tool-call-start`: Emitted when a tool is about to be executed
+- `tool-call-result`: Emitted when a tool execution is complete
+
+Different voice providers may support different sets of events with varying payload structures.
+
+## Using with CompositeVoice
+
+When using `CompositeVoice`, the `on()` method delegates to the configured real-time provider:
+
+```typescript
+import { CompositeVoice } from '@mastra/core/voice'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import Speaker from '@mastra/node-speaker'
+
+const speaker = new Speaker({
+  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
+  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
+  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
+})
+
+const realtimeVoice = new OpenAIRealtimeVoice()
+const voice = new CompositeVoice({
+  realtime: realtimeVoice,
+})
+
+// Connect to the real-time service
+await voice.connect()
+
+// This will register the event listener with the OpenAIRealtimeVoice provider
+voice.on('speaker', stream => {
+  stream.pipe(speaker)
+})
+```
+
+## Notes
+
+- This method is primarily used with real-time voice providers that support event-based communication
+- If called on a voice provider that doesn't support events, it will log a warning and do nothing
+- Event listeners should be registered before calling methods that might emit events
+- To remove an event listener, use the [voice.off()](https://mastra.ai/reference/voice/voice.off) method with the same event name and callback function
+- Multiple listeners can be registered for the same event
+- The callback function will receive different data depending on the event type (see [Voice Events](https://mastra.ai/reference/voice/voice.events))
+- For best performance, consider removing event listeners when they are no longer needed

package/.docs/reference/voice/voice.send.md

@@ -0,0 +1,65 @@
+# voice.send()
+
+The `send()` method streams audio data in real-time to voice providers for continuous processing. This method is essential for real-time speech-to-speech conversations, allowing you to send microphone input directly to the AI service.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import Speaker from '@mastra/node-speaker'
+import { getMicrophoneStream } from '@mastra/node-audio'
+
+const speaker = new Speaker({
+  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
+  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
+  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
+})
+
+// Initialize a real-time voice provider
+const voice = new OpenAIRealtimeVoice({
+  realtimeConfig: {
+    model: 'gpt-5.1-realtime',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+})
+
+// Connect to the real-time service
+await voice.connect()
+
+// Set up event listeners for responses
+voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`)
+})
+
+voice.on('speaker', stream => {
+  stream.pipe(speaker)
+})
+
+// Get microphone stream (implementation depends on your environment)
+const microphoneStream = getMicrophoneStream()
+
+// Send audio data to the voice provider
+await voice.send(microphoneStream)
+
+// You can also send audio data as Int16Array
+const audioBuffer = getAudioBuffer() // Assume this returns Int16Array
+await voice.send(audioBuffer)
+```
+
+## Parameters
+
+**audioData:** (`NodeJS.ReadableStream | Int16Array`): Audio data to send to the voice provider. Can be a readable stream (like a microphone stream) or an Int16Array of audio samples.
+
+## Return Value
+
+Returns a `Promise<void>` that resolves when the audio data has been accepted by the voice provider.
+
+## Notes
+
+- This method is only implemented by real-time voice providers that support speech-to-speech capabilities
+- If called on a voice provider that doesn't support this functionality, it will log a warning and resolve immediately
+- You must call `connect()` before using `send()` to establish the WebSocket connection
+- The audio format requirements depend on the specific voice provider
+- For continuous conversation, you typically call `send()` to transmit user audio, then `answer()` to trigger the AI response
+- The provider will typically emit 'writing' events with transcribed text as it processes the audio
+- When the AI responds, the provider will emit 'speaking' events with the audio response

package/.docs/reference/voice/voice.speak.md

@@ -0,0 +1,157 @@
+# voice.speak()
+
+The `speak()` method is a core function available in all Mastra voice providers that converts text to speech. It takes text input and returns an audio stream that can be played or saved.
+
+## Parameters
+
+**input:** (`string | NodeJS.ReadableStream`): Text to convert to speech. Can be a string or a readable stream of text.
+
+**options?:** (`object`): Options for speech synthesis
+
+**options.speaker?:** (`string`): Voice ID to use for this specific request. Overrides the default speaker set in the constructor.
+
+## Return Value
+
+Returns a `Promise<NodeJS.ReadableStream | void>` where:
+
+- `NodeJS.ReadableStream`: A stream of audio data that can be played or saved
+- `void`: When using a realtime voice provider that emits audio through events instead of returning it directly
+
+## Provider-Specific Options
+
+Each voice provider may support additional options specific to their implementation. Here are some examples:
+
+### OpenAI
+
+**options.speed?:** (`number`): Speech speed multiplier. Values between 0.25 and 4.0 are supported. (Default: `1.0`)
+
+### ElevenLabs
+
+**options.stability?:** (`number`): Voice stability. Higher values result in more stable, less expressive speech. (Default: `0.5`)
+
+**options.similarity\_boost?:** (`number`): Voice clarity and similarity to the original voice. (Default: `0.75`)
+
+### Google
+
+**options.languageCode?:** (`string`): Language code for the voice (e.g., 'en-US').
+
+**options.audioConfig?:** (`object`): Audio configuration options from Google Cloud Text-to-Speech API. (Default: `{ audioEncoding: 'LINEAR16' }`)
+
+### Murf
+
+**options.properties.rate?:** (`number`): Speech rate multiplier.
+
+**options.properties.pitch?:** (`number`): Voice pitch adjustment.
+
+**options.properties.format?:** (`'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'`): Output audio format.
+
+## Usage Example
+
+```typescript
+import { OpenAIVoice } from '@mastra/voice-openai'
+// Initialize a voice provider
+const voice = new OpenAIVoice({
+  speaker: 'alloy', // Default voice
+})
+// Basic usage with default settings
+const audioStream = await voice.speak('Hello, world!')
+// Using a different voice for this specific request
+const audioStreamWithDifferentVoice = await voice.speak('Hello again!', {
+  speaker: 'nova',
+})
+// Using provider-specific options
+const audioStreamWithOptions = await voice.speak('Hello with options!', {
+  speaker: 'echo',
+  speed: 1.2, // OpenAI-specific option
+})
+// Using a text stream as input
+import { Readable } from 'stream'
+const textStream = Readable.from(['Hello', ' from', ' a', ' stream!'])
+const audioStreamFromTextStream = await voice.speak(textStream)
+```
+
+## Using with CompositeVoice
+
+When using `CompositeVoice`, the `speak()` method delegates to the configured speaking provider:
+
+```typescript
+import { CompositeVoice } from '@mastra/core/voice'
+import { OpenAIVoice } from '@mastra/voice-openai'
+import { PlayAIVoice } from '@mastra/voice-playai'
+
+const voice = new CompositeVoice({
+  output: new PlayAIVoice(),
+  input: new OpenAIVoice(),
+})
+
+// This will use the PlayAIVoice provider
+const audioStream = await voice.speak('Hello, world!')
+```
+
+### Using AI SDK Model Providers
+
+You can also use AI SDK speech models directly with `CompositeVoice`:
+
+```typescript
+import { CompositeVoice } from '@mastra/core/voice'
+import { openai } from '@ai-sdk/openai'
+import { elevenlabs } from '@ai-sdk/elevenlabs'
+
+// Use AI SDK speech models
+const voice = new CompositeVoice({
+  output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK model
+  input: openai.transcription('whisper-1'), // AI SDK model
+})
+
+// Works the same way
+const audioStream = await voice.speak('Hello from AI SDK!')
+
+// Provider-specific options can be passed through
+const audioWithOptions = await voice.speak('Hello with options!', {
+  speaker: 'Rachel', // ElevenLabs voice
+  providerOptions: {
+    elevenlabs: {
+      stability: 0.5,
+      similarity_boost: 0.75,
+    },
+  },
+})
+```
+
+See the [CompositeVoice reference](https://mastra.ai/reference/voice/composite-voice) for more details on AI SDK integration.
+
+## Realtime Voice Providers
+
+When using realtime voice providers like `OpenAIRealtimeVoice`, the `speak()` method behaves differently:
+
+- Instead of returning an audio stream, it emits a 'speaking' event with the audio data
+- You need to register an event listener to receive the audio chunks
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+import Speaker from '@mastra/node-speaker'
+
+const speaker = new Speaker({
+  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
+  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
+  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
+})
+
+const voice = new OpenAIRealtimeVoice()
+await voice.connect()
+// Register event listener for audio chunks
+voice.on('speaker', stream => {
+  // Handle audio chunk (e.g., play it or save it)
+  stream.pipe(speaker)
+})
+// This will emit 'speaking' events instead of returning a stream
+await voice.speak('Hello, this is realtime speech!')
+```
+
+## Notes
+
+- The behavior of `speak()` may vary slightly between providers, but all implementations follow the same basic interface.
+- When using a realtime voice provider, the method might not return an audio stream directly but instead emit a 'speaking' event.
+- If a text stream is provided as input, the provider will typically convert it to a string before processing.
+- The audio format of the returned stream depends on the provider. Common formats include MP3, WAV, and OGG.
+- For best performance, consider closing or ending the audio stream when you're done with it.

package/.docs/reference/voice/voice.updateConfig.md

@@ -0,0 +1,60 @@
+# voice.updateConfig()
+
+The `updateConfig()` method allows you to update the configuration of a voice provider at runtime. This is useful for changing voice settings, API keys, or other provider-specific options without creating a new instance.
+
+## Usage Example
+
+```typescript
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+
+// Initialize a real-time voice provider
+const voice = new OpenAIRealtimeVoice({
+  realtimeConfig: {
+    model: 'gpt-5.1-realtime',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+  speaker: 'alloy',
+})
+
+// Connect to the real-time service
+await voice.connect()
+
+// Later, update the configuration
+voice.updateConfig({
+  voice: 'nova', // Change the default voice
+  turn_detection: {
+    type: 'server_vad',
+    threshold: 0.5,
+    silence_duration_ms: 1000,
+  },
+})
+
+// The next speak() call will use the new configuration
+await voice.speak('Hello with my new voice!')
+```
+
+## Parameters
+
+**options:** (`Record<string, unknown>`): Configuration options to update. The specific properties depend on the voice provider.
+
+## Return Value
+
+This method does not return a value.
+
+## Configuration Options
+
+Different voice providers support different configuration options:
+
+### OpenAI Realtime
+
+**voice?:** (`string`): Voice ID to use for speech synthesis (e.g., 'alloy', 'echo', 'nova')
+
+**turn\_detection?:** (`{ type: string, threshold?: number, silence_duration_ms?: number }`): Configuration for detecting when a user has finished speaking
+
+## Notes
+
+- The default implementation logs a warning if the provider doesn't support this method
+- Configuration updates are typically applied to subsequent operations, not ongoing ones
+- Not all properties that can be set in the constructor can be updated at runtime
+- The specific behavior depends on the voice provider implementation
+- For real-time voice providers, some configuration changes may require reconnecting to the service

package/.docs/reference/workflows/run-methods/cancel.md

@@ -0,0 +1,86 @@
+# Run.cancel()
+
+The `.cancel()` method cancels a workflow run, stopping execution and cleaning up resources.
+
+This method aborts any running steps and updates the workflow status to 'canceled'. It works for both actively running workflows and suspended/waiting workflows.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+await run.cancel()
+// Returns: { message: 'Workflow run canceled' }
+```
+
+## Parameters
+
+**No parameters:** (`void`): This method takes no parameters
+
+## Returns
+
+**result:** (`Promise<{ message: string }>`): A promise that resolves with { message: 'Workflow run canceled' } when cancellation succeeds
+
+## How cancellation works
+
+When called, the workflow will:
+
+1. **Trigger the abort signal** - Uses the standard Web API AbortSignal to notify running steps
+2. **Prevent subsequent steps** - No further steps will be executed
+
+## Abort signal behavior
+
+Steps that check the `abortSignal` parameter can respond to cancellation:
+
+- Steps can listen to the 'abort' event: `abortSignal.addEventListener('abort', callback)`
+- Steps can check if already aborted: `if (abortSignal.aborted) { ... }`
+- Useful for cancelling timeouts, network requests, or long-running operations
+
+**Note:** Steps must actively check the abort signal to be canceled mid-execution. Steps that don't check the signal will run to completion, but subsequent steps won't execute.
+
+## Extended usage examples
+
+### Cancelling a workflow on error
+
+```typescript
+const run = await workflow.createRun()
+
+try {
+  const result = await run.start({ inputData: { value: 'initial data' } })
+} catch (error) {
+  await run.cancel()
+}
+```
+
+### Creating a step that responds to cancellation
+
+```typescript
+const step = createStep({
+  id: 'long-running-step',
+  execute: async ({ inputData, abortSignal, abort }) => {
+    const timeout = new Promise(resolve => {
+      const timer = setTimeout(() => resolve('done'), 10000)
+
+      // Clean up if canceled
+      abortSignal.addEventListener('abort', () => {
+        clearTimeout(timer)
+        resolve('canceled')
+      })
+    })
+
+    const result = await timeout
+
+    // Check if aborted after async operation
+    if (abortSignal.aborted) {
+      return abort() // Stop execution
+    }
+
+    return { result }
+  },
+})
+```
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)

package/.docs/reference/workflows/run-methods/restart.md

@@ -0,0 +1,33 @@
+# Run.restart()
+
+The `.restart()` method restarts an active workflow run that lost connection to the server, allowing you to continue execution from the moment it lost connection (the last active step).
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const result = await run.start({ inputData: { value: 'initial data' } })
+
+const restartedResult = await run.restart()
+```
+
+## Parameters
+
+**requestContext?:** (`RequestContext`): Request Context data to use when resuming
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+## Returns
+
+**result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the workflow execution result containing step outputs and status
+
+**traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Restart workflows](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)

package/.docs/reference/workflows/run-methods/resume.md

@@ -0,0 +1,59 @@
+# Run.resume()
+
+The `.resume()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const result = await run.start({ inputData: { value: 'initial data' } })
+
+if (result.status === 'suspended') {
+  const resumedResults = await run.resume({
+    resumeData: { value: 'resume data' },
+  })
+}
+```
+
+## Parameters
+
+**resumeData?:** (`z.infer<TResumeSchema>`): Data for resuming the suspended step
+
+**step?:** (`Step<string, any, any, TResumeSchema, any, TEngineType> | [...Step<string, any, any, any, any, TEngineType>[], Step<string, any, any, TResumeSchema, any, TEngineType>] | string | string[]`): The step(s) to resume execution from. Can be a Step instance, array of Steps, step ID string, or array of step ID strings
+
+**requestContext?:** (`RequestContext`): Request Context data to use when resuming
+
+**retryCount?:** (`number`): Optional retry count for nested workflow execution
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**outputOptions?:** (`OutputOptions`): includeState?:booleanWhether to include the workflow run state in the result.
+
+## Returns
+
+**result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the workflow execution result containing step outputs and status
+
+**traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
+
+## Extended usage example
+
+```typescript
+if (result.status === 'suspended') {
+  const resumedResults = await run.resume({
+    step: result.suspended[0],
+    resumeData: { value: 'resume data' },
+  })
+}
+```
+
+> **Note:** When exactly one step is suspended, you can omit the `step` parameter and the workflow will automatically resume that step. For workflows with multiple suspended steps, you must explicitly specify which step to resume.
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
+- [Suspend and resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Human in the loop](https://mastra.ai/docs/workflows/human-in-the-loop)

package/.docs/reference/workflows/run-methods/start.md

@@ -0,0 +1,58 @@
+# Run.start()
+
+The `.start()` method starts a workflow run with input data, allowing you to execute the workflow from the beginning.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const result = await run.start({
+  inputData: {
+    value: 'initial data',
+  },
+})
+```
+
+## Parameters
+
+**inputData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+
+**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+
+**outputWriter?:** (`(chunk: TOutput) => Promise<void>`): Optional asynchronous function to handle output chunks as they are produced
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**outputOptions?:** (`OutputOptions`): includeState?:booleanWhether to include the workflow run state in the result.
+
+## Returns
+
+**result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the workflow execution result containing step outputs and status
+
+**traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
+
+## Extended usage example
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const run = await workflow.createRun()
+
+const requestContext = new RequestContext()
+requestContext.set('variable', false)
+
+const result = await run.start({
+  inputData: {
+    value: 'initial data',
+  },
+  requestContext,
+})
+```
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)