@mastra/mcp-docs-server 1.2.18-alpha.3 → 1.2.18-alpha.6

package/.docs/reference/index.md

@@ -68,6 +68,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [mastra](https://mastra.ai/reference/cli/mastra)
 - [Agents API](https://mastra.ai/reference/client-js/agents)
 - [Conversations API](https://mastra.ai/reference/client-js/conversations)
+- [Datasets API](https://mastra.ai/reference/client-js/datasets)
 - [Error Handling](https://mastra.ai/reference/client-js/error-handling)
 - [Logs API](https://mastra.ai/reference/client-js/logs)
 - [Mastra Client SDK](https://mastra.ai/reference/client-js/mastra-client)
@@ -166,10 +167,12 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.addItems()](https://mastra.ai/reference/datasets/addItems)
 - [.compareExperiments()](https://mastra.ai/reference/datasets/compareExperiments)
 - [.create()](https://mastra.ai/reference/datasets/create)
+- [.createExperiment()](https://mastra.ai/reference/datasets/createExperiment)
 - [.delete()](https://mastra.ai/reference/datasets/delete)
 - [.deleteExperiment()](https://mastra.ai/reference/datasets/deleteExperiment)
 - [.deleteItem()](https://mastra.ai/reference/datasets/deleteItem)
 - [.deleteItems()](https://mastra.ai/reference/datasets/deleteItems)
+- [.finalizeExperiment()](https://mastra.ai/reference/datasets/finalizeExperiment)
 - [.get()](https://mastra.ai/reference/datasets/get)
 - [.getDetails()](https://mastra.ai/reference/datasets/getDetails)
 - [.getExperiment()](https://mastra.ai/reference/datasets/getExperiment)
@@ -180,8 +183,10 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listExperiments()](https://mastra.ai/reference/datasets/listExperiments)
 - [.listItems()](https://mastra.ai/reference/datasets/listItems)
 - [.listVersions()](https://mastra.ai/reference/datasets/listVersions)
+- [.runExperimentItem()](https://mastra.ai/reference/datasets/runExperimentItem)
 - [.startExperiment()](https://mastra.ai/reference/datasets/startExperiment)
 - [.startExperimentAsync()](https://mastra.ai/reference/datasets/startExperimentAsync)
+- [.submitExperimentResult()](https://mastra.ai/reference/datasets/submitExperimentResult)
 - [.update()](https://mastra.ai/reference/datasets/update)
 - [.updateItem()](https://mastra.ai/reference/datasets/updateItem)
 - [config.ts](https://mastra.ai/reference/file-based-agents/config)

package/.docs/reference/observability/tracing/exporters/langfuse.md

@@ -17,6 +17,7 @@ interface LangfuseExporterConfig extends BaseExporterConfig {
   publicKey?: string
   secretKey?: string
   baseUrl?: string
+  additionalHeaders?: Record<string, string>
   realtime?: boolean
   flushAt?: number
   flushInterval?: number
@@ -78,6 +79,7 @@ const exporter = new LangfuseExporter({
   publicKey: process.env.LANGFUSE_PUBLIC_KEY,
   secretKey: process.env.LANGFUSE_SECRET_KEY,
   baseUrl: 'https://cloud.langfuse.com',
+  additionalHeaders: { 'x-custom-header': 'custom-value' },
   realtime: true,
 })
 ```

package/.docs/reference/pubsub/redis-streams.md

@@ -135,4 +135,14 @@ When a subscriber calls `nack`, the event is republished with an incremented `de
 
 Lease keys are namespaced under the same `keyPrefix` as topics, as `<keyPrefix>:lease:<key>`. All operations are atomic: `acquireLease` uses `SET NX PX` and refreshes its own TTL idempotently, while `releaseLease`, `renewLease`, and `transferLease` use Lua scripts that check ownership before mutating, so a concurrent renewal from another owner is never clobbered.
 
-You don't call these methods directly. Configuring `RedisStreamsPubSub` as the `pubsub` backend is enough for the runtime to detect and use the capability. See [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) for the full method contract.
+You don't call these methods directly. Configuring `RedisStreamsPubSub` as the `pubsub` backend is enough for the runtime to detect and use the capability. See [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) for the full method contract.
+
+## Managed provisioning
+
+When you deploy a project that reads `REDIS_URL` from the environment, the Mastra CLI's `deploy` preflight offers to attach a managed Redis on the Mastra platform in one step.
+
+If you accept, `mastra deploy` provisions the database and waits for it to reach the ready state before injecting `REDIS_URL` into the deploy so `new RedisStreamsPubSub({ url: process.env.REDIS_URL })` connects without extra setup.
+
+The prompt is shown only when three conditions hold: `REDIS_URL` is referenced by user code, the environment's value is missing or points to a localhost address, and the run is interactive (a terminal without the `--yes` flag). Non-interactive runs (CI, `--yes`) report the issue with a copy-pasteable `mastra env db create --kind redis` command instead of silently creating infrastructure.
+
+You can also provision a managed Redis up front with `mastra env db create --kind redis`. Once attached, the platform meters CPU seconds and memory GB-hours and shows them on the project's Database Usage page.

package/.docs/reference/rag/metadata-filters.md

@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: { $gt: 2 } } } — MongoDB requires an integer instead: { tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
 ## Common rules and restrictions
 
@@ -186,13 +186,21 @@ const results = await store.query({
 
 ### MongoDB
 
-- Full support for MongoDB/Sift query syntax for metadata filters
-- Supports all standard comparison, array, logical, and element operators
-- Supports nested fields and arrays in metadata
-- Filtering can be applied to both `metadata` and the original document content using the `filter` and `documentFilter` options, respectively
-- `filter` applies to the metadata object; `documentFilter` applies to the original document fields
-- No artificial limits on filter size or complexity (subject to MongoDB query limits)
-- Indexing metadata fields is recommended for optimal performance
+- Requires MongoDB Atlas or a deployment with MongoDB Vector Search enabled. The store queries with the `$vectorSearch` aggregation stage.
+- Uses MongoDB query syntax directly for metadata filters, including nested fields and arrays in metadata.
+- Supports the comparison, array, logical, and element operators in the tables above, plus `$regex` and `$size`. `$size` takes an integer, as in `{ tags: { $size: 3 } }`.
+- Use `filter` to match fields in the metadata object and `documentFilter` to match the original document text. You can combine them in a single query.
+- Declare the metadata fields you filter on in `filterFields` when you create the index. Mastra passes filters that use only declared fields and the operators MongoDB Vector Search accepts (`$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`) directly to `$vectorSearch`:
+
+```typescript
+await store.createIndex({
+  indexName: 'my_index',
+  dimension: 1536,
+  filterFields: ['category', 'price'],
+})
+```
+
+- Filters that reference an undeclared field or use another operator take a fallback path: Mastra pre-filters the collection and passes the matching document IDs to `$vectorSearch`. This works only while the ID set fits within MongoDB's 16 MB BSON document limit. On large collections the query fails once that limit is exceeded, so declare your filter fields for selective queries over large data sets.
 
 ### Couchbase
 

package/.docs/reference/rag/retrieval.md

@@ -77,9 +77,19 @@ For detailed information about available operators and syntax, see the [Metadata
 
 Basic filtering examples:
 
+**MongoDB**:
+
 ```ts
+import { MongoDBVector } from '@mastra/mongodb'
+
+const mongoVector = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
 // Simple equality filter
-const results = await pgVector.query({
+const equalityResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -89,7 +99,7 @@ const results = await pgVector.query({
 })
 
 // Numeric comparison
-const results = await pgVector.query({
+const priceResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -99,7 +109,7 @@ const results = await pgVector.query({
 })
 
 // Multiple conditions
-const results = await pgVector.query({
+const compoundResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -111,7 +121,7 @@ const results = await pgVector.query({
 })
 
 // Array operations
-const results = await pgVector.query({
+const tagResults = await mongoVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -121,7 +131,64 @@ const results = await pgVector.query({
 })
 
 // Logical operators
-const results = await pgVector.query({
+const categoryResults = await mongoVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    $or: [{ category: 'electronics' }, { category: 'accessories' }],
+    $and: [{ price: { $gt: 50 } }, { price: { $lt: 200 } }],
+  },
+})
+```
+
+**pgVector**:
+
+```ts
+// Simple equality filter
+const equalityResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    source: 'article1.txt',
+  },
+})
+
+// Numeric comparison
+const priceResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    price: { $gt: 100 },
+  },
+})
+
+// Multiple conditions
+const compoundResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    category: 'electronics',
+    price: { $lt: 1000 },
+    inStock: true,
+  },
+})
+
+// Array operations
+const tagResults = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    tags: { $in: ['sale', 'new'] },
+  },
+})
+
+// Logical operators
+const categoryResults = await pgVector.query({
   indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
@@ -141,6 +208,47 @@ Common use cases for metadata filtering:
 - Combine multiple conditions for precise querying
 - Filter by document attributes (e.g., language, author)
 
+### Where the filter is applied
+
+Vector stores differ in _when_ they apply a metadata filter, which affects how filtered queries scale.
+
+MongoDB can evaluate the filter inside the vector index itself. This keeps the query on a single round trip to `$vectorSearch`, so it avoids the pre-filter pass that collects matching document IDs and the 16 MB BSON limit that pass is subject to. Declaring the fields you filter on in `filterFields` when you create the index is what enables it:
+
+```ts
+// Declare the metadata fields you want to filter on
+await mongoVector.createIndex({
+  indexName: 'embeddings',
+  dimension: 1536,
+  filterFields: ['source', 'price', 'category', 'inStock', 'tags'],
+})
+
+// createIndex() returns before the index finishes building
+await mongoVector.waitForIndexReady({ indexName: 'embeddings' })
+
+// The filter is applied during the index search
+const results = await mongoVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: { source: 'article1.txt' },
+})
+```
+
+Mastra passes the filter to the index only when every field it references is declared in `filterFields` and every operator is one the index accepts: `$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, and `$nin`. A filter that uses an undeclared field or any other operator takes a fallback path: Mastra matches the collection first and passes the matching document IDs into the vector search. That fallback holds only while the ID set fits within MongoDB's 16 MB BSON document limit. On large collections the query fails once that limit is exceeded, so declare your filter fields when you expect selective filters over large data sets.
+
+pgVector applies the filter as an ordinary query condition:
+
+```ts
+const results = await pgVector.query({
+  indexName: 'embeddings',
+  queryVector: embedding,
+  topK: 10,
+  filter: { source: 'article1.txt' },
+})
+```
+
+Postgres vector indexes (HNSW and IVFFlat) can't restrict that search to rows matching a condition. When a filter is present, pgVector instead compares the query vector against every matching row and returns the closest `topK`. Results are exact, but the work grows with the number of rows the filter matches. Indexing the metadata column speeds up row retrieval. The distance comparisons still happen per row.
+
 ### Vector Query Tool
 
 Sometimes you want to give your agent the ability to query a vector database directly. The Vector Query Tool allows your agent to be in charge of retrieval decisions, combining semantic search with optional filtering and reranking based on the agent's understanding of the user's needs.

package/.docs/reference/server/routes.md

@@ -368,6 +368,117 @@ On authenticated servers, the read routes require the `stored-workflows:read` pe
 }
 ```
 
+## Datasets and experiments
+
+| Method   | Path                                                                   | Description                                                               |
+| -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `GET`    | `/api/datasets`                                                        | List datasets                                                             |
+| `POST`   | `/api/datasets`                                                        | Create a dataset                                                          |
+| `GET`    | `/api/datasets/:datasetId`                                             | Get dataset by ID                                                         |
+| `PATCH`  | `/api/datasets/:datasetId`                                             | Update a dataset                                                          |
+| `DELETE` | `/api/datasets/:datasetId`                                             | Delete a dataset                                                          |
+| `GET`    | `/api/datasets/:datasetId/items`                                       | List dataset items                                                        |
+| `POST`   | `/api/datasets/:datasetId/items`                                       | Add a dataset item                                                        |
+| `GET`    | `/api/experiments`                                                     | List experiments across datasets                                          |
+| `GET`    | `/api/datasets/:datasetId/experiments`                                 | List experiments for a dataset                                            |
+| `POST`   | `/api/datasets/:datasetId/experiments`                                 | Trigger an experiment, or create one without starting it (`start: false`) |
+| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/items/:itemId/run` | Execute one experiment item server-side                                   |
+| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/results`           | Submit an externally computed item result                                 |
+| `POST`   | `/api/datasets/:datasetId/experiments/:experimentId/finalize`          | Finalize a caller-driven experiment                                       |
+| `GET`    | `/api/datasets/:datasetId/experiments/:experimentId`                   | Get experiment by ID                                                      |
+| `GET`    | `/api/datasets/:datasetId/experiments/:experimentId/results`           | List experiment results                                                   |
+| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two experiments                                                   |
+
+### Caller-driven experiment routes
+
+Use these routes when your own orchestrator (for example a Temporal workflow) owns the experiment loop and Mastra acts as the system of record. Item runs, result submission, and finalization are safe to retry. Creation is safe to retry only when the request includes a caller-supplied `id`; without one, each retry creates a new experiment. Item runs and result submissions upsert on `(experimentId, itemId, attempt)`. Finalize returns the stored record if the experiment is already completed.
+
+#### Create experiment request body
+
+Post to `/api/datasets/:datasetId/experiments` with `start: false` to create the experiment without running it. Include `targetType` and `targetId` when Mastra should execute items via the run-item route. Omit both for pure ingestion via the results route.
+
+```typescript
+{
+  start?: boolean;              // false creates the experiment without running it. Defaults to true.
+  id?: string;                  // Caller-supplied experiment id (e.g. a workflow run id) for idempotent creates
+  targetType?: 'agent' | 'workflow' | 'scorer'; // Provide with targetId, or omit both
+  targetId?: string;
+  scorerIds?: string[];         // Run-level scorer ids, resolved server-side. Requires a target when start is false.
+  name?: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+  version?: number;             // Pin to a specific dataset version (defaults to latest)
+  provenance?: {
+    source?: string;
+    sourceId?: string;
+    sourceVersion?: string;
+    metadata?: Record<string, unknown>;
+  };
+  grouping?: {                  // Stable grouping dimensions for comparisons and repeated trials
+    experimentSetId?: string;
+    comparisonId?: string;
+    variantId?: string;
+    trialIndex?: number;
+  };
+}
+```
+
+Returns `{ experimentId, status, totalItems, datasetVersion }` when `start` is `false`.
+
+#### Run experiment item request body
+
+`POST /api/datasets/:datasetId/experiments/:experimentId/items/:itemId/run` executes the experiment's target against one item and runs the resolved scorers, then upserts the result. Requires an experiment created with a target.
+
+```typescript
+{
+  attempt?: number;             // Zero-based repetition index. Defaults to 0.
+  requestContext?: Record<string, unknown>; // Merged with the item's own request context (item wins)
+}
+```
+
+Returns `{ result, scores }` with the persisted result row and the scores produced for the item.
+
+#### Submit experiment result request body
+
+```typescript
+{
+  itemId: string;               // Dataset item this result belongs to
+  attempt?: number;             // Zero-based repetition index. Defaults to 0.
+  input?: unknown;              // Defaults to the dataset item input
+  output?: unknown;             // Output produced by the external runner
+  groundTruth?: unknown;        // Defaults to the dataset item groundTruth
+  error?: {                     // Failure info when the item run failed
+    message: string;
+    stack?: string;
+    code?: string;
+  } | null;
+  startedAt?: string;           // ISO date
+  completedAt?: string;         // ISO date
+  traceId?: string;
+  scores?: Array<{              // Externally computed scores, persisted keyed by runId = experimentId
+    scorerId: string;
+    scorerName?: string;
+    score: number;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+```
+
+Returns the persisted experiment result row.
+
+#### Finalize experiment
+
+`POST /api/datasets/:datasetId/experiments/:experimentId/finalize` takes no body. The server computes per-item counts from the persisted result rows and marks the experiment `completed`: `succeededCount` (at least one attempt without an error), `failedCount` (every attempt errored), and `skippedCount` (never submitted). Returns the updated experiment record.
+
+#### Caller-driven experiment error responses
+
+| Status | Condition                                                                                                                                                                                                                                                                                                                  |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400`  | Result submitted to an experiment that has a target (`EXPERIMENT_HAS_TARGET`), item run requested on a target-less experiment (`EXPERIMENT_HAS_NO_TARGET`), `targetType` and `targetId` weren't provided together (`EXPERIMENT_INVALID_TARGET`), or the dataset has no items at the pinned version (`EXPERIMENT_NO_ITEMS`) |
+| `404`  | Dataset, experiment, dataset item, or target not found (`EXPERIMENT_TARGET_NOT_FOUND`)                                                                                                                                                                                                                                     |
+| `409`  | Caller-supplied experiment `id` already exists for a different dataset or target (`EXPERIMENT_ID_CONFLICT`), or a call arrived after finalization (`EXPERIMENT_ALREADY_FINALIZED`)                                                                                                                                         |
+
 ## MCP
 
 | Method | Path                               | Description        |

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.18-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [[`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`acc3471`](https://github.com/mastra-ai/mastra/commit/acc3471de5f3fde8027ee4e355af292b2bc1bc30), [`b6a771e`](https://github.com/mastra-ai/mastra/commit/b6a771ef23d203ddb348efca8065eff65def8191), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`26d4016`](https://github.com/mastra-ai/mastra/commit/26d40160ff7f7d8bf95fee2039a52cbc83863533), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`9267e9b`](https://github.com/mastra-ai/mastra/commit/9267e9b3d9c2fcf16936050495a787054c2431ab), [`57c5103`](https://github.com/mastra-ai/mastra/commit/57c51035a2a36e3df3c4f32f46bb789a66ed5946)]:
+  - @mastra/core@1.61.0-alpha.3
+
+## 1.2.18-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`480e491`](https://github.com/mastra-ai/mastra/commit/480e491588bd6a7a1c9ee4407590ad625dd33952), [`3bb88dd`](https://github.com/mastra-ai/mastra/commit/3bb88ddf07fb98f3cd16d3bff94e51cd3b45d011), [`d378d75`](https://github.com/mastra-ai/mastra/commit/d378d7511f71309ed61a8f6b93cd0361dc6cb70f), [`cad4208`](https://github.com/mastra-ai/mastra/commit/cad42082e6aa1776168a94914f523334be45d929), [`d378d75`](https://github.com/mastra-ai/mastra/commit/d378d7511f71309ed61a8f6b93cd0361dc6cb70f)]:
+  - @mastra/core@1.61.0-alpha.2
+
 ## 1.2.18-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.18-alpha.3",
+  "version": "1.2.18-alpha.6",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.61.0-alpha.1",
+    "@mastra/core": "1.61.0-alpha.3",
     "@mastra/mcp": "^1.17.1-alpha.0"
   },
   "devDependencies": {
@@ -47,7 +47,7 @@
     "vitest": "4.1.10",
     "@internal/lint": "0.0.124",
     "@internal/types-builder": "0.0.99",
-    "@mastra/core": "1.61.0-alpha.1"
+    "@mastra/core": "1.61.0-alpha.3"
   },
   "homepage": "https://mastra.ai",
   "repository": {