@mastra/mcp-docs-server 0.0.0-default-storage-virtual-file-20250410035748

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

@@ -0,0 +1,119 @@
+---
+title: "Serverless Deployment"
+description: "Build and deploy Mastra applications using platform-specific deployers or standard HTTP servers"
+---
+
+# Serverless Deployment
+
+This guide covers deploying Mastra to Cloudflare Workers, Vercel, and Netlify using platform-specific deployers
+
+For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/deployment/server) guide.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Node.js** installed (version 18 or higher is recommended)
+- If using a platform-specific deployer:
+  - An account with your chosen platform
+  - Required API keys or credentials
+
+## Serverless Platform Deployers
+
+Platform-specific deployers handle configuration and deployment for:
+- **[Cloudflare Workers](/docs/reference/deployer/cloudflare)**
+- **[Vercel](/docs/reference/deployer/vercel)**
+- **[Netlify](/docs/reference/deployer/netlify)**
+
+### Installing Deployers
+
+```bash copy
+# For Cloudflare
+npm install @mastra/deployer-cloudflare
+
+# For Vercel
+npm install @mastra/deployer-vercel
+
+# For Netlify
+npm install @mastra/deployer-netlify
+```
+
+### Configuring Deployers
+
+Configure the deployer in your entry file:
+
+```typescript copy showLineNumbers
+import { Mastra, createLogger } from '@mastra/core';
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare';
+
+export const mastra = new Mastra({
+  agents: { /* your agents here */ },
+  logger: createLogger({ name: 'MyApp', level: 'debug' }),
+  deployer: new CloudflareDeployer({
+    scope: 'your-cloudflare-scope',
+    projectName: 'your-project-name',
+    // See complete configuration options in the reference docs
+  }),
+});
+```
+
+### Deployer Configuration
+
+Each deployer has specific configuration options. Below are basic examples, but refer to the reference documentation for complete details.
+
+#### Cloudflare Deployer
+
+```typescript copy showLineNumbers
+new CloudflareDeployer({
+  scope: 'your-cloudflare-account-id',
+  projectName: 'your-project-name',
+  // For complete configuration options, see the reference documentation
+})
+```
+
+[View Cloudflare Deployer Reference →](/docs/reference/deployer/cloudflare)
+
+#### Vercel Deployer
+
+```typescript copy showLineNumbers
+new VercelDeployer({
+  teamSlug: 'your-vercel-team-slug',
+  projectName: 'your-project-name',
+  token: 'your-vercel-token'
+  // For complete configuration options, see the reference documentation
+})
+```
+
+[View Vercel Deployer Reference →](/docs/reference/deployer/vercel)
+
+#### Netlify Deployer
+
+```typescript copy showLineNumbers
+new NetlifyDeployer({
+  scope: 'your-netlify-team-slug',
+  projectName: 'your-project-name',
+  token: 'your-netlify-token'
+})
+```
+
+[View Netlify Deployer Reference →](/docs/reference/deployer/netlify)
+
+## Environment Variables
+
+Required variables:
+
+1. Platform deployer variables (if using platform deployers):
+   - Platform credentials
+2. Agent API keys:
+   - `OPENAI_API_KEY`
+   - `ANTHROPIC_API_KEY`
+3. Server configuration (for universal deployment):
+   - `PORT`: HTTP server port (default: 3000)
+   - `HOST`: Server host (default: 0.0.0.0)
+
+## Platform Documentation
+
+Platform deployment references:
+- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
+- [Vercel](https://vercel.com/docs)
+- [Netlify](https://docs.netlify.com/)

package/.docs/raw/deployment/server.mdx

@@ -0,0 +1,276 @@
+---
+title: "Creating A Mastra Server"
+description: "Configure and customize the Mastra server with middleware and other options"
+---
+
+# Creating A Mastra Server
+
+While developing or when you deploy a Mastra application, it runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. This page explains how to configure and customize the server behavior.
+
+## Server Architecture
+
+Mastra uses [Hono](https://hono.dev) as its underlying HTTP server framework. When you build a Mastra application using `mastra build`, it generates a Hono-based HTTP server in the `.mastra` directory.
+
+The server provides:
+- API endpoints for all registered agents
+- API endpoints for all registered workflows
+- Custom api route supports
+- Custom middleware support
+- Configuration of timeout
+- Configuration of port
+
+## Server configuration
+
+You can configure server `port` and `timeout` in the Mastra instance.
+
+```typescript copy showLineNumbers
+import { Mastra } from '@mastra/core';
+
+export const mastra = new Mastra({
+  server: {
+    port: 3000, // Defaults to 4111
+    timeout: 10000, // Defaults to 30000 (30s)
+  },
+});
+```
+
+## Custom API Routes
+
+Mastra provides a list of api routes that are automatically generated based on the registered agents and workflows. You can also define custom api routes the Mastra instance.
+
+These routes can live in the same file as the Mastra instance or in a separate file. We recommend keeping them in a separate file to keep the Mastra instance clean.
+
+```typescript copy showLineNumbers
+import { Mastra } from '@mastra/core';
+import { registerApiRoute } from "@mastra/core/server"
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/my-custom-route', {
+        method: 'GET',
+        handler: async (c) => {
+          // you have access to mastra instance here
+          const mastra = c.get('mastra')
+
+          // you can use the mastra instance to get agents, workflows, etc.
+          const agents = await mastra.getAgent('my-agent')
+
+          return c.json({ message: 'Hello, world!' });
+        }
+      })
+    ]
+  }
+  // Other configuration options
+});
+```
+
+## Custom CORS Config
+
+Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
+
+```typescript copy showLineNumbers
+import { Mastra } from '@mastra/core';
+
+export const mastra = new Mastra({
+  server: {
+    cors: {
+      origin: ['https://example.com'], // Allow specific origins or '*' for all
+      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      allowHeaders: ['Content-Type', 'Authorization'],
+      credentials: false,
+    }
+  }
+});
+```
+
+## Middleware
+
+Mastra allows you to configure custom middleware functions that will be applied to API routes. This is useful for adding authentication, logging, CORS, or other HTTP-level functionality to your API endpoints.
+
+```typescript copy showLineNumbers
+import { Mastra } from '@mastra/core';
+
+export const mastra = new Mastra({
+  // Other configuration options
+  server: {
+    middleware: [
+    {
+      handler: async (c, next) => {
+        // Example: Add authentication check
+        const authHeader = c.req.header('Authorization');
+        if (!authHeader) {
+          return new Response('Unauthorized', { status: 401 });
+        }
+        
+        // Continue to the next middleware or route handler
+        await next();
+      },
+      path: '/api/*'
+    },
+    // add middleware to all routes
+    async (c, next) => {
+      // Example: Add request logging
+      console.log(`${c.req.method} ${c.req.url}`);
+      await next();
+    },
+  ]
+});
+```
+
+if you want to add a middleware to a single route, you can also specify that in the registerApiRoute using `registerApiRoute`.
+
+```typescript copy showLineNumbers
+registerApiRoute('/my-custom-route', {
+  method: 'GET',
+  middleware: [
+    async (c, next) => {
+      // Example: Add request logging
+      console.log(`${c.req.method} ${c.req.url}`);
+      await next();
+    },
+  ],
+  handler: async (c) => {
+    // you have access to mastra instance here
+    const mastra = c.get('mastra')
+
+    // you can use the mastra instance to get agents, workflows, etc.
+    const agents = await mastra.getAgent('my-agent')
+
+    return c.json({ message: 'Hello, world!' });
+  }
+})
+```
+
+### Middleware Behavior
+
+Each middleware function:
+- Receives a Hono context object (`c`) and a `next` function
+- Can return a `Response` to short-circuit the request handling
+- Can call `next()` to continue to the next middleware or route handler
+- Can optionally specify a path pattern (defaults to '/api/*')
+
+### Common Middleware Use Cases
+
+#### Authentication
+
+```typescript copy
+{
+  handler: async (c, next) => {
+    const authHeader = c.req.header('Authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    
+    const token = authHeader.split(' ')[1];
+    // Validate token here
+    
+    await next();
+  },
+  path: '/api/*',
+}
+```
+
+#### CORS Support
+
+```typescript copy
+{
+  handler: async (c, next) => {
+    // Add CORS headers
+    c.header('Access-Control-Allow-Origin', '*');
+    c.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    c.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    
+    // Handle preflight requests
+    if (c.req.method === 'OPTIONS') {
+      return new Response(null, { status: 204 });
+    }
+    
+    await next();
+  }
+}
+```
+
+#### Request Logging
+
+```typescript copy
+{
+  handler: async (c, next) => {
+    const start = Date.now();
+    await next();
+    const duration = Date.now() - start;
+    console.log(`${c.req.method} ${c.req.url} - ${duration}ms`);
+  }
+}
+```
+
+### Special Mastra Headers
+
+When integrating with Mastra Cloud or building custom clients, there are special headers that clients send to identify themselves and enable specific features. Your server middleware can check for these headers to customize behavior:
+
+```typescript copy
+{
+  handler: async (c, next) => {
+    // Check for Mastra-specific headers in incoming requests
+    const isFromMastraCloud = c.req.header('x-mastra-cloud') === 'true';
+    const clientType = c.req.header('x-mastra-client-type'); // e.g., 'js', 'python'
+    const isDevPlayground = c.req.header('x-mastra-dev-playground') === 'true';
+    
+    // Customize behavior based on client information
+    if (isFromMastraCloud) {
+      // Special handling for Mastra Cloud requests
+    }
+    
+    await next();
+  }
+}
+```
+
+These headers have the following purposes:
+- `x-mastra-cloud`: Indicates that the request is coming from Mastra Cloud
+- `x-mastra-client-type`: Specifies the client SDK type (e.g., 'js', 'python')
+- `x-mastra-dev-playground`: Indicates that the request is from the development playground
+
+You can use these headers in your middleware to implement client-specific logic or enable features only for certain environments.
+
+## Deployment
+
+Since Mastra builds to a standard Node.js server, you can deploy to any platform that runs Node.js applications:
+- Cloud VMs (AWS EC2, DigitalOcean Droplets, GCP Compute Engine)
+- Container platforms (Docker, Kubernetes)
+- Platform as a Service (Heroku, Railway)
+- Self-hosted servers
+
+### Building
+
+Build the application:
+
+```bash copy
+# Build from current directory
+mastra build
+
+# Or specify a directory
+mastra build --dir ./my-project
+```
+
+The build process:
+1. Locates entry file (`src/mastra/index.ts` or `src/mastra/index.js`)
+2. Creates `.mastra` output directory
+3. Bundles code using Rollup with tree shaking and source maps
+4. Generates [Hono](https://hono.dev) HTTP server
+
+See [`mastra build`](/docs/reference/cli/build) for all options.
+
+### Running the Server
+
+Start the HTTP server:
+
+```bash copy
+node .mastra/output/index.mjs
+```
+
+## Serverless Deployment
+
+Mastra also supports serverless deployment on Cloudflare Workers, Vercel, and Netlify.
+
+See our [Serverless Deployment](/docs/deployment/deployment) guide for setup instructions.

package/.docs/raw/evals/custom-eval.mdx

@@ -0,0 +1,22 @@
+---
+title: "Create your own Eval"
+description: "Mastra allows so create your own evals, here is how."
+---
+
+# Create your own Eval
+
+Creating your own eval is as easy as creating a new function. You simply create a class that extends the `Metric` class and implement the `measure` method.
+
+## Basic example
+
+For a simple example of creating a custom metric that checks if the output contains certain words, see our [Word Inclusion example](/examples/evals/word-inclusion).
+
+## Creating a custom LLM-Judge
+
+A custom LLM judge helps evaluate specific aspects of your AI's responses. Think of it like having an expert reviewer for your particular use case:
+
+- Medical Q&A → Judge checks for medical accuracy and safety
+- Customer Service → Judge evaluates tone and helpfulness
+- Code Generation → Judge verifies code correctness and style
+
+For a practical example, see how we evaluate [Chef Michel's](/docs/guides/chef-michel) recipes for gluten content in our [Gluten Checker example](/examples/evals/custom-eval).

package/.docs/raw/evals/overview.mdx

@@ -0,0 +1,95 @@
+---
+title: "Overview"
+description: "Understanding how to evaluate and measure AI agent quality using Mastra evals."
+---
+
+# Testing your agents with evals
+
+While traditional software tests have clear pass/fail conditions, AI outputs are non-deterministic — they can vary with the same input. Evals help bridge this gap by providing quantifiable metrics for measuring agent quality.
+
+Evals are automated tests that evaluate Agents outputs using model-graded, rule-based, and statistical methods. Each eval returns a normalized score between 0-1 that can be logged and compared. Evals can be customized with your own prompts and scoring functions.
+
+Evals can be run in the cloud, capturing real-time results. But evals can also be part of your CI/CD pipeline, allowing you to test and monitor your agents over time.
+
+## Types of Evals
+
+There are different kinds of evals, each serving a specific purpose. Here are some common types:
+
+1. **Textual Evals**: Evaluate accuracy, reliability, and context understanding of agent responses
+2. **Classification Evals**: Measure accuracy in categorizing data based on predefined categories
+3. **Tool Usage Evals**: Assess how effectively an agent uses external tools or APIs
+4. **Prompt Engineering Evals**: Explore impact of different instructions and input formats
+
+## Getting Started
+
+Evals need to be added to an agent. Here's an example using the summarization, content similarity, and tone consistency metrics:
+
+```typescript copy showLineNumbers filename="src/mastra/agents/index.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { SummarizationMetric } from "@mastra/evals/llm";
+import {
+  ContentSimilarityMetric,
+  ToneConsistencyMetric,
+} from "@mastra/evals/nlp";
+
+const model = openai("gpt-4o");
+
+export const myAgent = new Agent({
+  name: "ContentWriter",
+  instructions: "You are a content writer that creates accurate summaries",
+  model,
+  evals: {
+    summarization: new SummarizationMetric(model),
+    contentSimilarity: new ContentSimilarityMetric(),
+    tone: new ToneConsistencyMetric(),
+  },
+});
+```
+
+You can view eval results in the Mastra dashboard when using `mastra dev`.
+
+## Beyond Automated Testing
+
+While automated evals are valuable, high-performing AI teams often combine them with:
+
+1. **A/B Testing**: Compare different versions with real users
+2. **Human Review**: Regular review of production data and traces
+3. **Continuous Monitoring**: Track eval metrics over time to detect regressions
+
+## Understanding Eval Results
+
+Each eval metric measures a specific aspect of your agent's output. Here's how to interpret and improve your results:
+
+### Understanding Scores
+
+For any metric:
+
+1. Check the metric documentation to understand the scoring process
+2. Look for patterns in when scores change
+3. Compare scores across different inputs and contexts
+4. Track changes over time to spot trends
+
+### Improving Results
+
+When scores aren't meeting your targets:
+
+1. Check your instructions - Are they clear? Try making them more specific
+2. Look at your context - Is it giving the agent what it needs?
+3. Simplify your prompts - Break complex tasks into smaller steps
+4. Add guardrails - Include specific rules for tricky cases
+
+### Maintaining Quality
+
+Once you're hitting your targets:
+
+1. Monitor stability - Do scores remain consistent?
+2. Document what works - Keep notes on successful approaches
+3. Test edge cases - Add examples that cover unusual scenarios
+4. Fine-tune - Look for ways to improve efficiency
+
+See [Textual Evals](/docs/evals/textual-evals) for more info on what evals can do.
+
+For more info on how to create your own evals, see the [Custom Evals](/docs/evals/custom-eval) guide.
+
+For running evals in your CI pipeline, see the [Running in CI](/docs/evals/running-in-ci) guide.

package/.docs/raw/evals/running-in-ci.mdx

@@ -0,0 +1,81 @@
+---
+title: "Running in CI"
+description: "Learn how to run Mastra evals in your CI/CD pipeline to monitor agent quality over time."
+---
+
+# Running Evals in CI
+
+Running evals in your CI pipeline helps bridge this gap by providing quantifiable metrics for measuring agent quality over time.
+
+## Setting Up CI Integration
+
+We support any testing framework that supports ESM modules. For example, you can use [Vitest](https://vitest.dev/), [Jest](https://jestjs.io/) or [Mocha](https://mochajs.org/) to run evals in your CI/CD pipeline.
+
+```typescript copy showLineNumbers filename="src/mastra/agents/index.test.ts"
+import { describe, it, expect } from 'vitest';
+import { evaluate } from "@mastra/evals";
+import { ToneConsistencyMetric } from "@mastra/evals/nlp";
+import { myAgent } from './index';
+
+describe('My Agent', () => {
+  it('should validate tone consistency', async () => {
+    const metric = new ToneConsistencyMetric();
+    const result = await evaluate(myAgent, 'Hello, world!', metric)
+
+    expect(result.score).toBe(1);
+  });
+});
+```
+
+You will need to configure a testSetup and globalSetup script for your testing framework to capture the eval results. It allows us to show these results in your mastra dashboard.
+
+## Framework Configuration
+
+### Vitest Setup
+
+Add these files to your project to run evals in your CI/CD pipeline:
+
+```typescript copy showLineNumbers filename="globalSetup.ts"
+import { globalSetup } from '@mastra/evals';
+
+export default function setup() {
+  globalSetup()
+}
+```
+
+```typescript copy showLineNumbers filename="testSetup.ts"
+import { beforeAll } from 'vitest';
+import { attachListeners } from '@mastra/evals';
+
+beforeAll(async () => {
+  await attachListeners();
+});
+```
+
+```typescript copy showLineNumbers filename="vitest.config.ts"
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globalSetup: './globalSetup.ts',
+    setupFiles: ['./testSetup.ts'],
+  },
+})
+```
+
+## Storage Configuration
+
+To store eval results in Mastra Storage and capture results in the Mastra dashboard:
+
+```typescript copy showLineNumbers filename="testSetup.ts"
+import { beforeAll } from 'vitest';
+import { attachListeners } from '@mastra/evals';
+import { mastra } from './your-mastra-setup';
+
+beforeAll(async () => {
+  // Store evals in Mastra Storage (requires storage to be enabled)
+  await attachListeners(mastra);
+});
+```
+
+With file storage, evals persist and can be queried later. With memory storage, evals are isolated to the test process.

package/.docs/raw/evals/textual-evals.mdx

@@ -0,0 +1,54 @@
+---
+title: "Textual Evals"
+description: "Understand how Mastra uses LLM-as-judge methodology to evaluate text quality."
+---
+
+# Textual Evals
+
+Textual evals use an LLM-as-judge methodology to evaluate agent outputs. This approach leverages language models to assess various aspects of text quality, similar to how a teaching assistant might grade assignments using a rubric.
+
+Each eval focuses on specific quality aspects and returns a score between 0 and 1, providing quantifiable metrics for non-deterministic AI outputs.
+
+Mastra provides several eval metrics for assessing Agent outputs. Mastra is not limited to these metrics, and you can also [define your own evals](/docs/evals/custom-eval).
+
+## Why Use Textual Evals?
+
+Textual evals help ensure your agent:
+
+- Produces accurate and reliable responses
+- Uses context effectively
+- Follows output requirements
+- Maintains consistent quality over time
+
+## Available Metrics
+
+### Accuracy and Reliability
+
+These metrics evaluate how correct, truthful, and complete your agent's answers are:
+
+- [`hallucination`](/docs/reference/evals/hallucination): Detects facts or claims not present in provided context
+- [`faithfulness`](/docs/reference/evals/faithfulness): Measures how accurately responses represent provided context
+- [`content-similarity`](/docs/reference/evals/content-similarity): Evaluates consistency of information across different phrasings
+- [`completeness`](/docs/reference/evals/completeness): Checks if responses include all necessary information
+- [`answer-relevancy`](/docs/reference/evals/answer-relevancy): Assesses how well responses address the original query
+- [`textual-difference`](/docs/reference/evals/textual-difference): Measures textual differences between strings
+
+### Understanding Context
+
+These metrics evaluate how well your agent uses provided context:
+
+- [`context-position`](/docs/reference/evals/context-position): Analyzes where context appears in responses
+- [`context-precision`](/docs/reference/evals/context-precision): Evaluates whether context chunks are grouped logically
+- [`context-relevancy`](/docs/reference/evals/context-relevancy): Measures use of appropriate context pieces
+- [`contextual-recall`](/docs/reference/evals/contextual-recall): Assesses completeness of context usage
+
+### Output Quality
+
+These metrics evaluate adherence to format and style requirements:
+
+- [`tone`](/docs/reference/evals/tone-consistency): Measures consistency in formality, complexity, and style
+- [`toxicity`](/docs/reference/evals/toxicity): Detects harmful or inappropriate content
+- [`bias`](/docs/reference/evals/bias): Detects potential biases in the output
+- [`prompt-alignment`](/docs/reference/evals/prompt-alignment): Checks adherence to explicit instructions like length restrictions, formatting requirements, or other constraints
+- [`summarization`](/docs/reference/evals/summarization): Evaluates information retention and conciseness
+- [`keyword-coverage`](/docs/reference/evals/keyword-coverage): Assesses technical terminology usage