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

package/.docs/reference/vectors/couchbase.md

@@ -0,0 +1,226 @@
+# Couchbase Vector Store
+
+The `CouchbaseVector` class provides vector search using [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html). It enables efficient similarity search and metadata filtering within your Couchbase collections.
+
+## Requirements
+
+- **Couchbase Server 7.6.4+** or a compatible Capella cluster
+- **Search Service enabled** on your Couchbase deployment
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/couchbase@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/couchbase@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/couchbase@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/couchbase@latest
+```
+
+## Usage Example
+
+```typescript
+import { CouchbaseVector } from '@mastra/couchbase'
+
+const store = new CouchbaseVector({
+  id: 'couchbase-vector',
+  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
+  username: process.env.COUCHBASE_USERNAME,
+  password: process.env.COUCHBASE_PASSWORD,
+  bucketName: process.env.COUCHBASE_BUCKET,
+  scopeName: process.env.COUCHBASE_SCOPE,
+  collectionName: process.env.COUCHBASE_COLLECTION,
+})
+```
+
+## Constructor Options
+
+**id:** (`string`): Unique identifier for this vector store instance
+
+**connectionString:** (`string`): Couchbase connection string
+
+**username:** (`string`): Couchbase username
+
+**password:** (`string`): Couchbase password
+
+**bucketName:** (`string`): Name of the Couchbase bucket to use
+
+**scopeName:** (`string`): Name of the Couchbase scope to use
+
+**collectionName:** (`string`): Name of the Couchbase collection to use
+
+**options?:** (`CouchbaseClientOptions`): Optional Couchbase client options
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index in Couchbase.
+
+> **Note:** Index creation is asynchronous. After calling `createIndex`, allow time (typically 1–5 seconds for small datasets, longer for large ones) before querying. For production, implement polling to check index status rather than using fixed delays.
+
+**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()
+
+Adds or updates vectors and their metadata in the collection.
+
+> **Note:** You can upsert data before or after creating the index. The `upsert` method does not require the index to exist. Couchbase allows multiple Search indexes over the same collection.
+
+**indexName:** (`string`): Name of the index to insert 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 similar vectors.
+
+> **Warning:** The `filter` and `includeVector` parameters are not currently supported. Filtering must be performed client-side after retrieving results, or by using the Couchbase SDK's Search capabilities directly. To retrieve the vector embedding, fetch the full document by ID using the Couchbase SDK.
+
+**indexName:** (`string`): Name of the index to search in
+
+**queryVector:** (`number[]`): Query vector to find similar vectors for
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Record<string, any>`): Metadata filters
+
+**includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)
+
+**minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)
+
+### describeIndex()
+
+Returns information about the index.
+
+**indexName:** (`string`): Name of the index to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### deleteIndex()
+
+Deletes an index and all its data.
+
+**indexName:** (`string`): Name of the index to delete
+
+### listIndexes()
+
+Lists all vector indexes in the Couchbase bucket.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Updates a specific vector entry by its ID with new vector data and/or metadata. **Note:** Filter-based updates are not yet implemented for Couchbase.
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): ID of the vector entry to update
+
+**update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+
+### deleteVector()
+
+Deletes a single vector by its ID from the index.
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): ID of the vector to delete
+
+### deleteVectors()
+
+Deletes multiple vectors by their IDs. **Note:** Filter-based deletion is not yet implemented for Couchbase.
+
+**indexName:** (`string`): Name of the index containing the vectors to delete
+
+**ids:** (`string[]`): Array of vector IDs to delete
+
+### disconnect()
+
+Closes the Couchbase client connection. Should be called when done using the store.
+
+## 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: 'my_index',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes('Invalid index name')) {
+    console.error(
+      'Index name must start with a letter or underscore and contain only valid characters.',
+    )
+  } else if (error.message.includes('Index not found')) {
+    console.error('The specified index does not exist')
+  } else {
+    console.error('Vector store error:', error.message)
+  }
+}
+```
+
+## Notes
+
+- **Index Deletion Caveat:** Deleting a Search index does NOT delete the vectors/documents in the associated Couchbase collection. Data remains unless explicitly removed.
+- **Required Permissions:** The Couchbase user must have permissions to connect, read/write documents in the target collection (`kv` role), and manage Search Indexes (`search_admin` role on the relevant bucket/scope).
+- **Index Definition Details & Document Structure:** The `createIndex` method constructs a Search Index definition that indexes the `embedding` field (as type `vector`) and the `content` field (as type `text`), targeting documents within the specified `scopeName.collectionName`. Each document stores the vector in the `embedding` field and metadata in the `metadata` field. If `metadata` contains a `text` property, its value is also copied to a top-level `content` field, which is indexed for text search.
+- **Replication & Durability:** Consider using Couchbase's built-in replication and persistence features for data durability. Monitor index statistics regularly to ensure efficient search.
+
+## Limitations
+
+- Index creation delays may impact immediate querying after creation.
+- No hard enforcement of vector dimension at ingest time (dimension mismatches will error at query time).
+- Vector insertion and index updates are eventually consistent; strong consistency is not guaranteed immediately after writes.
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/vectors/duckdb.md

@@ -0,0 +1,318 @@
+# DuckDBVector Store
+
+The DuckDB storage implementation provides an embedded high-performance vector search solution using [DuckDB](https://duckdb.org/), an in-process analytical database. It uses the VSS extension for vector similarity search with HNSW indexing, offering a lightweight and efficient vector database that requires no external server.
+
+It's part of the `@mastra/duckdb` package and offers efficient vector similarity search with metadata filtering.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/duckdb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/duckdb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/duckdb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/duckdb@latest
+```
+
+## Usage
+
+```typescript
+import { DuckDBVector } from "@mastra/duckdb";
+
+// Create a new vector store instance
+const store = new DuckDBVector({
+  id: "duckdb-vector",
+  path: ":memory:", // or './vectors.duckdb' for file persistence
+});
+
+// Create an index
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+  metric: "cosine",
+});
+
+// Add vectors with metadata
+const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
+const metadata = [
+  { text: "first document", category: "A" },
+  { text: "second document", category: "B" },
+];
+await store.upsert({
+  indexName: "myCollection",
+  vectors,
+  metadata,
+});
+
+// Query similar vectors
+const queryVector = [0.1, 0.2, ...];
+const results = await store.query({
+  indexName: "myCollection",
+  queryVector,
+  topK: 10,
+  filter: { category: "A" },
+});
+
+// Clean up
+await store.close();
+```
+
+## Constructor Options
+
+**id:** (`string`): Unique identifier for the vector store instance
+
+**path?:** (`string`): Database file path. Use ':memory:' for in-memory database, or a file path like './vectors.duckdb' for persistence. (Default: `':memory:'`)
+
+**dimensions?:** (`number`): Default dimension for vector embeddings (Default: `1536`)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Default distance metric for similarity search (Default: `cosine`)
+
+## Methods
+
+### createIndex()
+
+Creates a new vector collection with optional HNSW index for fast approximate nearest neighbor search.
+
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension size (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+### upsert()
+
+Adds or updates vectors and their metadata in the index.
+
+**indexName:** (`string`): Name of the index to insert into
+
+**vectors:** (`number[][]`): Array of embedding vectors
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated UUIDs if not provided)
+
+### query()
+
+Searches for similar vectors with optional metadata filtering.
+
+**indexName:** (`string`): Name of the index to search in
+
+**queryVector:** (`number[]`): Query vector to find similar vectors for
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Filter`): Metadata filters using MongoDB-like query syntax
+
+**includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)
+
+### describeIndex()
+
+Gets information about an index.
+
+**indexName:** (`string`): Name of the index to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### deleteIndex()
+
+Deletes an index and all its data.
+
+**indexName:** (`string`): Name of the index to delete
+
+### listIndexes()
+
+Lists all vector indexes in the database.
+
+Returns: `Promise<string[]>`
+
+### 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 entry to update (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**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 entry from an index by its ID.
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): ID of the vector entry 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)
+
+### close()
+
+Closes the database connection and releases resources.
+
+```typescript
+await store.close()
+```
+
+## 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
+}
+```
+
+## Filter Operators
+
+DuckDB vector store supports MongoDB-like filter operators:
+
+| Category   | Operators                                  |
+| ---------- | ------------------------------------------ |
+| Comparison | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
+| Logical    | `$and`, `$or`, `$not`, `$nor`              |
+| Array      | `$in`, `$nin`                              |
+| Element    | `$exists`                                  |
+| Text       | `$contains`                                |
+
+### Filter Examples
+
+```typescript
+// Allegato operators
+const results = await store.query({
+  indexName: "docs",
+  queryVector: [...],
+  filter: {
+    $and: [
+      { category: "electronics" },
+      { price: { $gte: 100, $lte: 500 } },
+    ],
+  },
+});
+
+// Nested field access
+const results = await store.query({
+  indexName: "docs",
+  queryVector: [...],
+  filter: { "user.profile.tier": "premium" },
+});
+```
+
+## Distance Metrics
+
+| Metric       | Description       | Score Interpretation   | Best For                            |
+| ------------ | ----------------- | ---------------------- | ----------------------------------- |
+| `cosine`     | Cosine similarity | 0-1 (1 = most similar) | Text embeddings, normalized vectors |
+| `euclidean`  | L2 distance       | 0-∞ (0 = most similar) | Image embeddings, spatial data      |
+| `dotproduct` | Inner product     | Higher = more similar  | When vector magnitude matters       |
+
+## Error Handling
+
+The store throws specific errors for different failure cases:
+
+```typescript
+try {
+  await store.query({
+    indexName: 'my-collection',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  if (error.message.includes('not found')) {
+    console.error('The specified index does not exist')
+  } else if (error.message.includes('Invalid identifier')) {
+    console.error('Index name contains invalid characters')
+  } else {
+    console.error('Vector store error:', error.message)
+  }
+}
+```
+
+Common error cases include:
+
+- Invalid index name format
+- Index/table not found
+- Dimension mismatch between query vector and index
+- Empty filter or ids array in delete/update operations
+- Mutual exclusivity violations (providing both `id` and `filter`)
+
+## Use Cases
+
+### Embedded Semantic Search
+
+Build offline-capable AI applications with semantic search that runs entirely in-process:
+
+```typescript
+const store = new DuckDBVector({
+  id: 'offline-search',
+  path: './search.duckdb',
+})
+```
+
+### Local RAG Pipelines
+
+Process sensitive documents locally without sending data to cloud vector databases:
+
+```typescript
+const store = new DuckDBVector({
+  id: 'private-rag',
+  path: './confidential.duckdb',
+  dimensions: 1536,
+})
+```
+
+### Development and Testing
+
+Rapidly prototype vector search features with zero infrastructure:
+
+```typescript
+const store = new DuckDBVector({
+  id: 'dev-store',
+  path: ':memory:', // Fast in-memory for tests
+})
+```
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [DuckDB Documentation](https://duckdb.org/docs/)