@mastra/mcp-docs-server 0.13.16 → 0.13.17-alpha.0

package/.docs/raw/agents/overview.mdx

@@ -161,64 +161,46 @@ Define the `output` shape using [Zod](https://zod.dev/):
 ```typescript showLineNumbers copy
 import { z } from "zod";
 
-const response = await testAgent.generate("Monkey, Ice Cream, Boat", {
-  experimental_output: z.object({
-    summary: z.string(),
-    keywords: z.array(z.string())
-  })
-});
-
-console.log(response.object);
-```
-
-### Using Tools
-
-If you need to generate structured output alongside tool calls, you'll need to use the `experimental_output` or `structuredOutput` property instead of `output`. Here's how:
-
-```typescript showLineNumbers copy
-const response = await testAgent.generate("Monkey, Ice Cream, Boat", {
-  experimental_output: z.object({
-    summary: z.string(),
-    keywords: z.array(z.string())
-  })
-});
-
-const responseWithExperimentalOutput = await testAgent.generate(
+const response = await testAgent.generate(
   [
     {
-      role: "user",
-      content:
-        "Please analyze this repository and provide a summary and keywords...",
+      role: "system",
+      content: "Provide a summary and keywords for the following text:"
     },
+    {
+      role: "user",
+      content: "Monkey, Ice Cream, Boat"
+    }
   ],
   {
-    // Use experimental_output to enable both structured output and tool calls
-    experimental_output: schema,
-  },
+    output: z.object({
+      summary: z.string(),
+      keywords: z.array(z.string())
+    })
+  }
 );
 
-console.log("Structured Output:", responseWithExperimentalOutput.object);
+console.log(response.object);
+```
 
-const responseWithStructuredOutput = await testAgent.generate(
-  [
-    {
-      role: "user",
-      content:
-        "Please analyze this repository and provide a summary and keywords...",
-    },
-  ],
+#### Agents with tools
+
+To generate structured output with agents that use tools, use the `experimental_output` property:
+
+```typescript {6} showLineNumbers copy
+import { z } from "zod";
+
+const response = await testAgent.generate(
+  // ...
   {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: z.array(z.string())
-      }),
-      model: openai("gpt-4o-mini"),
-    }
-  },
+    experimental_output: z.object({
+      summary: z.string(),
+      keywords: z.array(z.string())
+    })
+  }
 );
 
-console.log("Structured Output:", responseWithStructuredOutput.object);
+console.log(response.object);
 ```
 
 ## Describing images

package/.docs/raw/deployment/monorepo.mdx

@@ -0,0 +1,107 @@
+---
+title: Monorepo Deployment
+description: Learn how to deploy Mastra applications that are part of a monorepo setup
+---
+
+import { FileTree } from "nextra/components";
+
+# Monorepo Deployment
+
+Deploying Mastra in a monorepo follows the same approach as deploying a standalone application. While some [Cloud](./cloud-providers/) or [Serverless Platform](./serverless-platforms/) providers may introduce extra requirements, the core setup is the same.
+
+## Example monorepo
+
+In this example, the Mastra application is located at `apps/api`.
+
+<FileTree>
+  <FileTree.Folder name="apps" defaultOpen>
+    <FileTree.Folder name="api" defaultOpen>
+      <FileTree.Folder name="src" defaultOpen>
+        <FileTree.Folder name="mastra" defaultOpen>
+          <FileTree.Folder name="agents" />
+          <FileTree.Folder name="tools" />
+          <FileTree.Folder name="workflows" />
+          <FileTree.File name="index.ts" />
+        </FileTree.Folder>
+      </FileTree.Folder>
+      <FileTree.File name="package.json" />
+      <FileTree.File name="tsconfig.json" />
+    </FileTree.Folder>
+    <FileTree.Folder name="web" />
+  </FileTree.Folder>
+  <FileTree.Folder name="packages" defaultOpen>
+    <FileTree.Folder name="ui" />
+    <FileTree.Folder name="utils" />
+  </FileTree.Folder>
+  <FileTree.File name="package.json" />
+</FileTree>
+
+## Environment variables
+
+Environment variables like `OPENAI_API_KEY` should be stored in an `.env` file at the root of the Mastra application `(apps/api)`, for example:
+
+<FileTree>
+  <FileTree.Folder name="api" defaultOpen>
+    <FileTree.Folder name="src" defaultOpen>
+      <FileTree.Folder name="mastra" />
+    </FileTree.Folder>
+    <FileTree.File name=".env" />
+    <FileTree.File name="package.json" />
+    <FileTree.File name="tsconfig.json" />
+  </FileTree.Folder>
+</FileTree>
+
+
+## Deployment configuration
+
+The image below shows how to select `apps/api` as the project root when deploying to [Mastra Cloud](../mastra-cloud/overview.mdx). While the interface may differ between providers, the configuration remains the same.
+
+![Deployment configuration](/image/monorepo/monorepo-mastra-cloud.jpg)
+
+## Dependency management
+
+In a monorepo, keep dependencies consistent to avoid version conflicts and build errors.
+
+- Use a **single lockfile** at the project root so all packages resolve the same versions.
+- Align versions of **shared libraries** (like Mastra or frameworks) to prevent duplicates.
+
+## Deployment pitfalls
+
+Common issues to watch for when deploying Mastra in a monorepo:
+
+- **Wrong project root**: make sure the correct package (e.g. `apps/api`) is selected as the deploy target.
+
+## Bundler options
+
+Use `transpilePackages` to compile TypeScript workspace packages or libraries. List package names exactly as they appear in each `package.json`. Use `externals` to exclude dependencies resolved at runtime, and `sourcemap` to emit readable stack traces.
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+
+export const mastra = new Mastra({
+  // ...
+  bundler: {
+    transpilePackages: ["utils"],
+    externals: ["ui"],
+    sourcemap: true
+  }
+});
+```
+
+> See [Mastra Class](../../reference/core/mastra-class.mdx) for more configuration options.
+
+## Supported monorepos
+
+Mastra works with:
+
+- npm workspaces
+- pnpm workspaces
+- Yarn workspaces
+- Turborepo
+
+Known limitations:
+
+- Bun workspaces — partial support; known issues
+- Nx — known issues
+
+> If you are experiencing issues with monorepos see our: [Monorepos Support mega issue](https://github.com/mastra-ai/mastra/issues/6852).

package/.docs/raw/frameworks/web-frameworks/astro.mdx

@@ -516,3 +516,4 @@ Let me know if you need more information!
 ## Next Steps
 
 - [Deployment | With Astro on Vercel](/docs/deployment/web-framework#with-astro-on-vercel)
+- [Monorepo Deployment](../../deployment/monorepo.mdx)

package/.docs/raw/frameworks/web-frameworks/next-js.mdx

@@ -530,3 +530,4 @@ Let me know if you need more information!
 ## Next Steps
 
 - [Deployment | With Next.js on Vercel](/docs/deployment/web-framework#with-nextjs-on-vercel)
+- [Monorepo Deployment](../../deployment/monorepo.mdx)

package/.docs/raw/frameworks/web-frameworks/sveltekit.mdx

@@ -454,3 +454,8 @@ If you need more details or information about a different location, feel free to
   </Steps>
   </Tabs.Tab>
 </Tabs>
+
+
+## Next steps
+
+- [Monorepo Deployment](../../deployment/monorepo.mdx)

package/.docs/raw/frameworks/web-frameworks/vite-react.mdx

@@ -235,3 +235,8 @@ Submitting **London** as the city would return a result similar to:
 ```plaintext
 The current weather in London is partly cloudy with a temperature of 19.3°C, feeling like 17.4°C. The humidity is at 53%, and there is a wind speed of 15.9 km/h, with gusts up to 38.5 km/h.
 ```
+
+
+## Next steps
+
+- [Monorepo Deployment](../../deployment/monorepo.mdx)

package/.docs/raw/reference/core/mastra-class.mdx

@@ -16,7 +16,7 @@ Think of `Mastra` as a top-level registry:
 ## Importing
 
 ```typescript
-import { Mastra } from "@mastra/core";
+import { Mastra } from "@mastra/core/mastra";
 ```
 
 ## Constructor
@@ -32,7 +32,7 @@ constructor(config?: Config);
 The Mastra class is typically initialized in your `src/mastra/index.ts` file:
 
 ```typescript filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
+import { Mastra } from "@mastra/core/mastra";
 import { LibSQLStore } from "@mastra/libsql";
 import { weatherAgent } from "./agents/weather-agent";
 
@@ -138,7 +138,9 @@ The constructor accepts an optional `Config` object to customize its behavior an
     {
       name: "bundler",
       type: "BundlerConfig",
-      description: "Configuration for the asset bundler.",
+      description: "Configuration for the asset bundler with options for externals, sourcemap, and transpilePackages.",
+      isOptional: true,
+      defaultValue: "{ externals: [], sourcemap: false, transpilePackages: [] }",
     },
   ]}
 />

package/.docs/raw/reference/scorers/context-precision.mdx

@@ -0,0 +1,130 @@
+---
+title: "Reference: Context Precision Scorer | Scorers | Mastra Docs"
+description: Documentation for the Context Precision Scorer in Mastra. Evaluates the relevance and precision of retrieved context for generating expected outputs using Mean Average Precision.
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# Context Precision Scorer
+
+The `createContextPrecisionScorer()` function creates a scorer that evaluates how relevant and well-positioned retrieved context pieces are for generating expected outputs. It uses **Mean Average Precision (MAP)** to reward systems that place relevant context earlier in the sequence.
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "MastraLanguageModel",
+      description: "The language model to use for evaluating context relevance",
+      required: true,
+    },
+    {
+      name: "options",
+      type: "ContextPrecisionMetricOptions",
+      description: "Configuration options for the scorer",
+      required: true,
+      children: [
+        {
+          name: "context",
+          type: "string[]",
+          description: "Array of context pieces to evaluate for relevance",
+          required: false,
+        },
+        {
+          name: "contextExtractor",
+          type: "(input, output) => string[]",
+          description: "Function to dynamically extract context from the run input and output",
+          required: false,
+        },
+        {
+          name: "scale",
+          type: "number",
+          description: "Scale factor to multiply the final score (default: 1)",
+          required: false,
+        },
+      ],
+    },
+  ]}
+/>
+
+:::note
+Either `context` or `contextExtractor` must be provided. If both are provided, `contextExtractor` takes precedence.
+:::
+
+## .run() Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "score",
+      type: "number",
+      description: "Mean Average Precision score between 0 and scale (default 0-1)",
+    },
+    {
+      name: "reason",
+      type: "string",
+      description: "Human-readable explanation of the context precision evaluation",
+    },
+  ]}
+/>
+
+## Scoring Details
+
+### Mean Average Precision (MAP)
+
+Context Precision uses **Mean Average Precision** to evaluate both relevance and positioning:
+
+1. **Context Evaluation**: Each context piece is classified as relevant or irrelevant for generating the expected output
+2. **Precision Calculation**: For each relevant context at position `i`, precision = `relevant_items_so_far / (i + 1)`
+3. **Average Precision**: Sum all precision values and divide by total relevant items
+4. **Final Score**: Multiply by scale factor and round to 2 decimals
+
+### Scoring Formula
+
+```
+MAP = (Σ Precision@k) / R
+
+Where:
+- Precision@k = (relevant items in positions 1...k) / k
+- R = total number of relevant items
+- Only calculated at positions where relevant items appear
+```
+
+### Score Interpretation
+
+- **1.0** = Perfect precision (all relevant context appears first)
+- **0.5-0.9** = Good precision with some relevant context well-positioned
+- **0.1-0.4** = Poor precision with relevant context buried or scattered
+- **0.0** = No relevant context found
+
+### Example Calculation
+
+Given context: `[relevant, irrelevant, relevant, irrelevant]`
+
+- Position 0: Relevant → Precision = 1/1 = 1.0
+- Position 1: Skip (irrelevant)  
+- Position 2: Relevant → Precision = 2/3 = 0.67
+- Position 3: Skip (irrelevant)
+
+MAP = (1.0 + 0.67) / 2 = 0.835 ≈ **0.83**
+
+## Usage Patterns
+
+### RAG System Evaluation
+Ideal for evaluating retrieved context in RAG pipelines where:
+- Context ordering matters for model performance
+- You need to measure retrieval quality beyond simple relevance
+- Early relevant context is more valuable than later relevant context
+
+### Context Window Optimization
+Use when optimizing context selection for:
+- Limited context windows
+- Token budget constraints  
+- Multi-step reasoning tasks
+
+## Related
+
+- [Answer Relevancy Scorer](/reference/scorers/answer-relevancy) - Evaluates if answers address the question
+- [Faithfulness Scorer](/reference/scorers/faithfulness) - Measures answer groundedness in context
+- [Custom Scorers](/docs/scorers/custom-scorers) - Creating your own evaluation metrics

package/.docs/raw/reference/scorers/context-relevance.mdx

@@ -0,0 +1,222 @@
+---
+title: "Reference: Context Relevance Scorer | Scorers | Mastra Docs"
+description: Documentation for the Context Relevance Scorer in Mastra. Evaluates the relevance and utility of provided context for generating agent responses using weighted relevance scoring.
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# Context Relevance Scorer
+
+The `createContextRelevanceScorerLLM()` function creates a scorer that evaluates how relevant and useful provided context was for generating agent responses. It uses weighted relevance levels and applies penalties for unused high-relevance context and missing information.
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "MastraLanguageModel",
+      description: "The language model to use for evaluating context relevance",
+      required: true,
+    },
+    {
+      name: "options",
+      type: "ContextRelevanceOptions",
+      description: "Configuration options for the scorer",
+      required: true,
+      children: [
+        {
+          name: "context",
+          type: "string[]",
+          description: "Array of context pieces to evaluate for relevance",
+          required: false,
+        },
+        {
+          name: "contextExtractor",
+          type: "(input, output) => string[]",
+          description: "Function to dynamically extract context from the run input and output",
+          required: false,
+        },
+        {
+          name: "scale",
+          type: "number",
+          description: "Scale factor to multiply the final score (default: 1)",
+          required: false,
+        },
+        {
+          name: "penalties",
+          type: "object",
+          description: "Configurable penalty settings for scoring",
+          required: false,
+          children: [
+            {
+              name: "unusedHighRelevanceContext",
+              type: "number",
+              description: "Penalty per unused high-relevance context (default: 0.1)",
+              required: false,
+            },
+            {
+              name: "missingContextPerItem",
+              type: "number",
+              description: "Penalty per missing context item (default: 0.15)",
+              required: false,
+            },
+            {
+              name: "maxMissingContextPenalty",
+              type: "number",
+              description: "Maximum total missing context penalty (default: 0.5)",
+              required: false,
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+:::note
+Either `context` or `contextExtractor` must be provided. If both are provided, `contextExtractor` takes precedence.
+:::
+
+## .run() Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "score",
+      type: "number",
+      description: "Weighted relevance score between 0 and scale (default 0-1)",
+    },
+    {
+      name: "reason",
+      type: "string",
+      description: "Human-readable explanation of the context relevance evaluation",
+    },
+  ]}
+/>
+
+## Scoring Details
+
+### Weighted Relevance Scoring
+
+Context Relevance uses a sophisticated scoring algorithm that considers:
+
+1. **Relevance Levels**: Each context piece is classified with weighted values:
+   - `high` = 1.0 (directly addresses the query)
+   - `medium` = 0.7 (supporting information)
+   - `low` = 0.3 (tangentially related)
+   - `none` = 0.0 (completely irrelevant)
+
+2. **Usage Detection**: Tracks whether relevant context was actually used in the response
+
+3. **Penalties Applied** (configurable via `penalties` options):
+   - **Unused High-Relevance**: `unusedHighRelevanceContext` penalty per unused high-relevance context (default: 0.1)
+   - **Missing Context**: Up to `maxMissingContextPenalty` for identified missing information (default: 0.5)
+
+### Scoring Formula
+
+```
+Base Score = Σ(relevance_weights) / (num_contexts × 1.0)
+Usage Penalty = count(unused_high_relevance) × unusedHighRelevanceContext
+Missing Penalty = min(count(missing_context) × missingContextPerItem, maxMissingContextPenalty)
+
+Final Score = max(0, Base Score - Usage Penalty - Missing Penalty) × scale
+```
+
+**Default Values**:
+- `unusedHighRelevanceContext` = 0.1 (10% penalty per unused high-relevance context)
+- `missingContextPerItem` = 0.15 (15% penalty per missing context item)
+- `maxMissingContextPenalty` = 0.5 (maximum 50% penalty for missing context)
+- `scale` = 1
+
+### Score Interpretation
+
+- **0.9-1.0** = Excellent relevance with minimal gaps
+- **0.7-0.8** = Good relevance with some unused or missing context
+- **0.4-0.6** = Mixed relevance with significant gaps
+- **0.0-0.3** = Poor relevance or mostly irrelevant context
+
+### Difference from Context Precision
+
+| Aspect | Context Relevance | Context Precision |
+|--------|-------------------|-------------------|
+| **Algorithm** | Weighted levels with penalties | Mean Average Precision (MAP) |
+| **Relevance** | Multiple levels (high/medium/low/none) | Binary (yes/no) |
+| **Position** | Not considered | Critical (rewards early placement) |
+| **Usage** | Tracks and penalizes unused context | Not considered |
+| **Missing** | Identifies and penalizes gaps | Not evaluated |
+
+## Usage Examples
+
+### Basic Configuration
+
+```typescript
+const scorer = createContextRelevanceScorerLLM({
+  model: openai('gpt-4o'),
+  options: {
+    context: ['Einstein won the Nobel Prize for his work on the photoelectric effect'],
+    scale: 1,
+  },
+});
+```
+
+### Custom Penalty Configuration
+
+```typescript
+const scorer = createContextRelevanceScorerLLM({
+  model: openai('gpt-4o'),
+  options: {
+    context: ['Context information...'],
+    penalties: {
+      unusedHighRelevanceContext: 0.05, // Lower penalty for unused context
+      missingContextPerItem: 0.2, // Higher penalty per missing item
+      maxMissingContextPenalty: 0.4, // Lower maximum penalty cap
+    },
+    scale: 2, // Double the final score
+  },
+});
+```
+
+### Dynamic Context Extraction
+
+```typescript
+const scorer = createContextRelevanceScorerLLM({
+  model: openai('gpt-4o'),
+  options: {
+    contextExtractor: (input, output) => {
+      // Extract context based on the query
+      const userQuery = input?.inputMessages?.[0]?.content || '';
+      if (userQuery.includes('Einstein')) {
+        return [
+          'Einstein won the Nobel Prize for the photoelectric effect',
+          'He developed the theory of relativity'
+        ];
+      }
+      return ['General physics information'];
+    },
+    penalties: {
+      unusedHighRelevanceContext: 0.15,
+    },
+  },
+});
+```
+
+## Usage Patterns
+
+### Content Generation Evaluation
+Best for evaluating context quality in:
+- Chat systems where context usage matters
+- RAG pipelines needing nuanced relevance assessment
+- Systems where missing context affects quality
+
+### Context Selection Optimization
+Use when optimizing for:
+- Comprehensive context coverage
+- Effective context utilization
+- Identifying context gaps
+
+## Related
+
+- [Context Precision Scorer](/reference/scorers/context-precision) - Evaluates context ranking using MAP
+- [Faithfulness Scorer](/reference/scorers/faithfulness) - Measures answer groundedness in context
+- [Custom Scorers](/docs/scorers/custom-scorers) - Creating your own evaluation metrics

package/.docs/raw/scorers/off-the-shelf-scorers.mdx

@@ -21,6 +21,22 @@ These scorers evaluate how correct, truthful, and complete your agent's answers
 - [`textual-difference`](/reference/scorers/textual-difference): Measures textual differences between strings (`0-1`, higher means more similar)
 - [`tool-call-accuracy`](/reference/scorers/tool-call-accuracy): Evaluates whether the LLM selects the correct tool from available options (`0-1`, higher is better)
 
+### Context Quality
+
+These scorers evaluate the quality and relevance of context used in generating responses:
+
+- [`context-precision`](/reference/scorers/context-precision): Evaluates context relevance and ranking using Mean Average Precision, rewarding early placement of relevant context (`0-1`, higher is better)
+- [`context-relevance`](/reference/scorers/context-relevance): Measures context utility with nuanced relevance levels, usage tracking, and missing context detection (`0-1`, higher is better)
+
+:::tip Context Scorer Selection
+- Use **Context Precision** when context ordering matters and you need standard IR metrics (ideal for RAG ranking evaluation)
+- Use **Context Relevance** when you need detailed relevance assessment and want to track context usage and identify gaps
+
+Both context scorers support:
+- **Static context**: Pre-defined context arrays
+- **Dynamic context extraction**: Extract context from runs using custom functions (ideal for RAG systems, vector databases, etc.)
+:::
+
 ### Output Quality
 
 These scorers evaluate adherence to format, style, and safety requirements:
@@ -28,4 +44,4 @@ These scorers evaluate adherence to format, style, and safety requirements:
 - [`tone-consistency`](/reference/scorers/tone-consistency): Measures consistency in formality, complexity, and style (`0-1`, higher is better)
 - [`toxicity`](/reference/scorers/toxicity): Detects harmful or inappropriate content (`0-1`, lower is better)
 - [`bias`](/reference/scorers/bias): Detects potential biases in the output (`0-1`, lower is better)
-- [`keyword-coverage`](/reference/scorers/keyword-coverage): Assesses technical terminology usage (`0-1`, higher is better)
+- [`keyword-coverage`](/reference/scorers/keyword-coverage): Assesses technical terminology usage (`0-1`, higher is better)

package/.docs/raw/server-db/local-dev-playground.mdx

@@ -184,6 +184,25 @@ export const mastra = new Mastra({
 });
 ```
 
+## Bundler options
+
+Use `transpilePackages` to compile TypeScript packages or libraries. Use `externals` to exclude dependencies resolved at runtime, and `sourcemap` to emit readable stack traces.
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+
+export const mastra = new Mastra({
+  // ...
+  bundler: {
+    transpilePackages: ["utils"],
+    externals: ["ui"],
+    sourcemap: true
+  }
+});
+```
+
+> See [Mastra Class](../../reference/core/mastra-class.mdx) for more configuration options.
+
 
 ## Next steps