@mastra/mcp-docs-server 1.3.0-alpha.6 → 1.3.1-alpha.1

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -11,7 +11,7 @@ Enables bidirectional integration between Mastra tracing and OpenTelemetry infra
 ## Constructor
 
 ```typescript
-new OtelBridge()
+new OtelBridge(config?: OtelBridgeConfig)
 ```
 
 ## Methods
@@ -118,9 +118,18 @@ const mastra = new Mastra({
 })
 ```
 
-## `OpenTelemetry` setup requirements
+## Setup requirements
 
-The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
+The bridge creates spans through an OpenTelemetry tracer provider. For Mastra spans to be exported:
+
+- **A tracer provider must be available.** Register one globally before Mastra runs, for example by calling `sdk.start()` on `NodeSDK` from `@opentelemetry/sdk-node`, or by calling `trace.setGlobalTracerProvider(provider)`. If the provider isn't registered globally, pass it with `new OtelBridge({ tracerProvider })`.
+- **A context manager must be installed for Mastra spans to nest under outer spans.** `NodeSDK` installs one automatically. Without a context manager, spans are still exported, but Mastra root spans can't read the active span, so they start new traces instead of joining the outer trace.
+
+When no tracer provider is available, agents and workflows still run, but no Mastra spans are exported through OpenTelemetry. The bridge logs this warning once:
+
+```text
+[OtelBridge] No OpenTelemetry tracer provider is registered globally, so Mastra spans will not be exported through OpenTelemetry. ...
+```
 
 See the [OtelBridge Guide](https://mastra.ai/integrations/observability/opentelemetry) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
 

package/.docs/reference/rag/vector-databases.md

@@ -54,6 +54,29 @@ const results = await store.hybridQuery({
 
 See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
 
+### Automated Embedding
+
+MongoDB can generate the embeddings itself, so you don't need an embedding provider in your application. Create the index with `autoEmbed` and a Voyage AI model, write plain text, and search with a query string:
+
+```ts
+await store.createIndex({
+  indexName: 'myCollection',
+  autoEmbed: { model: 'voyage-4' },
+})
+await store.upsert({
+  indexName: 'myCollection',
+  documents: chunks.map(chunk => chunk.text),
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+const results = await store.query({
+  indexName: 'myCollection',
+  queryText: 'search terms',
+  topK: 10,
+})
+```
+
+Automated Embedding is a MongoDB Preview feature and needs a deployment where it's available. See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for the supported options and requirements.
+
 **PgVector**:
 
 ```ts

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

@@ -87,7 +87,9 @@ 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)
+**dimension** (`number`): Vector dimension (must match your embedding model). Required unless autoEmbed is set, where the embedding model determines the dimension. Passing both is an error.
+
+**autoEmbed** (`MongoDBAutoEmbedConfig`): Generate the embeddings in MongoDB instead of supplying vectors. See Automated Embedding for the supported fields.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
@@ -115,13 +117,13 @@ Adds or updates vectors and their metadata in the collection. On a bring-your-ow
 
 **indexName** (`string`): Name of the collection to insert into
 
-**vectors** (`number[][]`): Array of embedding vectors
+**vectors** (`number[][]`): Array of embedding vectors. Required unless the index was created with autoEmbed, where MongoDB generates them from documents and supplying vectors is an error.
 
 **metadata** (`Record<string, any>[]`): Metadata for each vector
 
 **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
 
-**documents** (`string[]`): Optional document text content to store alongside vectors
+**documents** (`string[]`): Document text content to store alongside vectors. On an autoEmbed index this is the text MongoDB embeds, and it is required.
 
 ### `query()`
 
@@ -129,7 +131,11 @@ 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
+**queryVector** (`number[]`): Query vector to find similar vectors for. Supply this or queryText, not both.
+
+**queryText** (`string`): Text for MongoDB to embed at query time. autoEmbed indexes only, and mutually exclusive with queryVector. For full-text matching use textQuery() instead.
+
+**model** (`string`): Embedding model for this query, overriding the index's. Requires queryText, and must be compatible with the index's model.
 
 **topK** (`number`): Number of results to return (Default: `10`)
 
@@ -226,7 +232,11 @@ Runs a hybrid search that fuses vector similarity with full-text results through
 
 **indexName** (`string`): Name of the Mastra index to search
 
-**queryVector** (`number[]`): Query vector for similarity search
+**queryVector** (`number[]`): Query vector for the vector branch. Supply this or queryText, not both.
+
+**queryText** (`string`): Text for MongoDB to embed for the vector branch. autoEmbed indexes only. Independent of query, so each branch can search for something different.
+
+**model** (`string`): Embedding model for the vector branch, overriding the index's. Requires queryText.
 
 **query** (`string`): Full-text search query string
 
@@ -273,6 +283,8 @@ interface IndexStats {
 }
 ```
 
+On an `autoEmbed` index, `dimension` is read from the index definition and reports MongoDB's default of `1024` when the index doesn't pin one. `count` counts documents that carry the embedded text field, since the generated vectors aren't stored on your documents.
+
 ### `deleteIndex()`
 
 Deletes a vector index. Behavior depends on how the index was created:
@@ -367,6 +379,79 @@ try {
 }
 ```
 
+## Automated Embedding
+
+MongoDB can generate the embeddings for you. Create the index with `autoEmbed` and a Voyage AI model, write plain text through `documents`, and search with `queryText`. No embedding provider runs in your application, and no vectors travel through it.
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
+// No `dimension`: the embedding model determines it.
+await store.createIndex({
+  indexName: 'movies',
+  autoEmbed: { model: 'voyage-4' },
+  filterFields: ['year'],
+})
+
+// Automated Embedding indexes build slower than client-embedded ones.
+await store.waitForIndexReady({ indexName: 'movies', timeoutMs: 300000 })
+
+// No `vectors`: MongoDB embeds the text as documents are written.
+await store.upsert({
+  indexName: 'movies',
+  documents: [
+    'A lonely astronaut adrift near a strange ocean planet.',
+    'A heist crew robs a bank vault in Paris.',
+  ],
+  metadata: [{ year: 1972 }, { year: 2001 }],
+})
+
+// No `queryVector`: MongoDB embeds the query string with the same model.
+const results = await store.query({
+  indexName: 'movies',
+  queryText: 'space opera about isolation',
+  topK: 5,
+  filter: { year: { $gt: 1970 } },
+})
+```
+
+### `autoEmbed` options
+
+**model** (`string`): Voyage AI model to embed with, for example voyage-4. MongoDB rejects a name it does not support and lists the ones it does.
+
+**path** (`string`): Text field to embed. Defaults to the managed document field that upsert({ documents }) writes. Point it at a field of your own to index an existing collection in place. (Default: `document`)
+
+**similarity** (`'cosine' | 'dotProduct' | 'euclidean'`): Vector similarity function. Defaults to MongoDB's own default when omitted.
+
+**numDimensions** (`256 | 512 | 1024 | 2048`): Length of the generated embeddings. (Default: `1024`)
+
+**quantization** (`'float' | 'scalar' | 'binary' | 'binaryNoRescore'`): Storage format for the generated vectors. (Default: `scalar`)
+
+**indexingMethod** (`'hnsw' | 'flat'`): Index structure for the vector field. (Default: `hnsw`)
+
+**hnswOptions** (`{ maxEdges?: number; numEdgeCandidates?: number }`): Tuning for the HNSW graph. MongoDB's defaults suit most workloads.
+
+Any other field the `autoEmbed` index definition accepts is forwarded to MongoDB as given, so options added after this release work without a package update. Anything omitted keeps MongoDB's default.
+
+**Important notes:**
+
+- Automated Embedding is a **MongoDB Preview feature**. It requires an Atlas cluster with Automated Embedding available, or the `mongodb/mongodb-atlas-local:preview` image for local development. Self-managed deployments need `mongot` configured with a Voyage AI API key.
+- The Voyage AI API key must be provisioned through the Atlas UI. A key issued directly by Voyage AI is rejected by the default embedding endpoint.
+- **MongoDB stores the generated vectors outside your collection**, so documents carry text only. `includeVector: true` isn't supported on an `autoEmbed` index and throws.
+- Embeddings are generated asynchronously. A query can legitimately return no results for a short time after a write, even once the index reports ready.
+- An index declares either a vector field or an `autoEmbed` field, never both. Omit `autoEmbed` to keep supplying your own vectors. The client-side path is unchanged.
+- Passing `vectors` to an `autoEmbed` index is an error, since they would be written to a field no index reads.
+- When `document` is the embedded field it's no longer a declared filter field, so `documentFilter` uses the `$match` pre-filter automatically. Metadata filters declared through `filterFields` still push into `$vectorSearch`.
+- `updateVector()` rejects a vector update on an `autoEmbed` index. Upsert the document with new text instead, and MongoDB re-embeds it.
+- `queryVector` still works against an `autoEmbed` index, but the vector must come from a compatible model and match the index `quantization`. MongoDB rejects a mismatch.
+- Embedding generation is billed per token, for both documents and queries.
+
 ## Indexing an existing collection
 
 You can create a vector index on an existing operational collection instead of using a managed collection. This is useful when you want to add vector search capabilities to documents that already exist in your MongoDB database.

package/dist/index.js

@@ -1,2 +1,2 @@
-import { n as runServer, t as createDocsServer } from "./src-CGZ6-uLS.js";
+import { n as runServer, t as createDocsServer } from "./src-Baf8l9Sp.js";
 export { createDocsServer, runServer };

package/dist/{src-CGZ6-uLS.js → src-Baf8l9Sp.js}

@@ -992,6 +992,16 @@ const docsTool = {
 const packageCache = /* @__PURE__ */ new Map();
 const sourceMapCache = /* @__PURE__ */ new Map();
 const packageInfoCache = /* @__PURE__ */ new Map();
+const projectPathSchema = z.string().superRefine((projectPath, context) => {
+	if (projectPath.length === 0) context.addIssue({
+		code: "custom",
+		message: "Project path cannot be empty"
+	});
+	else if (!path.isAbsolute(projectPath)) context.addIssue({
+		code: "custom",
+		message: "Project path must be absolute"
+	});
+}).describe("Absolute path to your project root (we will search upward for node_modules with Mastra packages)");
 const KNOWN_MASTRA_PACKAGES = [
 	"@mastra/core",
 	"@mastra/cli",
@@ -1132,7 +1142,7 @@ const embeddedDocsTools = {
     3. Version mismatch: mastraChanges → mastraMigration
 
     This tool shows you which packages are installed and provides detailed guidance on using all available documentation tools.`,
-		parameters: z.object({ projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules with Mastra packages)") }),
+		parameters: z.object({ projectPath: projectPathSchema }),
 		execute: async (args) => {
 			logger.debug("Executing getMastraHelp tool", { projectPath: args.projectPath });
 			const packages = await getInstalledMastraPackages(args.projectPath);
@@ -1245,7 +1255,7 @@ Guided learning experience with hands-on exercises.
 
     Returns: List of @mastra/* packages (core, memory, rag, etc.) with embedded docs.
     Next step: Use getMastraExports to explore a specific package's API.`,
-		parameters: z.object({ projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules with Mastra packages)") }),
+		parameters: z.object({ projectPath: projectPathSchema }),
 		execute: async (args) => {
 			logger.debug("Executing listInstalledMastraPackages tool", {
 				projectPath: args.projectPath,
@@ -1291,7 +1301,7 @@ Install Mastra packages to get started:
     Next step: Use getMastraExportDetails to get full type definitions and code for a specific export.`,
 		parameters: z.object({
 			package: z.string().describe("Package name to explore (e.g., \"@mastra/core\", \"@mastra/memory\", \"@mastra/rag\")"),
-			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)"),
+			projectPath: projectPathSchema,
 			filter: z.string().optional().describe("Optional: filter exports by name (case-insensitive, e.g., \"Agent\", \"create\", \"Tool\")")
 		}),
 		execute: async (args) => {
@@ -1343,7 +1353,7 @@ Try running without a filter to see all available exports.` : `No exports found
 			includeTypes: z.boolean().optional().default(true).describe("Include TypeScript type definitions (recommended: true)"),
 			includeImplementation: z.boolean().optional().default(false).describe("Include source code implementation (useful for understanding internals)"),
 			implementationLines: z.number().optional().default(50).describe("Number of lines of implementation code to show (default: 50)"),
-			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)")
+			projectPath: projectPathSchema
 		}),
 		execute: async (args) => {
 			logger.debug("Executing findMastraExport tool", { args });
@@ -1414,7 +1424,7 @@ Run getMastraExports with package="${args.package}" to see all available exports
 			package: z.string().describe("Package name to read docs from (e.g., \"@mastra/core\", \"@mastra/memory\")"),
 			topic: z.string().optional().describe("Optional: topic folder to read (e.g., \"agents\", \"tools\", \"workflows\"). Omit to list all available topics."),
 			file: z.string().optional().describe("Optional: specific documentation file within the topic (e.g., \"01-overview.md\")"),
-			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)")
+			projectPath: projectPathSchema
 		}),
 		execute: async (args) => {
 			logger.debug("Executing readMastraEmbeddedDocs tool", { args });
@@ -1501,7 +1511,7 @@ Run readMastraDocs with package="${args.package}" (without topic parameter) to s
 			query: z.string().describe("What to search for (case-insensitive, e.g., \"workflow steps\", \"vector store\", \"authentication\")"),
 			package: z.string().optional().describe("Optional: limit search to a specific package (e.g., \"@mastra/core\"). Omit to search all packages."),
 			maxResults: z.number().optional().default(10).describe("Optional: maximum number of results to return (default: 10)"),
-			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)")
+			projectPath: projectPathSchema
 		}),
 		execute: async (args) => {
 			logger.debug("Executing searchMastraEmbeddedDocs tool", { args });
@@ -1846,4 +1856,4 @@ async function runServer() {
 //#endregion
 export { writeErrorLog as i, runServer as n, setLogLevel as r, createDocsServer as t };
 
-//# sourceMappingURL=src-CGZ6-uLS.js.map
+//# sourceMappingURL=src-Baf8l9Sp.js.map