npm - @mastra/mcp-docs-server - Versions diffs - 1.2.15-alpha.7 → 1.2.15 - Mend

@mastra/mcp-docs-server 1.2.15-alpha.7 → 1.2.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (504) hide show

package/.docs/reference/voice/google.md DELETED Viewed

@@ -1,290 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# 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, advanced audio configuration options, and both standard API key authentication and Vertex AI mode for enterprise deployments.
-## Usage example
-```typescript
-import { GoogleVoice } from '@mastra/voice-google'
-// Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
-const voice = new GoogleVoice()
-// Text-to-Speech (plain text)
-const audioStream = await voice.speak('Hello, world!', {
-  languageCode: 'en-US',
-  audioConfig: {
-    audioEncoding: 'LINEAR16',
-  },
-})
-// Text-to-Speech with SSML
-const ssmlStream = await voice.speak('ignored', {
-  input: {
-    ssml: '<speak>Take <say-as interpret-as="unit">5 mg</say-as> daily.</speak>',
-  },
-})
-// Text-to-Speech with Gemini-TTS model
-const geminiStream = await voice.speak('Hello from Gemini TTS!', {
-  voice: { name: 'Kore', modelName: 'gemini-2.5-flash-preview-tts' },
-  input: { prompt: 'Warm, calm tone.' },
-})
-// Speech-to-Text
-const transcript = await voice.listen(audioStream, {
-  config: {
-    encoding: 'LINEAR16',
-    languageCode: 'en-US',
-  },
-})
-// Get available voices for a specific language
-const voices = await voice.getSpeakers({ languageCode: 'en-US' })
-```
-## Constructor parameters
-**speechModel** (`GoogleModelConfig`): Configuration for text-to-speech functionality (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)
-**speechModel.apiKey** (`string`): Google Cloud API key. Falls back to GOOGLE\_API\_KEY environment variable. Not used when vertexAI is true.
-**speechModel.keyFilename** (`string`): Path to service account JSON key file. Falls back to GOOGLE\_APPLICATION\_CREDENTIALS environment variable.
-**speechModel.credentials** (`object`): In-memory service account credentials object with client\_email and private\_key properties.
-**listeningModel** (`GoogleModelConfig`): Configuration for speech-to-text functionality (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)
-**listeningModel.apiKey** (`string`): Google Cloud API key. Falls back to GOOGLE\_API\_KEY environment variable. Not used when vertexAI is true.
-**listeningModel.keyFilename** (`string`): Path to service account JSON key file. Falls back to GOOGLE\_APPLICATION\_CREDENTIALS environment variable.
-**listeningModel.credentials** (`object`): In-memory service account credentials object with client\_email and private\_key properties.
-**speaker** (`string`): Default voice ID to use for text-to-speech (Default: `'en-US-Casual-K'`)
-**vertexAI** (`boolean`): Enable Vertex AI mode for enterprise deployments. Uses project-based authentication instead of API keys. Requires 'project' to be set. (Default: `false`)
-**project** (`string`): Google Cloud project ID (required when vertexAI is true). Falls back to GOOGLE\_CLOUD\_PROJECT environment variable.
-**location** (`string`): Google Cloud region for Vertex AI. Falls back to GOOGLE\_CLOUD\_LOCATION environment variable. (Default: `'us-central1'`)
-## Methods
-### `speak()`
-Converts text to speech using Google Cloud Text-to-Speech service.
-**input** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
-**options** (`object`): Speech synthesis options
-**options.speaker** (`string`): Voice ID to use for this request.
-**options.languageCode** (`string`): Language code for the voice (e.g., 'en-US'). Defaults to the language code derived from the speaker ID, or 'en-US'.
-**options.input** (`ISynthesizeSpeechRequest['input']`): Rich input object passed through to the Google Cloud TTS API. Supports ssml, markup, prompt (Gemini-TTS style steering), customPronunciations, and multiSpeakerMarkup. When provided without text, ssml, markup, or multiSpeakerMarkup, the positional input argument is used as the text field automatically.
-**options.voice** (`ISynthesizeSpeechRequest['voice']`): Voice configuration merged on top of defaults (name and languageCode). Supports modelName (e.g., 'gemini-2.5-flash-preview-tts') and multiSpeakerVoiceConfig.
-**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Audio configuration options from Google Cloud Text-to-Speech API.
-Returns: `Promise<NodeJS.ReadableStream>`
-### `listen()`
-Converts speech to text using Google Cloud Speech-to-Text service. Supports both v1 (default) and v2 APIs. The v2 API adds support for AAC-in-MP4 audio (iOS Safari) via auto-decoding.
-#### v1 (default)
-**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
-**options** (`GoogleListenOptionsV1`): v1 recognition options
-**options.config** (`IRecognitionConfig`): v1 recognition configuration from Google Cloud Speech-to-Text API
-#### v2
-Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
-The v2 `recognize` call is IAM-authorized and does not accept API-key-only authentication. Configure service account credentials on the `listeningModel` (or set `GOOGLE_APPLICATION_CREDENTIALS`) and set `GOOGLE_CLOUD_PROJECT` so the recognizer path can be resolved, even when `vertexAI` is not enabled.
-```typescript
-import { GoogleVoice } from '@mastra/voice-google'
-// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
-// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
-const voice = new GoogleVoice({
-  listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
-})
-const transcript = await voice.listen(iosSafariAacStream, {
-  v2: true,
-  config: {
-    autoDecodingConfig: {},
-  },
-})
-```
-> **Note:** `listen({ v2: true })` fails with `PERMISSION_DENIED` on `speech.recognizers.recognize` when only `GOOGLE_API_KEY` is set. An API-key request carries no OAuth identity, so granting `roles/speech.client` to a user account does not help — the role must be granted to the service account presented in the request. This applies regardless of the `vertexAI` setting; `speak()` and v1 `listen()` still work with an API key alone.
-**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
-**options** (`GoogleListenOptionsV2`): v2 recognition options
-**options.v2** (`true`): Enables the v2 API path
-**options.config** (`v2.IRecognitionConfig`): v2 recognition configuration. Defaults to auto-decoding with languageCodes: \['en-US'] and model: 'long'. Set autoDecodingConfig: {} to auto-detect the audio format, or use explicitDecodingConfig to specify an encoding like MP4\_AAC, M4A\_AAC, or MOV\_AAC.
-**options.recognizer** (`string`): v2 recognizer resource path. Defaults to projects/{project}/locations/global/recognizers/\_ where {project} is resolved from the constructor project option, GOOGLE\_CLOUD\_PROJECT, or the client's default project.
-Returns: `Promise<string>`
-### `getSpeakers()`
-Returns an array of available voice options, where each node contains:
-**voiceId** (`string`): Unique identifier for the voice
-**languageCodes** (`string[]`): List of language codes supported by this voice
-### `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. Covers `speak()` and v1 `listen()`. It does not cover `listen({ v2: true })`, which is IAM-authorized and requires service account credentials (see [v2](#v2)).
-```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
-Grant `roles/speech.client` to the service account whose credentials the request presents (via `keyFilename`, `credentials`, or `GOOGLE_APPLICATION_CREDENTIALS`). This role is required for `listen({ v2: true })` specifically, not only for Vertex AI mode. Granting it to a user account has no effect on API-key-only requests, which carry no identity to authorize.
-#### 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. **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. `listen({ v2: true })` requires service account credentials and `GOOGLE_CLOUD_PROJECT`; it fails with `PERMISSION_DENIED` when only `GOOGLE_API_KEY` is set. `speak()` and v1 `listen()` work with an API key alone.
-8. Available voices can be filtered by language code using the `getSpeakers()` method.
-9. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.

package/.docs/reference/voice/inworld.md DELETED Viewed

@@ -1,137 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# Inworld
-The Inworld voice implementation in Mastra provides streaming text-to-speech (TTS) and batch speech-to-text (STT) capabilities using Inworld AI's API. It supports multiple TTS and STT models, configurable audio encodings, and progressive audio streaming.
-For real-time, full-duplex speech-to-speech, the same package exports [`InworldRealtimeVoice`](https://mastra.ai/reference/voice/inworld-realtime).
-## Usage example
-```typescript
-import { InworldVoice } from '@mastra/voice-inworld'
-// Initialize with default configuration (uses INWORLD_API_KEY environment variable)
-const voice = new InworldVoice()
-// Initialize with custom configuration
-const voice = new InworldVoice({
-  speechModel: {
-    name: 'inworld-tts-2',
-    apiKey: 'your-api-key',
-  },
-  listeningModel: {
-    name: 'groq/whisper-large-v3',
-    apiKey: 'your-api-key',
-  },
-  speaker: 'Dennis',
-})
-// Text-to-Speech (streaming)
-const audioStream = await voice.speak('Hello, world!')
-// Speech-to-Text
-const transcript = await voice.listen(audioStream)
-```
-## Constructor parameters
-**speechModel** (`InworldVoiceConfig`): Configuration for text-to-speech functionality. (Default: `{ name: 'inworld-tts-2' }`)
-**speechModel.name** (`'inworld-tts-2' | 'inworld-tts-1.5-max' | 'inworld-tts-1.5-mini'`): The Inworld TTS model to use.
-**speechModel.apiKey** (`string`): Inworld API key. Falls back to INWORLD\_API\_KEY environment variable.
-**listeningModel** (`InworldListeningConfig`): Configuration for speech-to-text functionality. (Default: `{ name: 'groq/whisper-large-v3' }`)
-**listeningModel.name** (`'groq/whisper-large-v3'`): The Inworld STT model to use.
-**listeningModel.apiKey** (`string`): Inworld API key. Falls back to INWORLD\_API\_KEY environment variable.
-**speaker** (`string`): Default voice ID to use for text-to-speech. (Default: `'Dennis'`)
-**audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'ALAW' | 'MULAW' | 'FLAC' | 'PCM' | 'WAV'`): Default audio encoding for TTS output. (Default: `'MP3'`)
-**sampleRateHertz** (`number`): Default sample rate for TTS output. (Default: `48000`)
-**language** (`string`): Default BCP-47 language code for STT. (Default: `'en-US'`)
-## Methods
-### `speak(input, options?)`
-Converts text to speech using Inworld's streaming TTS endpoint. Returns a readable stream that emits audio chunks progressively as they arrive.
-```typescript
-const audioStream = await voice.speak('Hello, world!', {
-  speaker: 'Olivia',
-  audioEncoding: 'WAV',
-  sampleRateHertz: 24000,
-  speakingRate: 1.2,
-  temperature: 0.8,
-})
-```
-**input** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
-**options** (`InworldSpeakOptions`): Additional options for speech synthesis.
-**options.speaker** (`string`): Override the default speaker for this request.
-**options.audioEncoding** (`AudioEncoding`): Override the default audio encoding.
-**options.sampleRateHertz** (`number`): Override the default sample rate.
-**options.speakingRate** (`number`): Adjust the speaking rate.
-**options.temperature** (`number`): Controls voice variability. Honored on inworld-tts-1.5-\* models; ignored by inworld-tts-2.
-**options.deliveryMode** (`'STABLE' | 'BALANCED' | 'CREATIVE'`): Steering control for delivery style. Only honored by inworld-tts-2.
-**options.language** (`string`): BCP-47 language code for this request. Auto-detected when omitted.
-**Returns:** `Promise<NodeJS.ReadableStream>`
-### `listen(input, options?)`
-Converts speech to text using Inworld's batch STT endpoint.
-```typescript
-const transcript = await voice.listen(audioStream, {
-  audioEncoding: 'MP3',
-  sampleRateHertz: 44100,
-  language: 'ja-JP',
-})
-```
-**input** (`NodeJS.ReadableStream`): Audio stream to transcribe.
-**options** (`InworldListenOptions`): Additional options for transcription.
-**options.audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'FLAC' | 'AUTO_DETECT'`): Audio encoding of the input stream.
-**options.sampleRateHertz** (`number`): Sample rate of the input audio.
-**options.language** (`string`): BCP-47 language code for transcription.
-**options.numberOfChannels** (`number`): Number of audio channels in the input.
-**Returns:** `Promise<string>`
-### `getSpeakers()`
-Returns a list of available voices from the Inworld API.
-```typescript
-const speakers = await voice.getSpeakers()
-// [{ voiceId: 'Dennis', name: 'Dennis', language: 'en', description: '...', tags: ['friendly'], source: 'SYSTEM' }, ...]
-```
-**Returns:** `Promise<Array<{ voiceId: string; name: string; language: string; description: string; tags: string[]; source: string }>>`
-## Notes
-- The TTS endpoint uses progressive NDJSON streaming, so audio playback can begin before the full response is received.
-- An API key can be provided via the `speechModel` or `listeningModel` config, or the `INWORLD_API_KEY` environment variable. TTS and STT keys are resolved independently: passing distinct `speechModel.apiKey` and `listeningModel.apiKey` values lets each service use its own credential. If only one is provided, it's reused for both services as a fallback before the env var.
-- `inworld-tts-2` is the default flagship model. Use `deliveryMode` (`STABLE` | `BALANCED` | `CREATIVE`) to steer delivery style on this model. The `temperature` option is ignored on `inworld-tts-2`.
-- The `inworld-tts-1.5-mini` model offers lower latency at the cost of reduced voice quality compared to `inworld-tts-1.5-max`.

package/.docs/reference/voice/openai.md DELETED Viewed

@@ -1,96 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# OpenAI
-The OpenAIVoice class in Mastra provides text-to-speech and speech-to-text capabilities using OpenAI's models.
-## Usage example
-```typescript
-import { OpenAIVoice } from '@mastra/voice-openai'
-// Initialize with default configuration using environment variables
-const voice = new OpenAIVoice()
-// Or initialize with specific configuration
-const voiceWithConfig = new OpenAIVoice({
-  speechModel: {
-    name: 'tts-1-hd',
-    apiKey: 'your-openai-api-key',
-  },
-  listeningModel: {
-    name: 'whisper-1',
-    apiKey: 'your-openai-api-key',
-  },
-  speaker: 'alloy', // Default voice
-})
-// Convert text to speech
-const audioStream = await voice.speak('Hello, how can I help you?', {
-  speaker: 'nova', // Override default voice
-  speed: 1.2, // Adjust speech speed
-})
-// Convert speech to text
-const text = await voice.listen(audioStream, {
-  filetype: 'mp3',
-})
-```
-## Configuration
-### Constructor options
-**speechModel** (`OpenAIConfig`): Configuration for text-to-speech synthesis. (Default: `{ name: 'tts-1' }`)
-**speechModel.name** (`'tts-1' | 'tts-1-hd' | 'whisper-1'`): Model name. Use 'tts-1-hd' for higher quality audio.
-**speechModel.apiKey** (`string`): OpenAI API key. Falls back to OPENAI\_API\_KEY environment variable.
-**listeningModel** (`OpenAIConfig`): Configuration for speech-to-text recognition. (Default: `{ name: 'whisper-1' }`)
-**listeningModel.name** (`'tts-1' | 'tts-1-hd' | 'whisper-1'`): Model name. Use 'tts-1-hd' for higher quality audio.
-**listeningModel.apiKey** (`string`): OpenAI API key. Falls back to OPENAI\_API\_KEY environment variable.
-**speaker** (`OpenAIVoiceId`): Default voice ID for speech synthesis. (Default: `'alloy'`)
-## Methods
-### `speak()`
-Converts text to speech using OpenAI's text-to-speech models.
-**input** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
-**options** (`Options`): Configuration options.
-**options.speaker** (`OpenAIVoiceId`): Voice ID to use for speech synthesis.
-**options.speed** (`number`): Speech speed multiplier.
-Returns: `Promise<NodeJS.ReadableStream>`
-### `listen()`
-Transcribes audio using OpenAI's Whisper model.
-**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe.
-**options** (`Options`): Configuration options.
-**options.filetype** (`string`): Audio format of the input stream.
-Returns: `Promise<string>`
-### `getSpeakers()`
-Returns an array of available voice options, where each node contains:
-**voiceId** (`string`): Unique identifier for the voice
-## Notes
-- API keys can be provided via constructor options or the `OPENAI_API_KEY` environment variable
-- The `tts-1-hd` model provides higher quality audio but may have slower processing times
-- Speech recognition supports multiple audio formats including mp3, wav, and webm

package/.docs/reference/voice/playai.md DELETED Viewed

@@ -1,82 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-# PlayAI
-The PlayAI voice implementation in Mastra provides text-to-speech capabilities using PlayAI's API.
-## Usage example
-```typescript
-import { PlayAIVoice } from '@mastra/voice-playai'
-// Initialize with default configuration (uses PLAYAI_API_KEY environment variable and PLAYAI_USER_ID environment variable)
-const voice = new PlayAIVoice()
-// Initialize with default configuration
-const voice = new PlayAIVoice({
-  speechModel: {
-    name: 'PlayDialog',
-    apiKey: process.env.PLAYAI_API_KEY,
-    userId: process.env.PLAYAI_USER_ID,
-  },
-  speaker: 'Angelo', // Default voice
-})
-// Convert text to speech with a specific voice
-const audioStream = await voice.speak('Hello, world!', {
-  speaker:
-    's3://voice-cloning-zero-shot/b27bc13e-996f-4841-b584-4d35801aea98/original/manifest.json', // Dexter voice
-})
-```
-## Constructor parameters
-**speechModel** (`PlayAIConfig`): Configuration for text-to-speech functionality (Default: `{ name: 'PlayDialog' }`)
-**speechModel.name** (`'PlayDialog' | 'Play3.0-mini'`): The PlayAI model to use
-**speechModel.apiKey** (`string`): PlayAI API key. Falls back to PLAYAI\_API\_KEY environment variable
-**speechModel.userId** (`string`): PlayAI user ID. Falls back to PLAYAI\_USER\_ID environment variable
-**speaker** (`string`): Default voice ID to use for speech synthesis (Default: `First available voice ID`)
-## Methods
-### `speak()`
-Converts text to speech using the configured speech model and voice.
-**input** (`string | NodeJS.ReadableStream`): Text to convert to speech. If a stream is provided, it will be converted to text first.
-**options** (`Options`): Configuration options.
-**options.speaker** (`string`): Override the default speaker for this request
-Returns: `Promise<NodeJS.ReadableStream>`.
-### `getSpeakers()`
-Returns an array of available voice options, where each node contains:
-**name** (`string`): Name of the voice
-**accent** (`string`): Accent of the voice (e.g., 'US', 'British', 'Australian')
-**gender** (`'M' | 'F'`): Gender of the voice
-**age** (`'Young' | 'Middle' | 'Old'`): Age category of the voice
-**style** (`'Conversational' | 'Narrative'`): Speaking style of the voice
-**voiceId** (`string`): Unique identifier for the voice
-### `listen()`
-This method isn't supported by PlayAI and will throw an error. PlayAI doesn't provide speech-to-text functionality.
-## Notes
-- PlayAI requires both an API key and a user ID for authentication
-- The service offers two models: 'PlayDialog' and 'Play3.0-mini'
-- Each voice has a unique S3 manifest ID that must be used when making API calls