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

package/.docs/reference/vectors/qdrant.md

@@ -0,0 +1,222 @@
+# Qdrant Vector Store
+
+The QdrantVector class provides vector search using [Qdrant](https://qdrant.tech/), a vector similarity search engine. It provides a production-ready service with a convenient API to store, search, and manage vectors with additional payload and extended filtering support.
+
+## Constructor Options
+
+**url:** (`string`): REST URL of the Qdrant instance. Eg. https\://xyz-example.eu-central.aws.cloud.qdrant.io:6333
+
+**apiKey:** (`string`): Optional Qdrant API key
+
+**https:** (`boolean`): Whether to use TLS when setting up the connection. Recommended.
+
+## Methods
+
+### createIndex()
+
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension (must match your embedding model). Required for single-vector collections.
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+**namedVectors?:** (`Record<string, { size: number; distance: 'cosine' | 'euclidean' | 'dotproduct' }>`): Configuration for named vector spaces. When provided, creates a collection with multiple named vector fields.
+
+#### Creating a Named Vectors Collection
+
+```typescript
+// Create a collection with multiple named vector spaces
+await store.createIndex({
+  indexName: 'multi_modal',
+  dimension: 768, // fallback
+  namedVectors: {
+    text: { size: 768, distance: 'cosine' },
+    image: { size: 512, distance: 'euclidean' },
+  },
+})
+```
+
+### 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)
+
+**vectorName?:** (`string`): Name of the vector space to upsert into when using named vectors.
+
+#### Upserting into Named Vector Spaces
+
+```typescript
+// Upsert into the "text" vector space
+await store.upsert({
+  indexName: 'multi_modal',
+  vectors: textEmbeddings,
+  metadata: textMetadata,
+  vectorName: 'text',
+})
+
+// Upsert into the "image" vector space
+await store.upsert({
+  indexName: 'multi_modal',
+  vectors: imageEmbeddings,
+  metadata: imageMetadata,
+  vectorName: 'image',
+})
+```
+
+### 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`)
+
+**using?:** (`string`): Name of the vector field to query when using named vectors. Use this when your collection has multiple named vector fields.
+
+#### Named Vectors
+
+Qdrant supports [named vectors](https://qdrant.tech/documentation/concepts/vectors/#named-vectors), allowing multiple vector fields per collection. Use the `using` parameter to specify which named vector to query against:
+
+```typescript
+const results = await store.query({
+  indexName: 'my_index',
+  queryVector: embedding,
+  topK: 10,
+  using: 'title_embedding', // Query against a specific named vector
+})
+```
+
+### 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
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): Name of the index to update
+
+**id?:** (`string`): ID of the vector to update (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+
+Updates a vector and/or its metadata in the specified index. If both vector and metadata are provided, both will be updated. If only one is provided, only that will be updated.
+
+### deleteVector()
+
+**indexName:** (`string`): Name of the index from which to delete the vector
+
+**id:** (`string`): ID of the vector to delete
+
+Deletes a vector from the specified index by its ID.
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): Name of the index containing the vectors to delete
+
+**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
+
+### createPayloadIndex()
+
+Creates a payload (metadata) index on a collection field to enable efficient filtering. This is **required** for Qdrant Cloud and any Qdrant instance with `strict_mode_config = true`.
+
+**indexName:** (`string`): Name of the collection to create the payload index on
+
+**fieldName:** (`string`): Name of the payload field to index
+
+**fieldSchema:** (`'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'`): The schema type for the payload field
+
+**wait?:** (`boolean`): Whether to wait for the operation to complete (Default: `true`)
+
+```typescript
+// Create a keyword index for filtering by source
+await store.createPayloadIndex({
+  indexName: 'my_index',
+  fieldName: 'source',
+  fieldSchema: 'keyword',
+})
+
+const results = await store.query({
+  indexName: 'my_index',
+  queryVector: queryVector,
+  filter: { source: 'document-a' },
+})
+```
+
+### deletePayloadIndex()
+
+Removes a payload index from a collection field.
+
+**indexName:** (`string`): Name of the collection to delete the payload index from
+
+**fieldName:** (`string`): Name of the payload field index to delete
+
+**wait?:** (`boolean`): Whether to wait for the operation to complete (Default: `true`)
+
+## 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
+  }
+}
+```
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/vectors/s3vectors.md

@@ -0,0 +1,277 @@
+# Amazon S3 Vectors Store
+
+The `S3Vectors` class provides vector search using [Amazon S3 Vectors (Preview)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html). It stores vectors in **vector buckets** and performs similarity search in **vector indexes**, with JSON-based metadata filters.
+
+> **Warning:** Amazon S3 Vectors is a Preview service. Preview features may change or be removed without notice and are not covered by AWS SLAs. Behavior, limits, and regional availability can change at any time. This library may introduce breaking changes to stay aligned with AWS.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/s3vectors@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/s3vectors@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/s3vectors@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/s3vectors@latest
+```
+
+## Usage Example
+
+```typescript
+import { S3Vectors } from '@mastra/s3vectors'
+
+const store = new S3Vectors({
+  vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // e.g. "my-vector-bucket"
+  clientConfig: {
+    region: process.env.AWS_REGION!, // credentials use the default AWS provider chain
+  },
+  // Optional: mark large/long-text fields as non-filterable at index creation time
+  nonFilterableMetadataKeys: ['content'],
+})
+
+// Create an index (names are normalized: "_" → "-" and lowercased)
+await store.createIndex({
+  indexName: 'my_index',
+  dimension: 1536,
+  metric: 'cosine', // "euclidean" also supported; "dotproduct" is NOT supported
+})
+
+// Upsert vectors (ids auto-generated if omitted). Date values in metadata are serialized to epoch ms.
+const ids = await store.upsert({
+  indexName: 'my_index',
+  vectors: [
+    [0.1, 0.2 /* … */],
+    [0.3, 0.4 /* … */],
+  ],
+  metadata: [
+    {
+      text: 'doc1',
+      genre: 'documentary',
+      year: 2023,
+      createdAt: new Date('2024-01-01'),
+    },
+    { text: 'doc2', genre: 'comedy', year: 2021 },
+  ],
+})
+
+// Query with metadata filters (implicit AND is canonicalized)
+const results = await store.query({
+  indexName: 'my-index',
+  queryVector: [0.1, 0.2 /* … */],
+  topK: 10, // Service-side limits may apply (commonly 30)
+  filter: { genre: { $in: ['documentary', 'comedy'] }, year: { $gte: 2020 } },
+  includeVector: false, // set true to include raw vectors (may trigger a secondary fetch)
+})
+
+// Clean up resources (closes the underlying HTTP handler)
+await store.disconnect()
+```
+
+## Constructor Options
+
+**vectorBucketName:** (`string`): Target S3 Vectors vector bucket name.
+
+**clientConfig?:** (`S3VectorsClientConfig`): AWS SDK v3 client options (e.g., \`region\`, \`credentials\`).
+
+**nonFilterableMetadataKeys?:** (`string[]`): Metadata keys that should NOT be filterable (applied to the index at creation time). Use this for large text fields like \`content\`.
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index in the configured vector bucket. If the index already exists, the call validates the schema and becomes a no-op (existing metric and dimension are preserved).
+
+**indexName:** (`string`): Logical index name. Normalized internally: underscores are replaced with hyphens and the name is lowercased.
+
+**dimension:** (`number`): Vector dimension (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean'`): Distance metric for similarity search. \`dotproduct\` is not supported by S3 Vectors. (Default: `cosine`)
+
+### upsert()
+
+Adds or replaces vectors (full-record put). If `ids` are not provided, UUIDs are generated.
+
+**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()
+
+Searches for nearest neighbors with optional metadata filtering.
+
+**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?:** (`S3VectorsFilter`): JSON-based metadata filter supporting \`$and\`, \`$or\`, \`$eq\`, \`$ne\`, \`$gt\`, \`$gte\`, \`$lt\`, \`$lte\`, \`$in\`, \`$nin\`, \`$exists\`.
+
+**includeVector?:** (`boolean`): Whether to include vectors in the results (Default: `false`)
+
+> **Note:** Results include `score = 1/(1 + distance)` so that higher is better while preserving the underlying distance ranking.
+
+### describeIndex()
+
+Returns information about the index.
+
+**indexName:** (`string`): Index name to describe.
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number // computed via ListVectors pagination (O(n))
+  metric: 'cosine' | 'euclidean'
+}
+```
+
+### deleteIndex()
+
+Deletes an index and its data.
+
+**indexName:** (`string`): Index to delete.
+
+### listIndexes()
+
+Lists all indexes in the configured vector bucket.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Updates a vector or metadata for a specific ID within an index.
+
+**indexName:** (`string`): Index containing the vector.
+
+**id:** (`string`): ID to update.
+
+**update:** (`object`): Update data containing vector and/or metadata
+
+**update.vector?:** (`number[]`): New vector data to update
+
+**update.metadata?:** (`Record<string, any>`): New metadata to update
+
+### deleteVector()
+
+Deletes a specific vector by ID.
+
+**indexName:** (`string`): Index containing the vector.
+
+**id:** (`string`): ID to delete.
+
+### disconnect()
+
+Closes the underlying AWS SDK HTTP handler to free sockets.
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string
+  score: number // 1/(1 + distance)
+  metadata: Record<string, any>
+  vector?: number[] // Only included if includeVector is true
+}
+```
+
+## Filter Syntax
+
+S3 Vectors supports a strict subset of operators and value types. The Mastra filter translator:
+
+- **Canonicalizes implicit AND**: `{a:1,b:2}` → `{ $and: [{a:1},{b:2}] }`.
+- **Normalizes Date values** to epoch ms for numeric comparisons and array elements.
+- **Disallows Date** in equality positions (`field: value` or `$eq/$ne`); equality values must be **string | number | boolean**.
+- **Rejects** null/undefined for equality; **array equality** is not supported (use `$in`/`$nin`).
+- Only **`$and` / `$or`** are allowed as top-level logical operators.
+- Logical operators must contain **field conditions** (not direct operators).
+
+**Supported operators:**
+
+- **Logical:** `$and`, `$or` (non-empty arrays)
+- **Basic:** `$eq`, `$ne` (string | number | boolean)
+- **Numeric:** `$gt`, `$gte`, `$lt`, `$lte` (number or `Date` → epoch ms)
+- **Array:** `$in`, `$nin` (non-empty arrays of string | number | boolean; `Date` → epoch ms)
+- **Element:** `$exists` (boolean)
+
+**Unsupported / disallowed (rejected):** `$not`, `$nor`, `$regex`, `$all`, `$elemMatch`, `$size`, `$text`, etc.
+
+**Examples:**
+
+```typescript
+// Implicit AND
+{ genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } }
+
+// Explicit logicals and ranges
+{
+  $and: [
+    { price: { $gte: 100, $lte: 1000 } },
+    { $or: [{ stock: { $gt: 0 } }, { preorder: true }] }
+  ]
+}
+
+// Dates in range (converted to epoch ms)
+{ timestamp: { $gt: new Date("2024-01-01T00:00:00Z") } }
+```
+
+> **Note:** If you set `nonFilterableMetadataKeys` at index creation, those keys are stored but **cannot** be used in filters.
+
+## 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
+
+Typical environment variables when wiring your app:
+
+- `S3_VECTORS_BUCKET_NAME`: Your S3 **vector bucket** name (used to populate `vectorBucketName`).
+- `AWS_REGION`: AWS region for the S3 Vectors bucket.
+- **AWS credentials**: via the standard AWS SDK provider chain (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_PROFILE`, etc.).
+
+## Best Practices
+
+- Choose the metric (`cosine` or `euclidean`) to match your embedding model; `dotproduct` is not supported.
+- Keep **filterable** metadata small and structured (string/number/boolean). Store large text (e.g., `content`) as **non-filterable**.
+- Use **dotted paths** for nested metadata and explicit `$and`/`$or` for complex logic.
+- Avoid calling `describeIndex()` on hot paths—`count` is computed with paginated `ListVectors` (**O(n)**).
+- Use `includeVector: true` only when you need raw vectors.
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/vectors/turbopuffer.md

@@ -0,0 +1,157 @@
+# Turbopuffer Vector Store
+
+The TurbopufferVector class provides vector search using [Turbopuffer](https://turbopuffer.com/), a high-performance vector database optimized for RAG applications. Turbopuffer offers fast vector similarity search with advanced filtering capabilities and efficient storage management.
+
+## Constructor Options
+
+**apiKey:** (`string`): The API key to authenticate with Turbopuffer
+
+**baseUrl?:** (`string`): The base URL for the Turbopuffer API (Default: `https://api.turbopuffer.com`)
+
+**connectTimeout?:** (`number`): The timeout to establish a connection, in ms. Only applicable in Node and Deno. (Default: `10000`)
+
+**connectionIdleTimeout?:** (`number`): The socket idle timeout, in ms. Only applicable in Node and Deno. (Default: `60000`)
+
+**warmConnections?:** (`number`): The number of connections to open initially when creating a new client. (Default: `0`)
+
+**compression?:** (`boolean`): Whether to compress requests and accept compressed responses. (Default: `true`)
+
+**schemaConfigForIndex?:** (`function`): A callback function that takes an index name and returns a config object for that index. This allows you to define explicit schemas per index.
+
+## 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 (Default: `cosine`)
+
+### upsert()
+
+**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
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id?:** (`string`): ID of the vector to update (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+
+### deleteVector()
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): ID of the vector to delete
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): Name of the index containing the vectors to delete
+
+**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
+
+## 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
+}
+```
+
+## Schema Configuration
+
+The `schemaConfigForIndex` option allows you to define explicit schemas for different indexes:
+
+```typescript
+schemaConfigForIndex: (indexName: string) => {
+  // Mastra's default embedding model and index for memory messages:
+  if (indexName === 'memory_messages_384') {
+    return {
+      dimensions: 384,
+      schema: {
+        thread_id: {
+          type: 'string',
+          filterable: true,
+        },
+      },
+    }
+  } else {
+    throw new Error(`TODO: add schema for index: ${indexName}`)
+  }
+}
+```
+
+## 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
+  }
+}
+```
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)