@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.23

package/.docs/reference/core/listMCPServers.md

@@ -12,18 +12,14 @@ const server1 = new MCPServer({
   id: 'server-one',
   name: 'Server One',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 const server2 = new MCPServer({
   id: 'server-two',
   name: 'Server Two',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 export const mastra = new Mastra({

package/.docs/reference/datasets/addItem.md

@@ -11,9 +11,7 @@ Adds a single item to the dataset. Each item has an input, optional ground truth
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/addItems.md

@@ -11,9 +11,7 @@ Adds multiple items to the dataset in a single bulk operation.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/compareExperiments.md

@@ -11,9 +11,7 @@ Compares two or more experiments, producing per-item and per-scorer comparisons.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const comparison = await mastra.datasets.compareExperiments({
   experimentIds: ['exp-baseline', 'exp-new'],

package/.docs/reference/datasets/create.md

@@ -12,9 +12,7 @@ Creates a new dataset. Use Standard JSON Schema (Zod, Valibot, ArkType, etc.) fo
 import { Mastra } from '@mastra/core'
 import { z } from 'zod'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Create with metadata
 const dataset = await mastra.datasets.create({

package/.docs/reference/datasets/dataset.md

@@ -13,9 +13,7 @@ The `Dataset` class provides methods for item CRUD, versioning, and experiment m
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.create({
   name: 'QA pairs',
@@ -44,9 +42,7 @@ console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/datasets-manager.md

@@ -13,9 +13,7 @@ The `DatasetsManager` class provides the public API for managing datasets, inclu
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Create a dataset
 const dataset = await mastra.datasets.create({
@@ -32,9 +30,7 @@ const { datasets } = await mastra.datasets.list()
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Get by ID
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
@@ -50,9 +46,7 @@ Retrieves a specific experiment (run) by ID. Unlike `dataset.getExperiment()`, t
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Get experiment directly without knowing the dataset
 const experiment = await mastra.datasets.getExperiment({
@@ -68,9 +62,7 @@ console.log(`Status: ${experiment.status}`)
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const comparison = await mastra.datasets.compareExperiments({
   experimentIds: ['exp-1', 'exp-2'],
@@ -83,9 +75,7 @@ const comparison = await mastra.datasets.compareExperiments({
 `DatasetsManager` isn't instantiated directly. Access it from a `Mastra` instance:
 
 ```typescript
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 const datasetsManager = mastra.datasets
 ```
 

package/.docs/reference/datasets/delete.md

@@ -11,9 +11,7 @@ Deletes a dataset by ID, including all items, versions, and experiments.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 await mastra.datasets.delete({ id: 'dataset-id' })
 ```

package/.docs/reference/datasets/deleteExperiment.md

@@ -11,9 +11,7 @@ Deletes an experiment (run) by ID, including all associated results.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/deleteItem.md

@@ -11,9 +11,7 @@ Deletes a single item from the dataset by ID.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/deleteItems.md

@@ -11,9 +11,7 @@ Deletes multiple items from the dataset in a single bulk operation.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/get.md

@@ -11,9 +11,7 @@ Retrieves an existing dataset by ID. Throws a `MastraError` if the dataset doesn
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getDetails.md

@@ -11,9 +11,7 @@ Retrieves the full dataset record from storage, including metadata, schemas, and
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getExperiment.md

@@ -11,9 +11,7 @@ Retrieves a specific experiment (run) by its ID.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getItem.md

@@ -11,9 +11,7 @@ Retrieves a single dataset item by ID, optionally at a specific dataset version.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Retrieves the full SCD-2 (Slowly Changing Dimension Type 2) history of a specifi
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Lists datasets with pagination and optional filters. Filters are applied at the
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const { datasets, pagination } = await mastra.datasets.list({ page: 0, perPage: 10 })
 

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

@@ -11,9 +11,7 @@ Lists individual item results for a specific experiment with optional filters an
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Lists experiments (runs) for this dataset with optional filters and pagination.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Lists items in the dataset. When only `version` is provided, returns a bare `Dat
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Lists all versions of the dataset with pagination.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Runs an experiment on the dataset and waits for completion. Executes all items a
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Starts an experiment asynchronously (fire-and-forget). Returns immediately with
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -12,9 +12,7 @@ Updates dataset metadata, name, description, and/or schemas. Use Standard JSON S
 import { Mastra } from '@mastra/core'
 import { z } from 'zod'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

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

@@ -11,9 +11,7 @@ Updates an existing item in the dataset. Only the provided fields are updated. U
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/editor/mastra-editor.md

@@ -14,9 +14,7 @@ import { MastraEditor } from '@mastra/editor'
 import { ComposioToolProvider } from '@mastra/editor/providers/composio'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
   editor: new MastraEditor({
     toolProviders: {
       composio: new ComposioToolProvider({

package/.docs/reference/evals/context-recall.md

@@ -0,0 +1,205 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Context recall scorer
+
+The `createContextRecallScorer()` function creates a scorer that evaluates how well retrieved context covers the claims in a ground-truth reference answer. It measures retrieval completeness by checking what fraction of the ground truth's claims are attributable to the retrieved context.
+
+This scorer requires a ground-truth reference answer, making it suitable for labeled datasets in CI or test environments. When `groundTruth` is not provided in the run, the scorer returns a score of 0 rather than throwing an error.
+
+## RAG retrieval evaluation
+
+Ideal for evaluating retrieval completeness in RAG pipelines where:
+
+- You need to verify the retriever fetches all necessary information
+- You have labeled datasets with known-correct answers
+- You want to catch regressions in what the retriever returns
+
+## Dataset-driven testing
+
+Use when running evaluations against curated test sets:
+
+- CI pipelines with ground-truth labeled questions
+- A/B testing retrieval strategies
+- Benchmarking embedding models for coverage
+
+## Parameters
+
+**model** (`MastraModelConfig`): The language model to use for evaluating claim attribution
+
+**options** (`ContextRecallMetricOptions`): Configuration options for the scorer
+
+**Note**: Either `context` or `contextExtractor` must be provided. When both are provided, `contextExtractor` is used only if the run input and output are agent-shaped (`MastraDBMessage[]`); otherwise the scorer falls back to `context`.
+
+## `.run()` returns
+
+**score** (`number`): Recall score between 0 and scale (default 0-1), representing the fraction of ground-truth claims covered by the context
+
+**reason** (`string`): Human-readable explanation of which ground-truth claims were and were not found in the context
+
+## Scoring details
+
+### Claim attribution
+
+Context Recall uses a two-step LLM evaluation followed by a deterministic score calculation:
+
+1. **Claim extraction**: The ground-truth answer is decomposed into atomic claims
+2. **Attribution check**: Each claim is checked against the retrieval context for support
+
+The score is then calculated as the ratio of attributed claims to total claims, multiplied by scale.
+
+### Scoring formula
+
+```text
+Context Recall = attributed_claims / total_claims × scale
+
+Where:
+- attributed_claims = number of ground-truth claims supported by the context
+- total_claims = total number of claims extracted from the ground truth
+- Attribution is binary: a claim is either supported (yes) or not (no)
+```
+
+### Score interpretation
+
+These ranges assume the default `scale` of 1. When using a custom scale, multiply accordingly.
+
+- **0.9-1.0**: Excellent recall — context covers nearly all ground-truth claims
+- **0.7-0.8**: Good recall — most claims are covered, minor gaps
+- **0.4-0.6**: Moderate recall — significant information missing from context
+- **0.1-0.3**: Poor recall — most ground-truth claims not found in context
+- **0.0**: No recall — none of the ground-truth claims are in the context
+
+### Reason analysis
+
+The reason field explains:
+
+- Which ground-truth claims were found in the context
+- Which claims were missing and what information gaps exist
+- Specific context pieces that supported attributed claims
+
+### Optimization insights
+
+Use results to:
+
+- **Improve retrieval**: Identify what types of information the retriever misses
+- **Tune chunk size**: Ensure chunks contain enough detail to cover ground-truth claims
+- **Evaluate embeddings**: Test different embedding models for better information coverage
+- **Expand knowledge base**: Add documents that cover frequently missed claims
+
+### Example calculation
+
+Given ground truth: "Einstein was born in 1879. He developed relativity. He won the Nobel Prize."
+
+Claims extracted: 3
+
+- "Einstein was born in 1879" → attributed (context mentions birthdate)
+- "Einstein developed relativity" → attributed (context covers relativity)
+- "Einstein won the Nobel Prize" → not attributed (context doesn't mention Nobel Prize)
+
+Recall = 2/3 = 0.67
+
+## Scorer configuration
+
+### Dynamic context extraction
+
+```typescript
+const scorer = createContextRecallScorer({
+  model: 'openai/gpt-5.5',
+  options: {
+    contextExtractor: (input, output) => {
+      const query = input?.inputMessages?.[0]?.content || ''
+      const searchResults = vectorDB.search(query, { limit: 10 })
+      return searchResults.map(result => result.content)
+    },
+    scale: 1,
+  },
+})
+```
+
+### Static context evaluation
+
+```typescript
+const scorer = createContextRecallScorer({
+  model: 'openai/gpt-5.5',
+  options: {
+    context: [
+      'Document 1: Einstein was born on 14 March 1879 in Ulm, Germany.',
+      'Document 2: Einstein published the theory of special relativity in 1905.',
+      'Document 3: Einstein moved to the United States in 1933.',
+    ],
+  },
+})
+```
+
+## Example
+
+Evaluate RAG retrieval completeness against a labeled dataset:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createContextRecallScorer } from '@mastra/evals/scorers/prebuilt'
+import { myAgent } from './agent'
+
+const scorer = createContextRecallScorer({
+  model: 'openai/gpt-5.5',
+  options: {
+    contextExtractor: (input, output) => {
+      // Extract context from tool invocation results in the agent output
+      return output
+        .filter(msg => msg?.role === 'assistant')
+        .flatMap(msg => msg?.content?.toolInvocations ?? [])
+        .filter((tool: any) => tool.state === 'result')
+        .map((tool: any) => JSON.stringify(tool.result))
+    },
+  },
+})
+
+const result = await runEvals({
+  data: [
+    {
+      input: 'What are the health benefits of green tea?',
+      groundTruth:
+        'Green tea contains antioxidants that reduce inflammation, L-theanine that improves focus, and catechins that boost metabolism.',
+    },
+    {
+      input: 'How does photosynthesis work?',
+      groundTruth:
+        'Photosynthesis converts sunlight into chemical energy using chlorophyll in chloroplasts, producing glucose and oxygen from carbon dioxide and water.',
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.id].score,
+      reason: scorerResults[scorer.id].reason,
+    })
+  },
+})
+
+console.log(result.scores)
+```
+
+For more details on `runEvals`, see the [runEvals reference](https://mastra.ai/reference/evals/run-evals).
+
+To add this scorer to an agent, see the [Scorers overview](https://mastra.ai/docs/evals/overview) guide.
+
+## Comparison with context precision
+
+Choose the right scorer for your needs:
+
+| Use case                  | Context Recall           | Context Precision             |
+| ------------------------- | ------------------------ | ----------------------------- |
+| **What it measures**      | Coverage of ground truth | Relevance of retrieved chunks |
+| **Direction**             | Ground truth → context   | Context → ground truth        |
+| **Position sensitive**    | No                       | Yes (rewards early placement) |
+| **Requires ground truth** | Yes                      | Yes                           |
+| **Failure mode caught**   | Missing information      | Irrelevant noise              |
+
+Use both together for a complete picture of retrieval quality: precision catches junk in the context, recall catches gaps.
+
+## Related
+
+- [Context Precision Scorer](https://mastra.ai/reference/evals/context-precision): Evaluates if retrieved context is relevant and well-ranked
+- [Context Relevance Scorer](https://mastra.ai/reference/evals/context-relevance): Evaluates context usage and quality
+- [Faithfulness Scorer](https://mastra.ai/reference/evals/faithfulness): Measures answer groundedness in context
+- [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers): Creating your own evaluation metrics

package/.docs/reference/evals/create-scorer.md

@@ -23,18 +23,12 @@ const scorer = createScorer({
     instructions: 'You are an expert evaluator...',
   },
 })
-  .preprocess({
-    /* step config */
-  })
-  .analyze({
-    /* step config */
-  })
+  .preprocess({/* step config */})
+  .analyze({/* step config */})
   .generateScore(({ run, results }) => {
     // Return a number
   })
-  .generateReason({
-    /* step config */
-  })
+  .generateReason({/* step config */})
 ```
 
 ## `createScorer` options
@@ -51,7 +45,7 @@ const scorer = createScorer({
 
 **judge.instructions** (`string`): System prompt/instructions for the LLM.
 
-**judge.jsonPromptInjection** (`boolean`): When true, inject the JSON schema into the prompt instead of using the provider's native response\_format API. Set this for models that don't support native structured output (e.g. some Groq Llama models) to avoid a wasted 400 call.
+**judge.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the judge's structured output schema reaches the model. Defaults to 'auto', which uses native structured output when supported and inline prompt injection otherwise. Explicit values override automatic routing.
 
 **judge.inputProcessors** (`Processor[]`): Input processors applied to the internal judge agent before its messages reach the model (e.g. redaction, validation).
 

package/.docs/reference/evals/mastra-scorer.md

@@ -33,9 +33,7 @@ const result = await scorer.run({
   input: 'What is machine learning?',
   output: 'Machine learning is a subset of artificial intelligence...',
   runId: 'optional-run-id',
-  requestContext: {
-    /* optional context */
-  },
+  requestContext: {/* optional context */},
 })
 ```