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

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

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

@@ -1,318 +0,0 @@
-# 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/)