@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.10

package/.docs/raw/reference/voice/composite-voice.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: CompositeVoice | Voice | Mastra Docs"
+title: "Reference: CompositeVoice | Voice"
 description: "Documentation for the CompositeVoice class, which enables combining multiple voice providers for flexible text-to-speech and speech-to-text operations."
 ---
 
@@ -7,31 +7,7 @@ description: "Documentation for the CompositeVoice class, which enables combinin
 
 The CompositeVoice class allows you to combine different voice providers for text-to-speech and speech-to-text operations. This is particularly useful when you want to use the best provider for each operation - for example, using OpenAI for speech-to-text and PlayAI for text-to-speech.
 
-CompositeVoice is used internally by the Agent class to provide flexible voice capabilities.
-
-## Usage Example
-
-```typescript
-import { CompositeVoice } from "@mastra/core/voice";
-import { OpenAIVoice } from "@mastra/voice-openai";
-import { PlayAIVoice } from "@mastra/voice-playai";
-
-// Create voice providers
-const openai = new OpenAIVoice();
-const playai = new PlayAIVoice();
-
-// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
-const voice = new CompositeVoice({
-  input: openai,
-  output: playai,
-});
-
-// Convert speech to text using OpenAI
-const text = await voice.listen(audioStream);
-
-// Convert text to speech using PlayAI
-const audio = await voice.speak("Hello, world!");
-```
+CompositeVoice supports both Mastra voice providers and AI SDK model providers
 
 ## Constructor Parameters
 
@@ -45,14 +21,20 @@ const audio = await voice.speak("Hello, world!");
     },
     {
       name: "config.input",
-      type: "MastraVoice",
-      description: "Voice provider to use for speech-to-text operations",
+      type: "MastraVoice | TranscriptionModel",
+      description: "Voice provider or AI SDK transcription model to use for speech-to-text operations. AI SDK models are automatically wrapped.",
       isOptional: true,
     },
     {
       name: "config.output",
+      type: "MastraVoice | SpeechModel",
+      description: "Voice provider or AI SDK speech model to use for text-to-speech operations. AI SDK models are automatically wrapped.",
+      isOptional: true,
+    },
+    {
+      name: "config.realtime",
       type: "MastraVoice",
-      description: "Voice provider to use for text-to-speech operations",
+      description: "Voice provider to use for real-time speech-to-speech operations",
       isOptional: true,
     },
   ]}
@@ -142,3 +124,64 @@ Notes:
 - If no speaking provider is configured, returns an empty array
 - Each voice object will have at least a voiceId property
 - Additional voice properties depend on the speaking provider
+
+## Usage Examples
+
+### Using Mastra Voice Providers
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+
+// Create voice providers
+const openai = new OpenAIVoice();
+const playai = new PlayAIVoice();
+
+// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
+const voice = new CompositeVoice({
+  input: openai,
+  output: playai,
+});
+
+// Convert speech to text using OpenAI
+const text = await voice.listen(audioStream);
+
+// Convert text to speech using PlayAI
+const audio = await voice.speak("Hello, world!");
+```
+
+### Using AI SDK Model Providers
+
+You can pass AI SDK transcription and speech models directly to CompositeVoice:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { openai } from "@ai-sdk/openai";
+import { elevenlabs } from "@ai-sdk/elevenlabs";
+
+// Use AI SDK models directly - they will be auto-wrapped
+const voice = new CompositeVoice({
+  input: openai.transcription('whisper-1'),      // AI SDK transcription
+  output: elevenlabs.speech('eleven_turbo_v2'),  // AI SDK speech
+});
+
+// Works the same way as with Mastra providers
+const text = await voice.listen(audioStream);
+const audio = await voice.speak("Hello from AI SDK!");
+```
+
+### Mix and Match
+
+You can combine Mastra providers with AI SDK models:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { PlayAIVoice } from "@mastra/voice-playai";
+import { groq } from "@ai-sdk/groq";
+
+const voice = new CompositeVoice({
+  input: groq.transcription('whisper-large-v3'),  // AI SDK for STT
+  output: new PlayAIVoice(),                       // Mastra for TTS
+});
+```

package/.docs/raw/reference/voice/deepgram.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Deepgram | Voice | Mastra Docs"
+title: "Reference: Deepgram | Voice"
 description: "Documentation for the Deepgram voice implementation, providing text-to-speech and speech-to-text capabilities with multiple voice models and languages."
 ---
 

package/.docs/raw/reference/voice/elevenlabs.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: ElevenLabs | Voice | Mastra Docs"
+title: "Reference: ElevenLabs | Voice"
 description: "Documentation for the ElevenLabs voice implementation, offering high-quality text-to-speech capabilities with multiple voice models and natural-sounding synthesis."
 ---
 

package/.docs/raw/reference/voice/google-gemini-live.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Google Gemini Live Voice | Voice | Mastra Docs"
+title: "Reference: Google Gemini Live Voice | Voice"
 description: "Documentation for the GeminiLiveVoice class, providing real-time multimodal voice interactions using Google's Gemini Live API with support for both Gemini API and Vertex AI."
 ---
 

package/.docs/raw/reference/voice/google.mdx

@@ -1,11 +1,11 @@
 ---
-title: "Reference: Google | Voice | Mastra Docs"
-description: "Documentation for the Google Voice implementation, providing text-to-speech and speech-to-text capabilities."
+title: "Reference: Google | Voice"
+description: "Documentation for the Google Voice implementation, providing text-to-speech and speech-to-text capabilities with support for both API key and Vertex AI authentication."
 ---
 
 # Google
 
-The Google Voice implementation in Mastra provides both text-to-speech (TTS) and speech-to-text (STT) capabilities using Google Cloud services. It supports multiple voices, languages, and advanced audio configuration options.
+The Google Voice implementation in Mastra provides both text-to-speech (TTS) and speech-to-text (STT) capabilities using Google Cloud services. It supports multiple voices, languages, advanced audio configuration options, and both standard API key authentication and Vertex AI mode for enterprise deployments.
 
 ## Usage Example
 
@@ -15,17 +15,6 @@ import { GoogleVoice } from "@mastra/voice-google";
 // Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
 const voice = new GoogleVoice();
 
-// Initialize with custom configuration
-const voice = new GoogleVoice({
-  speechModel: {
-    apiKey: "your-speech-api-key",
-  },
-  listeningModel: {
-    apiKey: "your-listening-api-key",
-  },
-  speaker: "en-US-Casual-K",
-});
-
 // Text-to-Speech
 const audioStream = await voice.speak("Hello, world!", {
   languageCode: "en-US",
@@ -71,6 +60,29 @@ const voices = await voice.getSpeakers({ languageCode: "en-US" });
       isOptional: true,
       defaultValue: "'en-US-Casual-K'",
     },
+    {
+      name: "vertexAI",
+      type: "boolean",
+      description:
+        "Enable Vertex AI mode for enterprise deployments. Uses project-based authentication instead of API keys. Requires 'project' to be set.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "project",
+      type: "string",
+      description:
+        "Google Cloud project ID (required when vertexAI is true). Falls back to GOOGLE_CLOUD_PROJECT environment variable.",
+      isOptional: true,
+    },
+    {
+      name: "location",
+      type: "string",
+      description:
+        "Google Cloud region for Vertex AI. Falls back to GOOGLE_CLOUD_LOCATION environment variable.",
+      isOptional: true,
+      defaultValue: "'us-central1'",
+    },
   ]}
 />
 
@@ -82,7 +94,21 @@ const voices = await voice.getSpeakers({ languageCode: "en-US" });
       name: "apiKey",
       type: "string",
       description:
-        "Google Cloud API key. Falls back to GOOGLE_API_KEY environment variable",
+        "Google Cloud API key. Falls back to GOOGLE_API_KEY environment variable. Not used when vertexAI is true.",
+      isOptional: true,
+    },
+    {
+      name: "keyFilename",
+      type: "string",
+      description:
+        "Path to service account JSON key file. Falls back to GOOGLE_APPLICATION_CREDENTIALS environment variable.",
+      isOptional: true,
+    },
+    {
+      name: "credentials",
+      type: "object",
+      description:
+        "In-memory service account credentials object with client_email and private_key properties.",
       isOptional: true,
     },
   ]}
@@ -193,11 +219,124 @@ Returns an array of available voice options, where each node contains:
   ]}
 />
 
+### isUsingVertexAI()
+
+Checks if Vertex AI mode is enabled.
+
+Returns: `boolean` - `true` if using Vertex AI, `false` otherwise
+
+### getProject()
+
+Gets the configured Google Cloud project ID.
+
+Returns: `string | undefined` - The project ID or `undefined` if not set
+
+### getLocation()
+
+Gets the configured Google Cloud location/region.
+
+Returns: `string` - The location (default: `'us-central1'`)
+
+## Authentication
+
+The Google Voice provider supports two authentication methods:
+
+### Standard Mode (API Key)
+
+Uses a Google Cloud API key for authentication. Suitable for development and simple use cases.
+
+```typescript
+// Using environment variable (GOOGLE_API_KEY)
+const voice = new GoogleVoice();
+
+// Using explicit API key
+const voice = new GoogleVoice({
+  speechModel: { apiKey: "your-api-key" },
+  listeningModel: { apiKey: "your-api-key" },
+  speaker: "en-US-Casual-K",
+});
+```
+
+### Vertex AI Mode (Service Account)
+
+Uses Google Cloud project-based authentication with service accounts. Recommended for production and enterprise deployments.
+
+**Benefits:**
+- Better security (no API keys in code)
+- IAM-based access control
+- Project-level billing and quotas
+- Audit logging
+- Enterprise features
+
+**Configuration Options:**
+
+```typescript
+// Using Application Default Credentials (ADC)
+// Set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT env vars
+const voice = new GoogleVoice({
+  vertexAI: true,
+  project: "your-gcp-project",
+  location: "us-central1", // Optional, defaults to 'us-central1'
+});
+
+// Using service account key file
+const voice = new GoogleVoice({
+  vertexAI: true,
+  project: "your-gcp-project",
+  speechModel: {
+    keyFilename: "/path/to/service-account.json",
+  },
+  listeningModel: {
+    keyFilename: "/path/to/service-account.json",
+  },
+});
+
+// Using in-memory credentials
+const voice = new GoogleVoice({
+  vertexAI: true,
+  project: "your-gcp-project",
+  speechModel: {
+    credentials: {
+      client_email: "service-account@project.iam.gserviceaccount.com",
+      private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
+    },
+  },
+});
+```
+
+**Required Permissions:**
+
+**IAM Roles:**
+
+For Text-to-Speech:
+- `roles/texttospeech.admin` - Text-to-Speech Admin (full access)
+- `roles/texttospeech.editor` - Text-to-Speech Editor (create and manage)
+- `roles/texttospeech.viewer` - Text-to-Speech Viewer (read-only)
+
+For Speech-to-Text:
+- `roles/speech.client` - Speech-to-Text Client
+
+**OAuth Scopes:**
+
+For synchronous Text-to-Speech synthesis:
+- `https://www.googleapis.com/auth/cloud-platform` - Full access to Google Cloud Platform services
+
+For long-audio Text-to-Speech operations:
+- `locations.longAudioSynthesize` - Create long-audio synthesis operations
+- `operations.get` - Get operation status
+- `operations.list` - List operations
+
 ## Important Notes
 
-1. A Google Cloud API key is required. Set it via the `GOOGLE_API_KEY` environment variable or pass it in the constructor.
-2. The default voice is set to 'en-US-Casual-K'.
-3. Both text-to-speech and speech-to-text services use LINEAR16 as the default audio encoding.
-4. The `speak()` method supports advanced audio configuration through the Google Cloud Text-to-Speech API.
-5. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
-6. Available voices can be filtered by language code using the `getSpeakers()` method.
+1. **Authentication**: Either a Google Cloud API key (standard mode) or service account credentials (Vertex AI mode) is required.
+2. **Environment Variables**:
+   - `GOOGLE_API_KEY` - API key for standard mode
+   - `GOOGLE_CLOUD_PROJECT` - Project ID for Vertex AI mode
+   - `GOOGLE_CLOUD_LOCATION` - Location for Vertex AI mode (defaults to 'us-central1')
+   - `GOOGLE_APPLICATION_CREDENTIALS` - Path to service account key file
+3. The default voice is set to `'en-US-Casual-K'`.
+4. Both text-to-speech and speech-to-text services use LINEAR16 as the default audio encoding.
+5. The `speak()` method supports advanced audio configuration through the Google Cloud Text-to-Speech API.
+6. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
+7. Available voices can be filtered by language code using the `getSpeakers()` method.
+8. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.

package/.docs/raw/reference/voice/mastra-voice.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraVoice | Voice | Mastra Docs"
+title: "Reference: MastraVoice | Voice"
 description: "Documentation for the MastraVoice abstract base class, which defines the core interface for all voice services in Mastra, including speech-to-speech capabilities."
 ---
 

package/.docs/raw/reference/voice/murf.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Murf | Voice | Mastra Docs"
+title: "Reference: Murf | Voice"
 description: "Documentation for the Murf voice implementation, providing text-to-speech capabilities."
 ---
 

package/.docs/raw/reference/voice/openai-realtime.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: OpenAI Realtime Voice | Voice | Mastra Docs"
+title: "Reference: OpenAI Realtime Voice | Voice"
 description: "Documentation for the OpenAIRealtimeVoice class, providing real-time text-to-speech and speech-to-text capabilities via WebSockets."
 ---
 
@@ -19,7 +19,7 @@ const voice = new OpenAIRealtimeVoice();
 // Or initialize with specific configuration
 const voiceWithConfig = new OpenAIRealtimeVoice({
   apiKey: "your-openai-api-key",
-  model: "gpt-4o-mini-realtime-preview-2024-12-17",
+  model: "gpt-5.1-realtime-preview-2024-12-17",
   speaker: "alloy", // Default voice
 });
 
@@ -69,7 +69,7 @@ voice.connect();
       type: "string",
       description: "The model ID to use for real-time voice interactions.",
       isOptional: true,
-      defaultValue: "'gpt-4o-mini-realtime-preview-2024-12-17'",
+      defaultValue: "'gpt-5.1-realtime-preview-2024-12-17'",
     },
     {
       name: "apiKey",

package/.docs/raw/reference/voice/openai.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: OpenAI | Voice | Mastra Docs"
+title: "Reference: OpenAI | Voice"
 description: "Documentation for the OpenAIVoice class, providing text-to-speech and speech-to-text capabilities."
 ---
 

package/.docs/raw/reference/voice/playai.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: PlayAI | Voice | Mastra Docs"
+title: "Reference: PlayAI | Voice"
 description: "Documentation for the PlayAI voice implementation, providing text-to-speech capabilities."
 ---
 

package/.docs/raw/reference/voice/sarvam.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Sarvam | Voice | Mastra Docs"
+title: "Reference: Sarvam | Voice"
 description: "Documentation for the Sarvam class, providing text-to-speech and speech-to-text capabilities."
 ---
 

package/.docs/raw/reference/voice/speechify.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Speechify | Voice | Mastra Docs"
+title: "Reference: Speechify | Voice"
 description: "Documentation for the Speechify voice implementation, providing text-to-speech capabilities."
 ---
 

package/.docs/raw/reference/voice/voice.addInstructions.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: voice.addInstructions() | Voice | Mastra Docs"
+title: "Reference: voice.addInstructions() | Voice"
 description: "Documentation for the addInstructions() method available in voice providers, which adds instructions to guide the voice model's behavior."
 ---
 
@@ -12,12 +12,11 @@ The `addInstructions()` method equips a voice provider with instructions that gu
 ```typescript
 import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
 });
@@ -27,7 +26,7 @@ const agent = new Agent({
   name: "Customer Support Agent",
   instructions:
     "You are a helpful customer support agent for a software company.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   voice,
 });
 

package/.docs/raw/reference/voice/voice.addTools.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: voice.addTools() | Voice | Mastra Docs"
+title: "Reference: voice.addTools() | Voice"
 description: "Documentation for the addTools() method available in voice providers, which equips voice models with function calling capabilities."
 ---
 
@@ -39,7 +39,7 @@ const weatherTool = createTool({
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
 });

package/.docs/raw/reference/voice/voice.answer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: voice.answer() | Voice | Mastra Docs"
+title: "Reference: voice.answer() | Voice"
 description: "Documentation for the answer() method available in real-time voice providers, which triggers the voice provider to generate a response."
 ---
 
@@ -23,7 +23,7 @@ const speaker = new Speaker({
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o",
+    model: "gpt-5.1",
     apiKey: process.env.OPENAI_API_KEY,
   },
   speaker: "alloy", // Default voice

package/.docs/raw/reference/voice/voice.close.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: voice.close() | Voice | Mastra Docs"
+title: "Reference: voice.close() | Voice"
 description: "Documentation for the close() method available in voice providers, which disconnects from real-time voice services."
 ---
 
@@ -16,7 +16,7 @@ import { getMicrophoneStream } from "@mastra/node-audio";
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
 });

package/.docs/raw/reference/voice/voice.connect.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: voice.connect() | Voice | Mastra Docs"
+title: "Reference: voice.connect() | Voice"
 description: "Documentation for the connect() method available in real-time voice providers, which establishes a connection for speech-to-speech communication."
 ---
 
@@ -22,7 +22,7 @@ const speaker = new Speaker({
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
     options: {
       sessionConfig: {

package/.docs/raw/reference/voice/voice.events.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Voice Events | Voice | Mastra Docs"
+title: "Reference: Voice Events | Voice"
 description: "Documentation for events emitted by voice providers, particularly for real-time voice interactions."
 ---
 

package/.docs/raw/reference/voice/voice.getSpeakers.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: voice.getSpeakers() | Voice Providers | Mastra Docs"
+title: "Reference: voice.getSpeakers() | Voice Providers"
 description: "Documentation for the getSpeakers() method available in voice providers, which retrieves available voice options."
 ---