@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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

@@ -0,0 +1,120 @@
+---
+title: "MastraClient"
+description: "Learn how to set up and use the Mastra Client SDK"
+---
+
+# Mastra Client SDK
+
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/deployment/server) from your client environment.
+
+## Development Requirements
+
+To ensure smooth local development, make sure you have:
+
+- Node.js 18.x or later installed
+- TypeScript 4.7+ (if using TypeScript)
+- A modern browser environment with Fetch API support
+- Your local Mastra server running (typically on port 4111)
+
+## Installation
+
+import { Tabs } from "nextra/components";
+
+<Tabs items={["npm", "yarn", "pnpm"]}>
+  <Tabs.Tab>
+```bash copy
+npm install @mastra/client-js
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+yarn add @mastra/client-js
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash copy
+pnpm add @mastra/client-js
+```
+  </Tabs.Tab>
+</Tabs>
+
+## Initialize Mastra Client
+
+To get started you'll need to initialize your MastraClient with necessary parameters:
+
+```typescript
+import { MastraClient } from "@mastra/client-js";
+
+const client = new MastraClient({
+  baseUrl: "http://localhost:4111", // Default Mastra development server port
+});
+```
+
+### Configuration Options
+
+You can customize the client with various options:
+
+```typescript
+const client = new MastraClient({
+  // Required
+  baseUrl: "http://localhost:4111",
+
+  // Optional configurations for development
+  retries: 3,           // Number of retry attempts
+  backoffMs: 300,       // Initial retry backoff time
+  maxBackoffMs: 5000,   // Maximum retry backoff time
+  headers: {            // Custom headers for development
+    "X-Development": "true"
+  }
+});
+```
+
+## Example
+
+Once your MastraClient is initialized you can start making client calls via the type-safe
+interface
+
+```typescript
+// Get a reference to your local agent
+const agent = client.getAgent("dev-agent-id");
+
+// Generate responses
+const response = await agent.generate({
+  messages: [
+    {
+      role: "user",
+      content: "Hello, I'm testing the local development setup!"
+    }
+  ]
+});
+```
+
+## Available Features
+
+Mastra client exposes all resources served by the Mastra Server
+
+- [**Agents**](/reference/client-js/agents): Create and manage AI agents, generate responses, and handle streaming interactions
+- [**Memory**](/reference/client-js/memory): Manage conversation threads and message history
+- [**Tools**](/reference/client-js/tools): Access and execute tools available to agents
+- [**Workflows**](/reference/client-js/workflows): Create and manage automated workflows
+- [**Vectors**](/reference/client-js/vectors): Handle vector operations for semantic search and similarity matching
+
+
+## Best Practices
+1. **Error Handling**: Implement proper error handling for development scenarios
+2. **Environment Variables**: Use environment variables for configuration
+3. **Debugging**: Enable detailed logging when needed
+
+```typescript
+// Example with error handling and logging
+try {
+  const agent = client.getAgent("dev-agent-id");
+  const response = await agent.generate({
+    messages: [{ role: "user", content: "Test message" }]
+  });
+  console.log("Response:", response);
+} catch (error) {
+  console.error("Development error:", error);
+}
+```
+

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

@@ -0,0 +1,127 @@
+---
+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](/reference/deployer/cloudflare)**
+- **[Vercel](/reference/deployer/vercel)**
+- **[Netlify](/reference/deployer/netlify)**
+
+As of April 2025, Mastra also offers [Mastra Cloud](https://mastra.ai/cloud-beta), a serverless agent environment with atomic deployments. You can sign up for the waitlist [here](https://mastra.ai/cloud-beta).
+
+### 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 →](/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 →](/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 →](/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)
+
+## Build Mastra Project
+
+To build your Mastra project for your target platform run:
+
+```bash
+npx mastra build
+```
+
+When a Deployer is used, the build output is automatically prepared for the target platform.
+You can then deploy the build output `.mastra/output` via your platform's (Vercel, netlify, cloudfare e.t.c) 
+CLI/UI.
+

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

@@ -0,0 +1,282 @@
+---
+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 on 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/\*')
+- Inject request specific data for agent tool calling or workflows
+
+### 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`](/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.