@mastra/mcp-docs-server 0.0.3 → 0.0.4-alpha.1

package/.docs/raw/voice/speech-to-text.mdx

@@ -0,0 +1,45 @@
+---
+title: Speech-to-Text (STT) in Mastra | Mastra Docs
+description: Overview of Speech-to-Text capabilities in Mastra, including configuration, usage, and integration with voice providers.
+---
+
+# Speech-to-Text (STT)
+
+Speech-to-Text (STT) in Mastra provides a standardized interface for converting audio input into text across multiple service providers. This section covers STT configuration and usage. Check out the [Adding Voice to Agents](../agents/03-adding-voice.mdx) documentation to learn how to use STT in an agent.
+
+## Speech Configuration
+
+To use STT in Mastra, you need to provide a `listeningModel` configuration when initializing the voice provider. This configuration includes parameters such as:
+
+- **`name`**: The specific STT model to use.
+- **`apiKey`**: Your API key for authentication.
+- **Provider-specific options**: Additional options that may be required or supported by the specific voice provider.
+
+**Note**: All of these parameters are optional. You can use the default settings provided by the voice provider, which will depend on the specific provider you are using.
+
+### Example Configuration
+
+```typescript
+const voice = new OpenAIVoice({
+  listeningModel: {
+    name: "whisper-1",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+});
+
+// If using default settings the configuration can be simplified to:
+const voice = new OpenAIVoice();
+```
+
+## Using the Listen Method
+
+The primary method for STT is the `listen()` method, which converts spoken audio into text. Here's how to use it:
+
+```typescript
+const audioStream = getMicrophoneStream(); // Assume this function gets audio input
+const transcript = await voice.listen(audioStream, {
+  filetype: "m4a", // Optional: specify the audio file type
+});
+```
+
+**Note**: If you are using a voice-to-voice provider, such as `OpenAIRealtimeVoice`, the `listen()` method will emit a "writing" event instead of returning a transcript directly.

package/.docs/raw/voice/text-to-speech.mdx

@@ -0,0 +1,52 @@
+---
+title: Text-to-Speech (TTS) in Mastra | Mastra Docs
+description: Overview of Text-to-Speech capabilities in Mastra, including configuration, usage, and integration with voice providers.
+---
+
+# Text-to-Speech (TTS)
+
+Text-to-Speech (TTS) in Mastra offers a unified API for synthesizing spoken audio from text using various provider services. This section explains TTS configuration options and implementation methods. For integrating TTS capabilities with agents, refer to the [Adding Voice to Agents](../agents/03-adding-voice.mdx) documentation.
+
+## Speech Configuration
+
+To use TTS in Mastra, you need to provide a `speechModel` configuration when initializing the voice provider. This configuration includes parameters such as:
+
+- **`name`**: The specific TTS model to use.
+- **`apiKey`**: Your API key for authentication.
+- **Provider-specific options**: Additional options that may be required or supported by the specific voice provider.
+
+The **`speaker`** option is specified separately and allows you to select different voices for speech synthesis.
+
+**Note**: All of these parameters are optional. You can use the default settings provided by the voice provider, which will depend on the specific provider you are using.
+
+### Example Configuration
+
+```typescript
+const voice = new OpenAIVoice({
+  speechModel: {
+    name: "tts-1-hd",
+    apiKey: process.env.OPENAI_API_KEY
+  },
+  speaker: "alloy",
+});
+
+// If using default settings the configuration can be simplified to:
+const voice = new OpenAIVoice();
+```
+
+## Using the Speak Method
+
+The primary method for TTS is the `speak()` method, which converts text to speech. This method can accept options that allows you to specify the speaker and other provider-specific options. Here's how to use it:
+
+```typescript
+const readableStream = await voice.speak("Hello, world!", {
+  speaker: "default", // Optional: specify a speaker
+  properties: {
+    speed: 1.0, // Optional: adjust speech speed
+    pitch: "default", // Optional: specify pitch if supported
+  },
+});
+```
+
+**Note**: If you are using a voice-to-voice provider, such as `OpenAIRealtimeVoice`, the `speak()` method will emit a "speaking" event instead of returning an Readable Stream.
+

package/.docs/raw/voice/voice-to-voice.mdx

@@ -0,0 +1,310 @@
+---
+title: Voice-to-Voice Capabilities in Mastra | Mastra Docs
+description: Overview of voice-to-voice capabilities in Mastra, including real-time interactions and event-driven architecture.
+---
+
+# Voice-to-Voice Capabilities in Mastra
+
+## Introduction
+
+Voice-to-Voice in Mastra provides a standardized interface for real-time speech-to-speech interactions across multiple service providers. This section covers configuration, event-driven architecture, and implementation methods for creating conversational voice experiences. For integrating Voice-to-Voice capabilities with agents, refer to the [Adding Voice to Agents](../agents/03-adding-voice.mdx) documentation.
+
+## Real-time Voice Interactions
+
+Mastra's real-time voice system enables continuous bidirectional audio communication through an event-driven architecture. Unlike separate TTS and STT operations, real-time voice maintains an open connection that processes speech continuously in both directions.
+
+### Example Implementation
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+
+const agent = new Agent({
+  name: 'Agent',
+  instructions: `You are a helpful assistant with real-time voice capabilities.`,
+  model: openai('gpt-4o'),
+  voice: new OpenAIRealtimeVoice(),
+});
+
+// Connect to the voice service
+await agent.voice.connect();
+
+// Listen for agent audio responses
+agent.voice.on('speaking', ({ audio }) => {
+  playAudio(audio);
+});
+
+// Initiate the conversation
+await agent.voice.speak('How can I help you today?');
+
+// Send continuous audio from the microphone
+const micStream = getMicrophoneStream();
+await agent.voice.send(micStream);
+```
+
+## Event-Driven Architecture
+
+Mastra's voice-to-voice implementation is built on an event-driven architecture. Developers register event listeners to handle incoming audio progressively, allowing for more responsive interactions than waiting for complete audio responses.
+
+
+## Configuration
+
+When initializing a voice-to-voice provider, you can provide configuration options to customize its behavior:
+
+### Constructor Options
+
+- **`chatModel`**: Configuration for the OpenAI realtime model.
+  - **`apiKey`**: Your OpenAI API key. Falls back to the `OPENAI_API_KEY` environment variable.
+  - **`model`**: The model ID to use for real-time voice interactions (e.g., `gpt-4o-mini-realtime`).
+  - **`options`**: Additional options for the realtime client, such as session configuration.
+
+- **`speaker`**: The default voice ID for speech synthesis. This allows you to specify which voice to use for the speech output.
+
+### Example Configuration
+
+```typescript
+const voice = new OpenAIRealtimeVoice({
+  chatModel: {
+    apiKey: 'your-openai-api-key',
+    model: 'gpt-4o-mini-realtime',
+    options: {
+      sessionConfig: {
+        turn_detection: {
+          type: 'server_vad',
+          threshold: 0.6,
+          silence_duration_ms: 1200,
+        },
+      },
+    },
+  },
+  speaker: 'alloy', // Default voice
+});
+
+// If using default settings the configuration can be simplified to:
+const voice = new OpenAIRealtimeVoice();
+```
+
+## Core Methods
+
+The `OpenAIRealtimeVoice` class provides the following core methods for voice interactions:
+
+### connect()
+
+Establishes a connection to the OpenAI realtime service.
+
+**Usage:**
+```typescript
+await voice.connect();
+```
+
+**Notes:**
+- Must be called before using any other interaction methods
+- Returns a Promise that resolves when the connection is established
+
+### speak(text, options?)
+
+Emits a speaking event using the configured voice model.
+
+**Parameters:**
+- `text`: String content to be spoken
+- `options`: Optional configuration object
+  - `speaker`: Voice ID to use (overrides default)
+  - `properties`: Additional provider-specific properties
+
+**Usage:**
+```typescript
+voice.speak('Hello, how can I help you today?', {
+  speaker: 'alloy'
+});
+```
+
+**Notes:**
+- Emits 'speaking' events rather than returning an audio stream
+
+### listen(audioInput, options?)
+
+Processes audio input for speech recognition.
+
+**Parameters:**
+- `audioInput`: Readable stream of audio data
+- `options`: Optional configuration object
+  - `filetype`: Audio format (default: 'mp3')
+  - Additional provider-specific options
+
+**Usage:**
+```typescript
+const audioData = getMicrophoneStream();
+voice.listen(audioData, {
+  filetype: 'wav'
+});
+```
+
+**Notes:**
+- Emits 'writing' events with transcribed text
+
+### send(audioStream)
+
+Streams audio data in real-time for continuous processing.
+
+**Parameters:**
+- `audioStream`: Readable stream of audio data
+
+**Usage:**
+```typescript
+const micStream = getMicrophoneStream();
+await voice.send(micStream);
+```
+
+**Notes:**
+- Used for continuous audio streaming scenarios like live microphone input
+- Returns a Promise that resolves when the stream is accepted
+
+### answer(params)
+
+Sends a response to the OpenAI Realtime API.
+
+**Parameters:**
+- `params`: The parameters object
+  - `options`: Configuration options for the response
+    - `content`: Text content of the response
+    - `voice`: Voice ID to use for the response
+
+**Usage:**
+```typescript
+await voice.answer({
+  options: {
+    content: "Hello, how can I help you today?",
+    voice: "alloy"
+  }
+});
+```
+
+**Notes:**
+- Triggers a response to the real-time session
+- Returns a Promise that resolves when the response has been sent
+
+## Utility Methods
+
+### updateConfig(config)
+
+Updates the session configuration for the voice instance.
+
+**Parameters:**
+- `config`: New session configuration object
+
+**Usage:**
+```typescript
+voice.updateConfig({
+  turn_detection: {
+    type: 'server_vad',
+    threshold: 0.6,
+    silence_duration_ms: 1200,
+  }
+});
+```
+
+### addTools(tools)
+
+Adds a set of tools to the voice instance.
+
+**Parameters:**
+- `tools`: Array of tool objects that the model can call
+
+**Usage:**
+```typescript
+voice.addTools([
+  createTool({
+    id: "Get Weather Information",
+    inputSchema: z.object({
+        city: z.string(),
+    }),
+    description: `Fetches the current weather information for a given city`,
+    execute: async ({ city }) => {...},
+  })
+]);
+```
+
+### close()
+
+Disconnects from the OpenAI realtime session and cleans up resources.
+
+**Usage:**
+```typescript
+voice.close();
+```
+
+**Notes:**
+- Should be called when you're done with the voice instance to free resources
+
+### on(event, callback)
+
+Registers an event listener for voice events.
+
+**Parameters:**
+- `event`: Event name ('speaking', 'writing', or 'error')
+- `callback`: Function to call when the event occurs
+
+**Usage:**
+```typescript
+voice.on('speaking', ({ audio }) => {
+  playAudio(audio);
+});
+```
+
+### off(event, callback)
+
+Removes a previously registered event listener.
+
+**Parameters:**
+- `event`: Event name
+- `callback`: The callback function to remove
+
+**Usage:**
+```typescript
+voice.off('speaking', callbackFunction);
+```
+
+## Events
+
+The `OpenAIRealtimeVoice` class emits the following events:
+
+### speaking
+
+Emitted when audio data is received from the model.
+
+**Event payload:**
+- `audio`: A chunk of audio data as a readable stream
+
+```typescript
+agent.voice.on('speaking', ({ audio }) => {
+  playAudio(audio); // Handle audio chunks as they're generated
+});
+```
+
+### writing
+
+Emitted when transcribed text is available.
+
+**Event payload:**
+- `text`: The transcribed text
+- `role`: The role of the speaker (user or assistant)
+- `done`: Boolean indicating if this is the final transcription
+
+```typescript
+agent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`); // Log who said what
+});
+```
+
+### error
+
+Emitted when an error occurs.
+
+**Event payload:**
+- Error object with details about what went wrong
+
+```typescript
+agent.voice.on('error', (error) => {
+  console.error('Voice error:', error);
+});
+```

package/.docs/raw/workflows/dynamic-workflows.mdx

@@ -99,6 +99,10 @@ const mainWorkflow = new Workflow({
 
 mainWorkflow.step(createDynamicWorkflow).commit();
 
+// Register the workflow with Mastra
+export const mastra = new Mastra({
+  workflows: { mainWorkflow },
+});
 
 const run = mainWorkflow.createRun();
 const result = await run.start({

package/.docs/raw/workflows/error-handling.mdx

@@ -0,0 +1,183 @@
+---
+title: "Error Handling in Workflows | Mastra Docs"
+description: "Learn how to handle errors in Mastra workflows using step retries, conditional branching, and monitoring."
+---
+
+# Error Handling in Workflows
+
+Robust error handling is essential for production workflows. Mastra provides several mechanisms to handle errors gracefully, allowing your workflows to recover from failures or gracefully degrade when necessary.
+
+## Overview
+
+Error handling in Mastra workflows can be implemented using:
+
+1. **Step Retries** - Automatically retry failed steps
+2. **Conditional Branching** - Create alternative paths based on step success or failure
+3. **Error Monitoring** - Watch workflows for errors and handle them programmatically
+4. **Result Status Checks** - Check the status of previous steps in subsequent steps
+
+## Step Retries
+
+Mastra provides a built-in retry mechanism for steps that fail due to transient errors. This is particularly useful for steps that interact with external services or resources that might experience temporary unavailability.
+
+### Basic Retry Configuration
+
+You can configure retries at the workflow level or for individual steps:
+
+```typescript
+// Workflow-level retry configuration
+const workflow = new Workflow({
+  name: 'my-workflow',
+  retryConfig: {
+    attempts: 3,    // Number of retry attempts
+    delay: 1000,    // Delay between retries in milliseconds
+  },
+});
+
+// Step-level retry configuration (overrides workflow-level)
+const apiStep = new Step({
+  id: 'callApi',
+  execute: async () => {
+    // API call that might fail
+  },
+  retryConfig: {
+    attempts: 5,    // This step will retry up to 5 times
+    delay: 2000,    // With a 2-second delay between retries
+  },
+});
+```
+
+For more details about step retries, see the [Step Retries](../reference/workflows/step-retries.mdx) reference.
+
+## Conditional Branching
+
+You can create alternative workflow paths based on the success or failure of previous steps using conditional logic:
+
+```typescript
+// Create a workflow with conditional branching
+const workflow = new Workflow({
+  name: 'error-handling-workflow',
+});
+
+workflow
+  .step(fetchDataStep)
+  .then(processDataStep, {
+    // Only execute processDataStep if fetchDataStep was successful
+    when: ({ context }) => {
+      return context.steps.fetchDataStep?.status === 'success';
+    },
+  })
+  .then(fallbackStep, {
+    // Execute fallbackStep if fetchDataStep failed
+    when: ({ context }) => {
+      return context.steps.fetchDataStep?.status === 'failed';
+    },
+  })
+  .commit();
+```
+
+## Error Monitoring
+
+You can monitor workflows for errors using the `watch` method:
+
+```typescript
+const { start, watch } = workflow.createRun();
+
+watch(async ({ context, activePaths }) => {
+  // Check for any failed steps
+  const failedSteps = Object.entries(context.steps)
+    .filter(([_, step]) => step.status === 'failed')
+    .map(([stepId]) => stepId);
+
+  if (failedSteps.length > 0) {
+    console.error(`Workflow has failed steps: ${failedSteps.join(', ')}`);
+    // Take remedial action, such as alerting or logging
+  }
+});
+
+await start();
+```
+
+## Handling Errors in Steps
+
+Within a step's execution function, you can handle errors programmatically:
+
+```typescript
+const robustStep = new Step({
+  id: 'robustStep',
+  execute: async ({ context }) => {
+    try {
+      // Attempt the primary operation
+      const result = await someRiskyOperation();
+      return { success: true, data: result };
+    } catch (error) {
+      // Log the error
+      console.error('Operation failed:', error);
+
+      // Return a graceful fallback result instead of throwing
+      return {
+        success: false,
+        error: error.message,
+        fallbackData: 'Default value'
+      };
+    }
+  },
+});
+```
+
+## Checking Previous Step Results
+
+You can make decisions based on the results of previous steps:
+
+```typescript
+const finalStep = new Step({
+  id: 'finalStep',
+  execute: async ({ context }) => {
+    // Check results of previous steps
+    const step1Success = context.steps.step1?.status === 'success';
+    const step2Success = context.steps.step2?.status === 'success';
+
+    if (step1Success && step2Success) {
+      // All steps succeeded
+      return { status: 'complete', result: 'All operations succeeded' };
+    } else if (step1Success) {
+      // Only step1 succeeded
+      return { status: 'partial', result: 'Partial completion' };
+    } else {
+      // Critical failure
+      return { status: 'failed', result: 'Critical steps failed' };
+    }
+  },
+});
+```
+
+## Best Practices for Error Handling
+
+1. **Use retries for transient failures**: Configure retry policies for steps that might experience temporary issues.
+
+2. **Provide fallback paths**: Design workflows with alternative paths for when critical steps fail.
+
+3. **Be specific about error scenarios**: Use different handling strategies for different types of errors.
+
+4. **Log errors comprehensively**: Include context information when logging errors to aid in debugging.
+
+5. **Return meaningful data on failure**: When a step fails, return structured data about the failure to help downstream steps make decisions.
+
+6. **Consider idempotency**: Ensure steps can be safely retried without causing duplicate side effects.
+
+7. **Monitor workflow execution**: Use the `watch` method to actively monitor workflow execution and detect errors early.
+
+## Advanced Error Handling
+
+For more complex error handling scenarios, consider:
+
+- **Implementing circuit breakers**: If a step fails repeatedly, stop retrying and use a fallback strategy
+- **Adding timeout handling**: Set time limits for steps to prevent workflows from hanging indefinitely
+- **Creating dedicated error recovery workflows**: For critical workflows, create separate recovery workflows that can be triggered when the main workflow fails
+
+## Related
+
+- [Step Retries Reference](../reference/workflows/step-retries.mdx)
+- [Watch Method Reference](../reference/workflows/watch.mdx)
+- [Step Conditions](../reference/workflows/step-condition.mdx)
+- [Control Flow](./control-flow.mdx)

package/.docs/raw/workflows/steps.mdx

@@ -14,7 +14,7 @@ The code below shows how to define these steps inline or separately.
 You can create steps directly within your workflow using `.step()` and `.then()`. This code shows how to define, link, and execute two steps in sequence.
 
 ```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
-import { Step, Workflow } from "@mastra/core/workflows";
+import { Step, Workflow, Mastra } from "@mastra/core";
 import { z } from "zod";
 
 export const myWorkflow = new Workflow({
@@ -51,6 +51,11 @@ myWorkflow
       },
     }),
   ).commit();
+
+  // Register the workflow with Mastra
+  export const mastra = new Mastra({
+    workflows: { myWorkflow },
+  });
 ```
 
 ## Creating Steps Separately
@@ -58,7 +63,7 @@ myWorkflow
 If you prefer to manage your step logic in separate entities, you can define steps outside and then add them to your workflow. This code shows how to define steps independently and link them afterward.
 
 ```typescript showLineNumbers filename="src/mastra/workflows/index.ts" copy
-import { Step, Workflow } from "@mastra/core/workflows";
+import { Step, Workflow, Mastra } from "@mastra/core";
 import { z } from "zod";
 
 // Define steps separately
@@ -95,4 +100,9 @@ const myWorkflow = new Workflow({
 
 myWorkflow.step(stepOne).then(stepTwo);
 myWorkflow.commit();
+
+// Register the workflow with Mastra
+export const mastra = new Mastra({
+  workflows: { myWorkflow },
+});
 ```