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

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

@@ -1,294 +0,0 @@
-# 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

@@ -1,147 +0,0 @@
-# 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

@@ -1,148 +0,0 @@
-# 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

@@ -1,83 +0,0 @@
-# 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