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

package/.docs/reference/datasets/getItemHistory.md

@@ -0,0 +1,31 @@
+# dataset.getItemHistory()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Retrieves the full SCD-2 (Slowly Changing Dimension Type 2) history of a specific item across all dataset versions.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const history = await dataset.getItemHistory({ itemId: 'item-id' })
+
+for (const row of history) {
+  console.log(`Version ${row.datasetVersion}: ${row.isDeleted ? 'deleted' : 'active'}`)
+}
+```
+
+## Parameters
+
+**itemId:** (`string`): ID of the item to retrieve history for.
+
+## Returns
+
+**result:** (`Promise<DatasetItemRow[]>`): DatasetItemRowid:stringUnique row identifier.datasetId:stringID of the parent dataset.datasetVersion:numberDataset version for this row\.validTo:number | nullVersion at which this row was superseded, or \`null\` if still current.isDeleted:booleanWhether this row represents a deletion.input:unknownInput data at this version.groundTruth?:unknownGround truth at this version.metadata?:Record\<string, unknown>Metadata at this version.createdAt:DateWhen this row was created.updatedAt:DateWhen this row was last updated.

package/.docs/reference/datasets/list.md

@@ -0,0 +1,31 @@
+# DatasetsManager.list()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Lists all datasets with pagination.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const { datasets, pagination } = await mastra.datasets.list({ page: 0, perPage: 10 })
+
+for (const ds of datasets) {
+  console.log(`${ds.id}: ${ds.name} (v${ds.version})`)
+}
+```
+
+## Parameters
+
+**page?:** (`number`): Page number. Defaults to \`0\`.
+
+**perPage?:** (`number`): Number of datasets per page. Defaults to \`20\`.
+
+## Returns
+
+**result:** (`Promise<object>`): objectdatasets:DatasetRecord\[]Array of dataset records. See dataset.getDetails() for the record shape.pagination:PaginationInfoPagination metadata with \`total\`, \`page\`, \`perPage\`, and \`hasMore\`.

package/.docs/reference/datasets/listExperimentResults.md

@@ -0,0 +1,39 @@
+# dataset.listExperimentResults()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Lists individual item results for a specific experiment with pagination.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const { results, pagination } = await dataset.listExperimentResults({
+  experimentId: 'exp-id',
+  page: 0,
+  perPage: 50,
+})
+
+for (const result of results) {
+  console.log(`Item ${result.itemId}: ${result.error ? 'FAILED' : 'OK'}`)
+}
+```
+
+## Parameters
+
+**experimentId:** (`string`): ID of the experiment to list results for.
+
+**page?:** (`number`): Page number. Defaults to \`0\`.
+
+**perPage?:** (`number`): Number of results per page. Defaults to \`20\`.
+
+## Returns
+
+**result:** (`Promise<object>`): objectresults:ExperimentResult\[]Array of item-level results.ExperimentResultid:stringUnique result ID.experimentId:stringID of the parent experiment.itemId:stringID of the dataset item.itemDatasetVersion:number | nullDataset version of the item when executed.input:unknownInput data passed to the target.output:unknown | nullOutput from the target.groundTruth:unknown | nullExpected output.error:{ message: string; stack?: string; code?: string } | nullStructured error if execution failed.startedAt:DateWhen execution started.completedAt:DateWhen execution completed.retryCount:numberNumber of retry attempts.traceId:string | nullTrace ID for observability.createdAt:DateWhen the result record was created.pagination:PaginationInfoPagination metadata with \`total\`, \`page\`, \`perPage\`, and \`hasMore\`.

package/.docs/reference/datasets/listExperiments.md

@@ -0,0 +1,33 @@
+# dataset.listExperiments()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Lists all experiments (runs) for this dataset with pagination.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const { experiments, pagination } = await dataset.listExperiments({ page: 0, perPage: 10 })
+
+for (const exp of experiments) {
+  console.log(`${exp.id}: ${exp.status} (${exp.succeededCount}/${exp.totalItems})`)
+}
+```
+
+## Parameters
+
+**page?:** (`number`): Page number. Defaults to \`0\`.
+
+**perPage?:** (`number`): Number of experiments per page. Defaults to \`20\`.
+
+## Returns
+
+**result:** (`Promise<object>`): objectexperiments:Experiment\[]Array of experiment records.Experimentid:stringUnique experiment ID.name?:stringDisplay name.description?:stringDescription.metadata?:Record\<string, unknown>Arbitrary metadata.datasetId:stringID of the parent dataset.datasetVersion:number | nullDataset version used for the experiment.targetType:'agent' | 'workflow' | 'scorer' | 'processor'Type of target used.targetId:stringID of the target used.status:'pending' | 'running' | 'completed' | 'failed'Current status of the experiment.totalItems:numberTotal number of items.succeededCount:numberNumber of successful items.failedCount:numberNumber of failed items.skippedCount:numberNumber of skipped items.startedAt:Date | nullWhen the experiment started.completedAt:Date | nullWhen the experiment completed.createdAt:DateWhen the experiment record was created.updatedAt:DateWhen the experiment record was last updated.pagination:PaginationInfoPagination metadata with \`total\`, \`page\`, \`perPage\`, and \`hasMore\`.

package/.docs/reference/datasets/listItems.md

@@ -0,0 +1,46 @@
+# dataset.listItems()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Lists items in the dataset. When a `version` is specified, returns all items at that version. Otherwise, returns paginated items from the latest version.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Paginated list (default: page 0, 20 per page)
+const result = await dataset.listItems()
+
+// List with search
+const filtered = await dataset.listItems({ search: 'TypeScript', page: 0, perPage: 10 })
+
+// List all items at a specific version
+const versionedItems = await dataset.listItems({ version: 2 })
+```
+
+## Parameters
+
+**version?:** (`number`): Dataset version to list items at. When set, returns all items at that version (no pagination).
+
+**page?:** (`number`): Page number for pagination. Defaults to \`0\`.
+
+**perPage?:** (`number`): Number of items per page. Defaults to \`20\`.
+
+**search?:** (`string`): Search string to filter items.
+
+## Returns
+
+When `version` is specified:
+
+**result:** (`Promise<DatasetItem[]>`): Array of all items at the specified dataset version.
+
+When `version` is not specified:
+
+**result:** (`Promise<object>`): objectitems:DatasetItem\[]Array of items for the current page.pagination:objectPagination metadata.objecttotal:numberTotal number of items.page:numberCurrent page number.perPage:number | falseItems per page, or \`false\` if unpaginated.hasMore:booleanWhether more pages are available.

package/.docs/reference/datasets/listVersions.md

@@ -0,0 +1,33 @@
+# dataset.listVersions()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Lists all versions of the dataset with pagination.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const { versions, pagination } = await dataset.listVersions({ page: 0, perPage: 10 })
+
+for (const version of versions) {
+  console.log(`Version ${version.version} created at ${version.createdAt}`)
+}
+```
+
+## Parameters
+
+**page?:** (`number`): Page number. Defaults to \`0\`.
+
+**perPage?:** (`number`): Number of versions per page. Defaults to \`20\`.
+
+## Returns
+
+**result:** (`Promise<object>`): objectversions:DatasetVersion\[]Array of version records.DatasetVersionid:stringUnique identifier of the version record.datasetId:stringID of the parent dataset.version:numberVersion number.createdAt:DateWhen this version was created.pagination:objectPagination metadata.objecttotal:numberTotal number of versions.page:numberCurrent page number.perPage:number | falseVersions per page, or \`false\` if unpaginated.hasMore:booleanWhether more pages are available.

package/.docs/reference/datasets/startExperiment.md

@@ -0,0 +1,62 @@
+# dataset.startExperiment()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Runs an experiment on the dataset and waits for completion. Executes all items against a target (agent, workflow, or scorer) with optional scoring.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Run against a registered agent with scorers
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'my-agent',
+  scorers: ['accuracy', 'relevancy'],
+  maxConcurrency: 10,
+})
+
+console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
+console.log(`Status: ${summary.status}`)
+```
+
+## Parameters
+
+**targetType?:** (`'agent' | 'workflow' | 'scorer'`): Type of registered target to run items against. Use with \`targetId\`.
+
+**targetId?:** (`string`): ID of the registered target. Use with \`targetType\`.
+
+**scorers?:** (`(MastraScorer | string)[]`): Scorers to evaluate each result. Pass \`MastraScorer\` instances or registered scorer IDs.
+
+**name?:** (`string`): Display name for the experiment.
+
+**description?:** (`string`): Description of the experiment.
+
+**metadata?:** (`Record<string, unknown>`): Arbitrary metadata for the experiment.
+
+**version?:** (`number`): Pin to a specific dataset version. Defaults to the latest version.
+
+**maxConcurrency?:** (`number`): Maximum concurrent item executions. Defaults to \`5\`.
+
+**signal?:** (`AbortSignal`): AbortSignal for cancelling the experiment.
+
+**itemTimeout?:** (`number`): Per-item execution timeout in milliseconds.
+
+**maxRetries?:** (`number`): Maximum retries per item on failure. Defaults to \`0\` (no retries). Abort errors are never retried.
+
+## Returns
+
+**result:** (`Promise<ExperimentSummary>`): ExperimentSummaryexperimentId:stringUnique ID of the experiment.status:'pending' | 'running' | 'completed' | 'failed'Final status of the experiment.totalItems:numberTotal number of items in the dataset.succeededCount:numberNumber of items that succeeded.failedCount:numberNumber of items that failed.skippedCount:numberNumber of items skipped (e.g., due to abort).completedWithErrors:boolean\`true\` if the run completed but some items failed.startedAt:DateWhen the experiment started.completedAt:DateWhen the experiment completed.results:ItemWithScores\[]All item results with their scores.ItemWithScoresitemId:stringID of the dataset item.itemVersion:numberDataset version of the item when executed.input:unknownInput data passed to the target.output:unknown | nullOutput from the target, or \`null\` if failed.groundTruth:unknown | nullExpected output from the dataset item.error:{ message: string; stack?: string; code?: string } | nullStructured error if execution failed.startedAt:DateWhen item execution started.completedAt:DateWhen item execution completed.retryCount:numberNumber of retry attempts.scores:ScorerResult\[]Results from all scorers for this item.ScorerResultscorerId:stringID of the scorer.scorerName:stringDisplay name of the scorer.score:number | nullComputed score, or \`null\` if the scorer failed.reason:string | nullReason/explanation for the score.error:string | nullError message if the scorer failed.
+
+## Related
+
+- [dataset.startExperimentAsync()](https://mastra.ai/reference/datasets/startExperimentAsync)
+- [dataset.listExperiments()](https://mastra.ai/reference/datasets/listExperiments)
+- [DatasetsManager.compareExperiments()](https://mastra.ai/reference/datasets/compareExperiments)

package/.docs/reference/datasets/startExperimentAsync.md

@@ -0,0 +1,43 @@
+# dataset.startExperimentAsync()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Starts an experiment asynchronously (fire-and-forget). Returns immediately with the experiment ID and a `'pending'` status. The experiment runs in the background.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Start experiment without waiting
+const { experimentId, status } = await dataset.startExperimentAsync({
+  targetType: 'agent',
+  targetId: 'my-agent',
+  scorers: ['accuracy'],
+})
+
+console.log(`Experiment ${experimentId} started with status: ${status}`)
+
+// Check progress later
+const experiment = await dataset.getExperiment({ experimentId })
+console.log(`Current status: ${experiment.status}`)
+```
+
+## Parameters
+
+Takes the same `StartExperimentConfig` as [`dataset.startExperiment()`](https://mastra.ai/reference/datasets/startExperiment).
+
+## Returns
+
+**result:** (`Promise<object>`): objectexperimentId:stringUnique ID of the created experiment.status:'pending'Always \`'pending'\` since the experiment hasn't started executing yet.
+
+## Related
+
+- [dataset.startExperiment()](https://mastra.ai/reference/datasets/startExperiment)
+- [dataset.getExperiment()](https://mastra.ai/reference/datasets/getExperiment)

package/.docs/reference/datasets/update.md

@@ -0,0 +1,48 @@
+# dataset.update()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Updates dataset metadata, name, description, and/or schemas. Zod schemas are automatically converted to JSON Schema.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { z } from 'zod'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+// Update with plain metadata
+const updated = await dataset.update({
+  name: 'Updated QA pairs',
+  description: 'Revised evaluation set',
+})
+
+// Update with Zod schema (auto-converted to JSON Schema)
+const updated2 = await dataset.update({
+  inputSchema: z.object({
+    question: z.string(),
+    context: z.string().optional(),
+  }),
+})
+```
+
+## Parameters
+
+**name?:** (`string`): New display name.
+
+**description?:** (`string`): New description.
+
+**metadata?:** (`Record<string, unknown>`): Updated metadata.
+
+**inputSchema?:** (`unknown`): JSON Schema or Zod schema for item inputs.
+
+**groundTruthSchema?:** (`unknown`): JSON Schema or Zod schema for item ground truths.
+
+## Returns
+
+**result:** (`Promise<DatasetRecord>`): The updated dataset record. See dataset.getDetails() for the full shape.

package/.docs/reference/datasets/updateItem.md

@@ -0,0 +1,38 @@
+# dataset.updateItem()
+
+**Added in:** `@mastra/core@1.4.0`
+
+Updates an existing item in the dataset. Only the provided fields are updated. Updating an item creates a new version.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  /* storage config */
+})
+
+const dataset = await mastra.datasets.get({ id: 'dataset-id' })
+
+const updated = await dataset.updateItem({
+  itemId: 'item-id',
+  input: { question: 'What is TypeScript?' },
+  groundTruth: { answer: 'A typed superset of JavaScript' },
+  metadata: { reviewed: true },
+})
+```
+
+## Parameters
+
+**itemId:** (`string`): ID of the item to update.
+
+**input?:** (`unknown`): Updated input data.
+
+**groundTruth?:** (`unknown`): Updated ground truth.
+
+**metadata?:** (`Record<string, unknown>`): Updated metadata.
+
+## Returns
+
+**result:** (`Promise<DatasetItem>`): The updated dataset item. See dataset.addItem() for the item shape.

package/.docs/reference/deployer/cloudflare.md

@@ -0,0 +1,79 @@
+# CloudflareDeployer
+
+The `CloudflareDeployer` bundles your Mastra server and generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). Cloudflare deploys this as a Cloudflare Worker.
+
+## Installation
+
+To use `CloudflareDeployer`, install the `@mastra/deployer-cloudflare` package:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-cloudflare@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-cloudflare@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-cloudflare@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-cloudflare@latest
+```
+
+## Usage example
+
+Import `CloudflareDeployer` and set it as the deployer in your Mastra configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
+
+export const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    name: 'your-project-name',
+    routes: [
+      {
+        pattern: 'example.com/*',
+        zone_name: 'example.com',
+        custom_domain: true,
+      },
+    ],
+    vars: {
+      NODE_ENV: 'production',
+      API_KEY: '<api-key>',
+    },
+    d1_databases: [
+      {
+        binding: 'DB',
+        database_name: 'my-database',
+        database_id: 'd1-database-id',
+        preview_database_id: 'your-preview-database-id',
+      },
+    ],
+    kv_namespaces: [
+      {
+        binding: 'CACHE',
+        id: 'kv-namespace-id',
+      },
+    ],
+  }),
+})
+```
+
+## Constructor options
+
+The `CloudflareDeployer` constructor accepts the same configuration options as `wrangler.jsonc`. See the [Wrangler configuration documentation](https://developers.cloudflare.com/workers/wrangler/configuration/) for all available options.
+
+## Build output
+
+After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.

package/.docs/reference/deployer/netlify.md

@@ -0,0 +1,80 @@
+# NetlifyDeployer
+
+The `NetlifyDeployer` class handles packaging, configuration, and deployment by adapting Mastra's output to create an optimized version of your server. It extends the base [`Deployer`](https://mastra.ai/reference/deployer) class with Netlify specific functionality. It enables you to run Mastra within Netlify functions.
+
+## Installation
+
+In order to use `NetlifyDeployer`, you need to install the `@mastra/deployer-netlify` package:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-netlify@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-netlify@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-netlify@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-netlify@latest
+```
+
+## Usage example
+
+Import `NetlifyDeployer` and set it as the deployer in your Mastra configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { NetlifyDeployer } from '@mastra/deployer-netlify'
+
+export const mastra = new Mastra({
+  deployer: new NetlifyDeployer(),
+})
+```
+
+## Output
+
+After running `mastra build`, the deployer generates a `.netlify` folder. The build output includes all agents, tools, and workflows of your project, alongside a special `config.json` file. The `config.json` file configures the behavior of Netlify functions.
+
+```bash
+your-project/
+└── .netlify/
+    └── v1/
+        ├── config.json
+        └── functions/
+            └── api/
+                ├── index.mjs
+                ├── package.json
+                └── node_modules/
+```
+
+The `config.json` file contains:
+
+```json
+{
+  "functions": {
+    "directory": ".netlify/v1/functions",
+    "node_bundler": "none",
+    "included_files": [".netlify/v1/functions/**"]
+  },
+  "redirects": [
+    {
+      "force": true,
+      "from": "/*",
+      "to": "/.netlify/functions/api/:splat",
+      "status": 200
+    }
+  ]
+}
+```

package/.docs/reference/deployer/vercel.md

@@ -0,0 +1,91 @@
+# VercelDeployer
+
+The `VercelDeployer` bundles your Mastra server and generates output conforming to Vercel's [Build Output API](https://vercel.com/docs/build-output-api/v3). Vercel deploys this output directly as serverless functions.
+
+## Installation
+
+To use `VercelDeployer`, install the `@mastra/deployer-vercel` package:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-vercel@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-vercel@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-vercel@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-vercel@latest
+```
+
+## Usage example
+
+Import `VercelDeployer` and set it as the deployer in your Mastra configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { VercelDeployer } from '@mastra/deployer-vercel'
+
+export const mastra = new Mastra({
+  deployer: new VercelDeployer(),
+})
+```
+
+## Constructor options
+
+The deployer accepts overrides that are written to the Vercel Output API function config (`.vc-config.json`):
+
+- `maxDuration?: number` — Function execution timeout (in seconds)
+- `memory?: number` — Function memory (in MB)
+- `regions?: string[]` — Regions to deploy the function (e.g. `['sfo1','iad1']`)
+
+These options are merged into `.vercel/output/functions/index.func/.vc-config.json` while preserving default fields (`handler`, `launcherType`, `runtime`, `shouldAddHelpers`).
+
+### Example with overrides
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { VercelDeployer } from '@mastra/deployer-vercel'
+
+export const mastra = new Mastra({
+  deployer: new VercelDeployer({
+    maxDuration: 600,
+    memory: 1536,
+    regions: ['sfo1', 'iad1'],
+  }),
+})
+```
+
+## Build output
+
+After running `mastra build`, the deployer generates a `.vercel/output` directory conforming to Vercel's [Build Output API (v3)](https://vercel.com/docs/build-output-api/v3). This directory contains routing configuration and serverless function bundles that Vercel deploys directly, bypassing framework detection.
+
+The output contains:
+
+- **config.json** — Routing configuration that directs all requests to your function
+- **functions/** — Your Mastra server bundled as a serverless function
+
+```bash
+.vercel/
+└── output/
+    ├── config.json
+    └── functions/
+        └── index.func/
+            ├── .vc-config.json
+            ├── index.mjs
+            └── node_modules/
+```
+
+This folder is generated during build and should not be committed to version control.