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

package/.docs/reference/vectors/upstash.md

@@ -0,0 +1,294 @@
+# Upstash Vector Store
+
+The UpstashVector class provides vector search using [Upstash Vector](https://upstash.com/vector), a serverless vector database service that provides vector similarity search with metadata filtering capabilities and hybrid search support.
+
+## Constructor Options
+
+**url:** (`string`): Upstash Vector database URL
+
+**token:** (`string`): Upstash Vector API token
+
+## Methods
+
+### createIndex()
+
+Note: This method is a no-op for Upstash as indexes are created automatically.
+
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+### upsert()
+
+**indexName:** (`string`): Name of the index to upsert into
+
+**vectors:** (`number[][]`): Array of embedding vectors
+
+**sparseVectors?:** (`{ indices: number[], values: number[] }[]`): Array of sparse vectors for hybrid search. Each sparse vector must have matching indices and values arrays.
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
+### query()
+
+**indexName:** (`string`): Name of the index to query
+
+**queryVector:** (`number[]`): Query vector to find similar vectors
+
+**sparseVector?:** (`{ indices: number[], values: number[] }`): Optional sparse vector for hybrid search. Must have matching indices and values arrays.
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Record<string, any>`): Metadata filters for the query
+
+**includeVector?:** (`boolean`): Whether to include vectors in the results (Default: `false`)
+
+**fusionAlgorithm?:** (`FusionAlgorithm`): Algorithm used to combine dense and sparse search results in hybrid search (e.g., RRF - Reciprocal Rank Fusion)
+
+**queryMode?:** (`QueryMode`): Search mode: 'DENSE' for dense-only, 'SPARSE' for sparse-only, or 'HYBRID' for combined search
+
+### listIndexes()
+
+Returns an array of index names (namespaces) as strings.
+
+### describeIndex()
+
+**indexName:** (`string`): Name of the index to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### deleteIndex()
+
+**indexName:** (`string`): Name of the index (namespace) to delete
+
+### updateVector()
+
+**indexName:** (`string`): Name of the index to update
+
+**id:** (`string`): ID of the item to update
+
+**update:** (`object`): Update object containing vector, sparse vector, and/or metadata
+
+The `update` object can have the following properties:
+
+- `vector` (optional): An array of numbers representing the new dense vector.
+- `sparseVector` (optional): A sparse vector object with `indices` and `values` arrays for hybrid indexes.
+- `metadata` (optional): A record of key-value pairs for metadata.
+
+### deleteVector()
+
+**indexName:** (`string`): Name of the index from which to delete the item
+
+**id:** (`string`): ID of the item to delete
+
+Attempts to delete an item by its ID from the specified index. Logs an error message if the deletion fails.
+
+## Hybrid Vector Search
+
+Upstash Vector supports hybrid search that combines semantic search (dense vectors) with keyword-based search (sparse vectors) for improved relevance and accuracy.
+
+### Basic Hybrid Usage
+
+```typescript
+import { UpstashVector } from '@mastra/upstash'
+
+const vectorStore = new UpstashVector({
+  id: 'upstash-vector',
+  url: process.env.UPSTASH_VECTOR_URL,
+  token: process.env.UPSTASH_VECTOR_TOKEN,
+})
+
+// Upsert vectors with both dense and sparse components
+const denseVectors = [
+  [0.1, 0.2, 0.3],
+  [0.4, 0.5, 0.6],
+]
+const sparseVectors = [
+  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
+  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
+]
+
+await vectorStore.upsert({
+  indexName: 'hybrid-index',
+  vectors: denseVectors,
+  sparseVectors: sparseVectors,
+  metadata: [{ title: 'Document 1' }, { title: 'Document 2' }],
+})
+
+// Query with hybrid search
+const results = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  topK: 10,
+})
+```
+
+### Advanced Hybrid Search Options
+
+```typescript
+import { FusionAlgorithm, QueryMode } from '@upstash/vector'
+
+// Query with specific fusion algorithm
+const fusionResults = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  fusionAlgorithm: FusionAlgorithm.RRF,
+  topK: 10,
+})
+
+// Dense-only search
+const denseResults = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3],
+  queryMode: QueryMode.DENSE,
+  topK: 10,
+})
+
+// Sparse-only search
+const sparseResults = await vectorStore.query({
+  indexName: 'hybrid-index',
+  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  queryMode: QueryMode.SPARSE,
+  topK: 10,
+})
+```
+
+### Updating Hybrid Vectors
+
+```typescript
+// Update both dense and sparse components
+await vectorStore.updateVector({
+  indexName: 'hybrid-index',
+  id: 'vector-id',
+  update: {
+    vector: [0.2, 0.3, 0.4],
+    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
+    metadata: { title: 'Updated Document' },
+  },
+})
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[] // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: 'index_name',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details) // Additional error context
+  }
+}
+```
+
+## Environment Variables
+
+Required environment variables:
+
+- `UPSTASH_VECTOR_URL`: Your Upstash Vector database URL
+- `UPSTASH_VECTOR_TOKEN`: Your Upstash Vector API token
+
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+**npm**:
+
+```bash
+npm install @mastra/fastembed@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
+Add the following to your agent:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { UpstashStore, UpstashVector } from '@mastra/upstash'
+import { fastembed } from '@mastra/fastembed'
+
+export const upstashAgent = new Agent({
+  id: 'upstash-agent',
+  name: 'Upstash Agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-5.1',
+  memory: new Memory({
+    storage: new UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    vector: new UpstashVector({
+      id: 'upstash-agent-vector',
+      url: process.env.UPSTASH_VECTOR_REST_URL!,
+      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+    },
+  }),
+})
+```
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/vectors/vectorize.md

@@ -0,0 +1,147 @@
+# Cloudflare Vector Store
+
+The CloudflareVector class provides vector search using [Cloudflare Vectorize](https://developers.cloudflare.com/vectorize/), a vector database service integrated with Cloudflare's edge network.
+
+## Constructor Options
+
+**accountId:** (`string`): Cloudflare account ID
+
+**apiToken:** (`string`): Cloudflare API token with Vectorize permissions
+
+## Methods
+
+### createIndex()
+
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (dotproduct maps to dot-product) (Default: `cosine`)
+
+### upsert()
+
+**indexName:** (`string`): Name of the index to upsert into
+
+**vectors:** (`number[][]`): Array of embedding vectors
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
+### query()
+
+**indexName:** (`string`): Name of the index to query
+
+**queryVector:** (`number[]`): Query vector to find similar vectors
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Record<string, any>`): Metadata filters for the query
+
+**includeVector?:** (`boolean`): Whether to include vectors in the results (Default: `false`)
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+**indexName:** (`string`): Name of the index to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### deleteIndex()
+
+**indexName:** (`string`): Name of the index to delete
+
+### createMetadataIndex()
+
+Creates an index on a metadata field to enable filtering.
+
+**indexName:** (`string`): Name of the index containing the metadata field
+
+**propertyName:** (`string`): Name of the metadata field to index
+
+**indexType:** (`'string' | 'number' | 'boolean'`): Type of the metadata field
+
+### deleteMetadataIndex()
+
+Removes an index from a metadata field.
+
+**indexName:** (`string`): Name of the index containing the metadata field
+
+**propertyName:** (`string`): Name of the metadata field to remove indexing from
+
+### listMetadataIndexes()
+
+Lists all metadata field indexes for an index.
+
+**indexName:** (`string`): Name of the index to list metadata indexes for
+
+### updateVector()
+
+Updates a vector or metadata for a specific ID within an index.
+
+**indexName:** (`string`): Name of the index containing the ID to update
+
+**id:** (`string`): Unique identifier of the vector or metadata to update
+
+**update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+
+### deleteVector()
+
+Deletes a vector and its associated metadata for a specific ID within an index.
+
+**indexName:** (`string`): Name of the index containing the ID to delete
+
+**id:** (`string`): Unique identifier of the vector and metadata to delete
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[]
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: 'index_name',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details) // Additional error context
+  }
+}
+```
+
+## Environment Variables
+
+Required environment variables:
+
+- `CLOUDFLARE_ACCOUNT_ID`: Your Cloudflare account ID
+- `CLOUDFLARE_API_TOKEN`: Your Cloudflare API token with Vectorize permissions
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/voice/azure.md

@@ -0,0 +1,148 @@
+# Azure
+
+The AzureVoice class in Mastra provides text-to-speech and speech-to-text capabilities using Microsoft Azure Cognitive Services.
+
+## Usage Example
+
+This requires Azure Speech Services credentials that can be provided through environment variables or directly in the configuration:
+
+```typescript
+import { AzureVoice } from '@mastra/voice-azure'
+
+// Initialize with configuration
+const voice = new AzureVoice({
+  speechModel: {
+    apiKey: 'your-azure-speech-api-key', // Or use AZURE_API_KEY env var
+    region: 'eastus', // Or use AZURE_REGION env var
+    voiceName: 'en-US-AriaNeural', // Optional: specific voice for TTS
+  },
+  listeningModel: {
+    apiKey: 'your-azure-speech-api-key', // Or use AZURE_API_KEY env var
+    region: 'eastus', // Or use AZURE_REGION env var
+    language: 'en-US', // Optional: recognition language for STT
+  },
+  speaker: 'en-US-JennyNeural', // Optional: default voice
+})
+
+// Convert text to speech
+const audioStream = await voice.speak('Hello, how can I help you?', {
+  speaker: 'en-US-GuyNeural', // Optional: override default voice
+})
+
+// Convert speech to text
+const text = await voice.listen(audioStream)
+```
+
+## Configuration
+
+### Constructor Options
+
+**speechModel?:** (`AzureSpeechConfig`): Configuration for text-to-speech synthesis.
+
+**listeningModel?:** (`AzureSpeechConfig`): Configuration for speech-to-text recognition.
+
+**speaker?:** (`string`): Default voice ID for speech synthesis.
+
+### AzureSpeechConfig
+
+Configuration object for speech synthesis (`speechModel`) and recognition (`listeningModel`).
+
+**apiKey?:** (`string`): Azure Speech Services API key (NOT Azure OpenAI key). Falls back to AZURE\_API\_KEY environment variable.
+
+**region?:** (`string`): Azure region (e.g., 'eastus', 'westeurope'). Falls back to AZURE\_REGION environment variable.
+
+**voiceName?:** (`string`): Voice ID for speech synthesis (e.g., 'en-US-AriaNeural', 'en-US-JennyNeural'). Only used in speechModel. See voice list below.
+
+**language?:** (`string`): Recognition language code (e.g., 'en-US', 'fr-FR'). Only used in listeningModel.
+
+## Methods
+
+### speak()
+
+Converts text to speech using Azure's neural text-to-speech service.
+
+**input:** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options.speaker?:** (`string`): Voice ID to use for speech synthesis (e.g., 'en-US-JennyNeural'). Overrides the default voice. (Default: `Constructor's speaker value`)
+
+Returns: `Promise<NodeJS.ReadableStream>` - Audio stream in WAV format
+
+### listen()
+
+Transcribes audio using Azure's speech-to-text service.
+
+**audioStream:** (`NodeJS.ReadableStream`): Audio stream to transcribe. Must be in WAV format.
+
+Returns: `Promise<string>` - The recognized text from the audio
+
+**Note:** Language and recognition settings are configured in the `listeningModel` configuration during initialization, not passed as options to this method.
+
+### getSpeakers()
+
+Returns an array of available voice options (200+ voices), where each node contains:
+
+**voiceId:** (`string`): Unique identifier for the voice (e.g., 'en-US-JennyNeural', 'fr-FR-DeniseNeural')
+
+**language:** (`string`): Language code extracted from voice ID (e.g., 'en', 'fr')
+
+**region:** (`string`): Region code extracted from voice ID (e.g., 'US', 'GB', 'FR')
+
+Returns: `Promise<Array<{ voiceId: string; language: string; region: string; }>>`
+
+## Important Notes
+
+### Azure Speech Services vs Azure OpenAI
+
+**⚠️ Critical:** This package uses **Azure Speech Services**, which is different from **Azure OpenAI Services**.
+
+- **DO NOT** use your `AZURE_OPENAI_API_KEY` for this package
+- **DO** use an Azure Speech Services subscription key (obtain from Azure Portal under "Speech Services")
+- These are separate Azure resources with different API keys and endpoints
+
+### Environment Variables
+
+API keys and regions can be provided via constructor options or environment variables:
+
+- `AZURE_API_KEY` - Your Azure Speech Services subscription key
+- `AZURE_REGION` - Your Azure region (e.g., 'eastus', 'westeurope')
+
+### Voice Capabilities
+
+- Azure offers 200+ neural voices across 50+ languages
+- Each voice ID follows the format: `{language}-{region}-{name}Neural` (e.g., 'en-US-JennyNeural')
+- Some voices include multilingual support or HD quality variants
+- Audio output is in WAV format
+- Audio input for recognition must be in WAV format
+
+## Available Voices
+
+Azure provides 200+ neural voices across many languages. Some popular English voices include:
+
+- **US English:**
+
+  - `en-US-AriaNeural` (Female, default)
+  - `en-US-JennyNeural` (Female)
+  - `en-US-GuyNeural` (Male)
+  - `en-US-DavisNeural` (Male)
+  - `en-US-AvaNeural` (Female)
+  - `en-US-AndrewNeural` (Male)
+
+- **British English:**
+
+  - `en-GB-SoniaNeural` (Female)
+  - `en-GB-RyanNeural` (Male)
+  - `en-GB-LibbyNeural` (Female)
+
+- **Australian English:**
+
+  - `en-AU-NatashaNeural` (Female)
+  - `en-AU-WilliamNeural` (Male)
+
+To get a complete list of all 200+ voices:
+
+```typescript
+const voices = await voice.getSpeakers()
+console.log(voices) // Array of { voiceId, language, region }
+```
+
+For more information, see the [Azure Neural TTS documentation](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=tts).

package/.docs/reference/voice/cloudflare.md

@@ -0,0 +1,83 @@
+# Cloudflare
+
+The CloudflareVoice class in Mastra provides text-to-speech capabilities using Cloudflare Workers AI. This provider specializes in efficient, low-latency speech synthesis suitable for edge computing environments.
+
+## Usage Example
+
+```typescript
+import { CloudflareVoice } from '@mastra/voice-cloudflare'
+
+// Initialize with configuration
+const voice = new CloudflareVoice({
+  speechModel: {
+    name: '@cf/meta/m2m100-1.2b',
+    apiKey: 'your-cloudflare-api-token',
+    accountId: 'your-cloudflare-account-id',
+  },
+  speaker: 'en-US-1', // Default voice
+})
+
+// Convert text to speech
+const audioStream = await voice.speak('Hello, how can I help you?', {
+  speaker: 'en-US-2', // Override default voice
+})
+
+// Get available voices
+const speakers = await voice.getSpeakers()
+console.log(speakers)
+```
+
+## Configuration
+
+### Constructor Options
+
+**speechModel?:** (`CloudflareSpeechConfig`): Configuration for text-to-speech synthesis.
+
+**speaker?:** (`string`): Default voice ID for speech synthesis. (Default: `'en-US-1'`)
+
+### CloudflareSpeechConfig
+
+**name?:** (`string`): Model name to use for TTS. (Default: `'@cf/meta/m2m100-1.2b'`)
+
+**apiKey?:** (`string`): Cloudflare API token with Workers AI access. Falls back to CLOUDFLARE\_API\_TOKEN environment variable.
+
+**accountId?:** (`string`): Cloudflare account ID. Falls back to CLOUDFLARE\_ACCOUNT\_ID environment variable.
+
+## Methods
+
+### speak()
+
+Converts text to speech using Cloudflare's text-to-speech service.
+
+**input:** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options.speaker?:** (`string`): Voice ID to use for speech synthesis. (Default: `Constructor's speaker value`)
+
+**options.format?:** (`string`): Output audio format. (Default: `'mp3'`)
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### getSpeakers()
+
+Returns an array of available voice options, where each node contains:
+
+**voiceId:** (`string`): Unique identifier for the voice (e.g., 'en-US-1')
+
+**language:** (`string`): Language code of the voice (e.g., 'en-US')
+
+## Notes
+
+- API tokens can be provided via constructor options or environment variables (CLOUDFLARE\_API\_TOKEN and CLOUDFLARE\_ACCOUNT\_ID)
+- Cloudflare Workers AI is optimized for edge computing with low latency
+- This provider only supports text-to-speech (TTS) functionality, not speech-to-text (STT)
+- The service integrates well with other Cloudflare Workers products
+- For production use, ensure your Cloudflare account has the appropriate Workers AI subscription
+- Voice options are more limited compared to some other providers, but performance at the edge is excellent
+
+## Related Providers
+
+If you need speech-to-text capabilities in addition to text-to-speech, consider using one of these providers:
+
+- [OpenAI](https://mastra.ai/reference/voice/openai) - Provides both TTS and STT
+- [Google](https://mastra.ai/reference/voice/google) - Provides both TTS and STT
+- [Azure](https://mastra.ai/reference/voice/azure) - Provides both TTS and STT