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

package/.docs/reference/vectors/mongodb.md

@@ -0,0 +1,295 @@
+# MongoDB Vector Store
+
+The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/mongodb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mongodb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mongodb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mongodb@latest
+```
+
+## Usage Example
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+})
+```
+
+### Custom Embedding Field Path
+
+If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the `embeddingFieldPath` option:
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
+})
+```
+
+## Constructor Options
+
+**id:** (`string`): Unique identifier for this vector store instance
+
+**uri:** (`string`): MongoDB connection string
+
+**dbName:** (`string`): Name of the MongoDB database to use
+
+**options?:** (`MongoClientOptions`): Optional MongoDB client options
+
+**embeddingFieldPath?:** (`string`): Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding'). (Default: `embedding`)
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index (collection) in MongoDB.
+
+**indexName:** (`string`): Name of the collection 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.
+
+**indexName:** (`string`): Name of the collection 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 with optional metadata filtering.
+
+**indexName:** (`string`): Name of the collection 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 (applies to the \`metadata\` field)
+
+**documentFilter?:** (`Record<string, any>`): Filters on original document fields (not just metadata)
+
+**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 (collection).
+
+**indexName:** (`string`): Name of the collection to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### deleteIndex()
+
+Deletes a collection and all its data.
+
+**indexName:** (`string`): Name of the collection to delete
+
+### listIndexes()
+
+Lists all vector collections in the MongoDB 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 collection 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 collection 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 collection 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)
+
+### disconnect()
+
+Closes the MongoDB 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_collection',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes('Invalid collection name')) {
+    console.error(
+      'Collection name must start with a letter or underscore and contain only valid characters.',
+    )
+  } else if (error.message.includes('Collection not found')) {
+    console.error('The specified collection does not exist')
+  } else {
+    console.error('Vector store error:', error.message)
+  }
+}
+```
+
+## Best Practices
+
+- Index metadata fields used in filters for optimal query performance.
+- Use consistent field naming in metadata to avoid unexpected query results.
+- Regularly monitor index and collection statistics to ensure efficient search.
+
+## Usage Example
+
+### Vector embeddings with MongoDB
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
+
+> **Note:** You must use a deployment hosted on MongoDB Atlas to successfully use the MongoDB Vector database.
+
+This setup uses FastEmbed, a local embedding model, to generate vector embeddings. To use this, install `@mastra/fastembed`:
+
+**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 { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+import { fastembed } from '@mastra/fastembed'
+
+export const mongodbAgent = new Agent({
+  id: 'mongodb-agent',
+  name: 'mongodb-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 MongoDBStore({
+      id: 'mongodb-storage',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    vector: new MongoDBVector({
+      id: 'mongodb-vector',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      generateTitle: true, // generates descriptive thread titles automatically
+    },
+  }),
+})
+```
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/vectors/opensearch.md

@@ -0,0 +1,99 @@
+# OpenSearch Vector Store
+
+The OpenSearchVector class provides vector search using [OpenSearch](https://opensearch.org/), an open-source search and analytics engine. It uses OpenSearch's k-NN capabilities to perform vector similarity search.
+
+## Constructor Options
+
+The constructor accepts all [OpenSearch ClientOptions](https://opensearch.org/docs/latest/clients/javascript/index/) plus a required `id` field.
+
+**id:** (`string`): Unique identifier for this vector store instance
+
+**node:** (`string | string[] | NodeOptions | NodeOptions[]`): OpenSearch node URL(s) (e.g., 'http\://localhost:9200')
+
+**auth?:** (`BasicAuth | BearerAuth | AwsSigv4Auth`): Authentication configuration
+
+**ssl?:** (`ConnectionOptions`): SSL/TLS configuration
+
+**compression?:** (`'gzip'`): Enable gzip compression
+
+## Methods
+
+### createIndex()
+
+Creates a new index with the specified configuration.
+
+**indexName:** (`string`): The name of the index to create
+
+**dimension:** (`number`): The dimension of the vectors to be stored in the index
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): The distance metric to use for vector similarity (Default: `'cosine'`)
+
+### listIndexes()
+
+Lists all indexes in the OpenSearch instance.
+
+Returns: `Promise<string[]>`
+
+### describeIndex()
+
+Gets information about an index.
+
+**indexName:** (`string`): The name of the index to describe
+
+### deleteIndex()
+
+**indexName:** (`string`): The name of the index to delete
+
+### upsert()
+
+**indexName:** (`string`): The name of the index to upsert vectors into
+
+**vectors:** (`number[][]`): Array of vector embeddings to insert
+
+**metadata?:** (`Record<string, any>[]`): Array of metadata objects corresponding to each vector
+
+**ids?:** (`string[]`): Optional array of IDs for the vectors. If not provided, random IDs will be generated
+
+### query()
+
+**indexName:** (`string`): The name of the index to query
+
+**queryVector:** (`number[]`): The query vector to find similar vectors for
+
+**topK?:** (`number`): The number of results to return (Default: `10`)
+
+**filter?:** (`VectorFilter`): Optional filter to apply to the query (MongoDB-style query syntax)
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): The name of the index to update vectors in
+
+**id?:** (`string`): The 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()
+
+Deletes a single vector by its ID from the index.
+
+**indexName:** (`string`): The name of the index to delete the vector from
+
+**id:** (`string`): The 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)
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)