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

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/server/nestjs-adapter.md

@@ -87,7 +87,7 @@ By default, Mastra routes mount under `/api`. Use `prefix` to change it.
 
 **contextOptions** (`{ strict?: boolean; logWarnings?: boolean }`): Request context parsing config
 
-**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH.
+**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH. Custom routes from server.apiRoutes (registerApiRoute()) are added automatically based on their requiresAuth setting.
 
 **tools** (`Record<string, Tool>`): Registered tools for the server
 
@@ -95,7 +95,7 @@ By default, Mastra routes mount under `/api`. Use `prefix` to change it.
 
 **mcpOptions** (`{ serverless?: boolean; sessionIdGenerator?: () => string }`): MCP transport options
 
-**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Enable Mastra token auth. Disabled by default — most NestJS apps use their own auth guards. Query-string apiKey auth is opt-in for backward compatibility. (Default: `` `{ enabled: false }` ``)
+**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Controls Mastra auth for Mastra routes. When server.auth is configured on your Mastra instance, it runs automatically (the same pipeline as other adapters: bearer tokens, cookie sessions, session refresh, and mapUserToResourceId). Set enabled: false to rely only on your own NestJS guards. Query-string apiKey auth is opt-in for backward compatibility.
 
 ## Async registration
 

package/.docs/reference/streaming/agents/stream.md

@@ -190,6 +190,8 @@ const stream = await agent.stream('message for agent')
 
 **options.toolCallConcurrency** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
 
+**options.eagerToolExecution** (`boolean`): Defaults to true. A tool call whose arguments have finished streaming starts executing immediately, instead of waiting for the model to finish the whole step. Set it to false to restore the previous scheduling. Tool results and message history keep their model-call order either way. Only server-side tools are started early: approval-gated, suspend-schema-declaring, provider-executed, client-side, background-dispatched (by argument or by backgroundTasks config), missing and inactive tools are left to the post-stream pass, as is any run using autoResumeSuspendedTools or an output processor that runs after the stream completes. That last case is wider than it sounds: a processor workflow you build yourself counts whatever it contains, because its contents are not inspected, and so does structuredOutput when given an explicit model. A processor implementing processToolResult is excluded too when a provider-executed tool is configured: that hook runs inside the stream when a provider result arrives there, and its abort bails the turn before the post-stream pass, so starting a tool early would change whether it runs, not just when. Without a provider tool, the hook only sees results after the pass and early dispatch stays on. Also left to the post-stream pass is any run using toolCallConcurrency.strategy: 'called' (the full set of called tools is not known until the step finishes). Eager executions honour the same toolCallConcurrency limit (they are counted separately from the post-stream pass, so the limit constrains each rather than being pooled across both) and aborting the run waits for work already running, then keeps its result, as the post-stream pass does. A tool that already ran is never run again, and its finished result is never thrown away. If the last model fails mid-stream with no retry, its calls still run through the post-stream pass, which adopts eager work instead of restarting it. If the attempt is retried or failed over, tools still running are allowed to finish, and every started call's result or error is written into the conversation before the replacement attempt begins, even if the retry never runs. A tool that calls suspend() at runtime without declaring a suspend schema cannot be detected in advance; the early attempt hands its suspension back to that call's own post-stream iteration, which raises the real suspension with the tool's own payload, so the tool body runs exactly once — the same as it would without early execution. Because that pre-suspend work already happened, an attempt holding such a call is never retried or failed over: the run suspends on that call instead, so resuming it is the only way the tool runs again. Not supported by durable agents, which reject an explicit true.
+
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Additional provider-specific options that are passed through to the underlying LLM provider. The structure is { providerName: { optionKey: value } }. For example: { openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }.
 
 **options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI-specific options. Example: { reasoningEffort: 'high' }

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