@mastra/mcp-docs-server 0.13.6 → 0.13.7-alpha.1

package/.docs/organized/code-examples/openapi-spec-writer.md

@@ -37,7 +37,7 @@
     "eslint-config-next": "15.3.5",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   },
   "peerDependencies": {
     "react": ">= 0.14.0 || 19",

package/.docs/organized/code-examples/quick-start.md

@@ -5,7 +5,7 @@
   "devDependencies": {
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-ai-recruiter.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-inline-steps.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-memory.md

@@ -5,7 +5,7 @@
   "devDependencies": {
     "@types/node": "^20.17.57",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-separate-steps.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/organized/code-examples/workflow-with-suspend-resume.md

@@ -6,7 +6,7 @@
     "@types/node": "^20.17.57",
     "mastra": "latest",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "zod": "^3.25.67"
   },
   "dependencies": {

package/.docs/raw/agents/runtime-variables.mdx

@@ -23,7 +23,7 @@ const agent = mastra.getAgent("weatherAgent");
 
 // Define your runtimeContext's type structure
 type WeatherRuntimeContext = {
-  "temperature-scale": "celsius" | "fahrenheit"; // Fixed typo in "fahrenheit"
+  "temperature-scale": "celsius" | "fahrenheit";
 };
 
 const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();

package/.docs/raw/auth/index.mdx

@@ -0,0 +1,24 @@
+---
+title: Auth Overview
+description: Learn about different Auth options for your Mastra applications
+---
+
+# Auth Overview
+
+Mastra lets you choose how you handle authentication, so you can secure access to your application's endpoints using the identity system that fits your stack.
+
+You can start with simple shared secret JWT authentication and switch to providers like Supabase, Firebase Auth, Auth0, Clerk, or WorkOS when you need more advanced identity features.
+
+## Available providers
+
+- [JSON Web Token (JWT)](/docs/auth/jwt)
+
+### Coming soon
+
+The following providers will be available soon:
+
+- Supabase Auth
+- Firebase Auth
+- Auth0
+- Clerk
+- WorkOS

package/.docs/raw/auth/jwt.mdx

@@ -0,0 +1,99 @@
+---
+title: "MastraJwtAuth"
+description: "Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# MastraJwtAuth
+
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `experimental_auth` option.
+
+## Installation
+
+```bash copy
+npm install @mastra/auth
+```
+
+## Usage example
+
+```typescript {2,7-9} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraJwtAuth } from '@mastra/auth';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraJwtAuth({
+        secret: process.env.MASTRA_JWT_SECRET
+    }),
+  },
+});
+```
+
+> See the [MastraJwtAuth](/reference/auth/jwt.mdx) API reference for all available configuration options.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid JWT in the `Authorization` header:
+
+```typescript {6} filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`
+  }
+});
+```
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client.mdx) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured, you can send authenticated requests from your frontend application, or use `curl` for quick local testing:
+
+<Tabs items={["MastraClient", "curl"]}>
+  <Tab>
+    ```tsx filename="src/components/test-agent.tsx" showLineNumbers copy
+    import { mastraClient } from "../../lib/mastra-client";
+
+    export const TestAgent = () => {
+      async function handleClick() {
+        const agent = mastraClient.getAgent("weatherAgent");
+
+        const response = await agent.generate({
+          messages: "Weather in London"
+        });
+
+        console.log(response);
+      }
+
+      return <button onClick={handleClick}>Test Agent</button>;
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer <your-jwt>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a JWT
+
+To authenticate requests to your Mastra server, you'll need a valid JSON Web Token (JWT) signed with your `MASTRA_JWT_SECRET`.
+
+The easiest way to generate one is using [jwt.io](https://www.jwt.io/):
+
+1. Select **JWT Encoder**.
+2. Scroll down to the **Sign JWT: Secret** section.
+3. Enter your secret (for example: `supersecretdevkeythatishs256safe!`).
+4. Click **Generate example** to create a valid JWT.
+5. Copy the generated token and set it as `MASTRA_JWT_TOKEN` in your `.env` file.

package/.docs/raw/community/contributing-templates.mdx

@@ -0,0 +1,192 @@
+---
+title: "Contributing Templates"
+description: "How to contribute your own templates to the Mastra ecosystem"
+---
+
+import { Callout } from "nextra/components";
+
+# Contributing Templates
+
+The Mastra community plays a vital role in creating templates that showcase innovative application patterns. This guide explains how to contribute your own templates to the Mastra ecosystem.
+
+## Template Contribution Process
+
+### 1. Review Requirements
+
+Before creating a template, ensure you understand:
+
+- [Templates Reference](/reference/templates) - Technical requirements and conventions
+- [Project Structure](/docs/getting-started/project-structure) - Standard Mastra project organization
+- Community guidelines and quality standards
+
+### 2. Develop Your Template
+
+Create your template following the established patterns:
+
+- Focus on a specific use case or pattern
+- Include comprehensive documentation
+- Test thoroughly with fresh installations
+- Follow all technical requirements
+
+### 3. Submit for Review
+
+Once your template is ready, submit it through our contribution form. Templates undergo an approval process to ensure quality and consistency.
+
+## Submission Guidelines
+
+### Template Criteria
+
+We accept templates that:
+
+- **Demonstrate unique value** - Show innovative use cases or patterns not covered by existing templates
+- **Follow conventions** - Adhere to all technical requirements and structural guidelines
+- **Include quality documentation** - Provide clear setup instructions and usage examples
+- **Work reliably** - Function correctly with minimal setup after installation
+
+### Quality Standards
+
+Templates must meet these quality benchmarks:
+
+- **Code quality** - Clean, well-commented, and maintainable code
+- **Error handling** - Proper error handling for external APIs and user inputs
+- **Type safety** - Full TypeScript typing with Zod validation where appropriate
+- **Documentation** - Comprehensive README with setup and usage instructions
+- **Testing** - Verified to work with fresh installations
+
+## Submission Process
+
+### 1. Prepare Your Template
+
+Ensure your template meets all requirements outlined in the [Templates Reference](/reference/templates):
+
+- Proper project structure in `src/mastra/` directory
+- Standard TypeScript configuration
+- Comprehensive `.env.example` file
+- Detailed README with setup instructions
+
+### 2. Submit Your Template
+
+Submit your template using our contribution form:
+
+**[Submit Template Contribution](https://forms.gle/5qcU5UTKYcgFdVfE7)**
+
+### Required Information
+
+When submitting your template, provide:
+
+- **Template Name** - Clear, descriptive name indicating the use case
+- **Template Author Name** - Your name or organization name
+- **Template Author Email** - Contact email for communication about your submission
+- **GitHub URL** - Link to your template repository
+- **Description** - Detailed explanation of what the template does and its value
+- **Optional Image** - Screenshot or diagram showing the template in action
+- **Optional Demo Video** - Link to a video demonstrating the template's functionality
+
+## Review Process
+
+### Review Criteria
+
+Templates are evaluated on:
+
+- **Technical compliance** - Adherence to template rules and conventions
+- **Code quality** - Clean, maintainable, and well-documented code
+- **Uniqueness** - Novel use cases or innovative implementation patterns
+- **Educational value** - Ability to teach Mastra concepts effectively
+- **Community benefit** - Potential value to the broader Mastra community
+
+### Feedback and Iteration
+
+If your template needs improvements:
+
+- You'll receive specific feedback on required changes
+- Make the requested modifications and resubmit
+- The review process continues until the template meets standards
+
+## Community Guidelines
+
+### Template Ideas
+
+Consider creating templates for:
+
+- **Industry-specific use cases** - Healthcare, finance, education, etc.
+- **Integration patterns** - Specific API or service integrations
+- **Advanced techniques** - Complex workflows, multi-agent systems, or novel patterns
+- **Learning resources** - Step-by-step tutorials for specific concepts
+
+### Development Best Practices
+
+- **Start simple** - Begin with a minimal working example and add complexity gradually
+- **Document thoroughly** - Include detailed comments and comprehensive README
+- **Test extensively** - Verify your template works across different environments
+- **Seek feedback** - Share with the community for early feedback before submission
+
+### Community Engagement
+
+- **Join Discord** - Participate in the [Mastra Discord community](https://discord.gg/BTYqqHKUrf)
+- **Share progress** - Update the community on your template development
+- **Help others** - Assist other contributors with their templates
+- **Stay updated** - Keep track of new Mastra features and conventions
+
+## Template Maintenance
+
+### Ongoing Responsibilities
+
+As a template contributor, you may be asked to:
+
+- **Update dependencies** - Keep templates current with latest Mastra versions
+- **Fix issues** - Address bugs or compatibility problems
+- **Improve documentation** - Enhance instructions based on user feedback
+- **Add features** - Extend templates with new capabilities
+
+### Community Support
+
+The Mastra team and community provide:
+
+- **Technical guidance** - Help with complex implementation challenges
+- **Review feedback** - Detailed feedback to improve template quality
+- **Promotion** - Showcase approved templates to the community
+- **Maintenance assistance** - Support for keeping templates up-to-date
+
+## Validation Checklist
+
+Before submitting a template, verify:
+
+- [ ] All code organized in `src/mastra/` directory
+- [ ] Uses standard Mastra TypeScript configuration
+- [ ] Includes comprehensive `.env.example`
+- [ ] Has detailed README with setup instructions
+- [ ] No monorepo or web framework boilerplate
+- [ ] Successfully runs after fresh install and environment setup
+- [ ] Follows all code quality standards
+- [ ] Demonstrates clear, valuable use case
+
+## Community Showcase
+
+### Template Gallery
+
+Approved templates will be featured in:
+
+- **mastra.ai/templates** - Community template gallery (coming soon)
+- **Documentation** - Referenced in relevant documentation sections
+- **Community highlights** - Featured in newsletters and community updates
+
+### Recognition
+
+Template contributors receive:
+
+- **Attribution** - Your name and contact information with the template
+- **Community recognition** - Acknowledgment in community channels
+
+## Getting Started
+
+Ready to contribute a template?
+
+1. **Explore existing templates** - Review current templates for inspiration and patterns
+2. **Plan your template** - Define the use case and value proposition
+3. **Follow the requirements** - Ensure compliance with all technical requirements
+4. **Build and test** - Create a working, well-documented template
+5. **Submit for review** - Use the contribution form to submit your template
+
+<Callout type="info">
+Your contributions help grow the Mastra ecosystem and provide valuable resources for the entire community. We look forward to seeing your innovative templates!
+</Callout>

package/.docs/raw/deployment/cloud-providers/azure-app-services.mdx

@@ -18,8 +18,8 @@ Deploy your Mastra applications to Azure App Services.
 
 ### Prerequisites
 
-- An Azure account with an active subscription
-- A GitHub repository containing your Mastra application
+- An [Azure account](https://azure.microsoft.com/) with an active subscription
+- A [GitHub repository](https://github.com/) containing your Mastra application
 - Your Mastra application should be created using `npx create-mastra@latest`
 
 ### Deployment Steps
@@ -29,7 +29,7 @@ Deploy your Mastra applications to Azure App Services.
 #### Create a new App Service
 
 - Log in to the [Azure Portal](https://portal.azure.com)
-- Navigate to **App Services** or search for it in the top search bar
+- Navigate to **[App Services](https://docs.microsoft.com/en-us/azure/app-service/)** or search for it in the top search bar
 - Click **Create** to create a new App Service
 - In the drop-down, select **Web App**
 
@@ -67,7 +67,7 @@ Before setting up deployment, configure your environment variables:
 - Navigate to **Deployment Center** in the left sidebar
 - Select **GitHub** as your source
 - Sign in to GitHub if you're not already authenticated with Azure
-- In this example, we will keep GitHub Actions as our provider.
+- In this example, we will keep [GitHub Actions](https://docs.github.com/en/actions) as our provider
 - Select your organization, repository, and branch
 - Azure will generate a GitHub workflow file and you can preview it before proceeding
 - Click **Save** (the save button is located at the top of the page)
@@ -84,7 +84,7 @@ Pull the latest changes to your local repository and modify the generated workfl
 
 1. **Update the build step**: Find the step named "npm install, build, and test" and:
    - Change the step name to "npm install and build"
-   - Remove the `npm test` command from the run section
+   - If you haven't set up proper tests in your Mastra application, remove the `npm test` command from the run section as the default test script will fail and disrupt deployment. If you have working tests, you can keep the test command.
 
 2. **Update the zip artifact step**: Find the "Zip artifact for deployment" step and replace the zip command with:
 
@@ -133,4 +133,5 @@ such as `LibSQLStore` with a file URL. Consider using cloud-based storage soluti
 - [Mastra Client SDK](/docs/client-js/overview)
 - [Configure custom domains](https://docs.microsoft.com/en-us/azure/app-service/app-service-web-tutorial-custom-domain)
 - [Enable HTTPS](https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-bindings)
+- [Azure App Service documentation](https://docs.microsoft.com/en-us/azure/app-service/)
 

package/.docs/raw/deployment/cloud-providers/digital-ocean.mdx

@@ -4,7 +4,6 @@ description: "Deploy your Mastra applications to Digital Ocean."
 ---
 
 import { Callout, Steps, Tabs } from "nextra/components";
-import ServerConfig from "@/components/content-blocks/server-config.mdx";
 
 ## Digital Ocean
 
@@ -25,8 +24,8 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 
 #### Prerequisites [#app-platform-prerequisites]
 
-- A Git repository containing your Mastra application. This can be a GitHub repository, GitLab repository, or any other compatible source provider.
-- A Digital Ocean account
+- A Git repository containing your Mastra application. This can be a [GitHub](https://github.com/) repository, [GitLab](https://gitlab.com/) repository, or any other compatible source provider.
+- A [Digital Ocean account](https://www.digitalocean.com/)
 
 #### Deployment Steps
 
@@ -34,8 +33,8 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 
 #### Create a new App
 
-- Log in to your Digital Ocean dashboard.
-- Navigate to the App Platform service.
+- Log in to your [Digital Ocean dashboard](https://cloud.digitalocean.com/).
+- Navigate to the [App Platform](https://docs.digitalocean.com/products/app-platform/) service.
 - Select your source provider and create a new app.
 
 #### Configure Deployment Source
@@ -76,21 +75,86 @@ such as `LibSQLStore` with a file URL.
 ### Droplets
 
 Deploy your Mastra application to Digital Ocean's Droplets.
-This guide will cover setting up a droplet, a reverse proxy using Nginx, and running your Mastra application.
-
-<Callout>
-The guide assumes your droplet runs Ubuntu 24+.
-</Callout>
 
 #### Prerequisites [#droplets-prerequisites]
 
-- A Digital Ocean account
-- A droplet running Ubuntu 24+
+- A [Digital Ocean account](https://www.digitalocean.com/)
+- A [Droplet](https://docs.digitalocean.com/products/droplets/) running Ubuntu 24+
 - A domain name with an A record pointing to your droplet
+- A reverse proxy configured (e.g., using [nginx](https://nginx.org/))
+- SSL certificate configured (e.g., using [Let's Encrypt](https://letsencrypt.org/))
+- Node.js 18+ installed on your droplet
+
+#### Deployment Steps
+
+<Steps>
+
+#### Clone your Mastra application
+
+Connect to your Droplet and clone your repository:
+
+<Tabs items={["Public Repository", "Private Repository"]}>
+<Tabs.Tab>
+
+```bash copy
+git clone https://github.com/<your-username>/<your-repository>.git
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```bash copy
+git clone https://<your-username>:<your-personal-access-token>@github.com/<your-username>/<your-repository>.git
+```
+
+</Tabs.Tab>
+</Tabs>
+
+Navigate to the repository directory:
 
-#### Setting up the droplet
+```bash copy
+cd "<your-repository>"
+```
+
+#### Install dependencies
+
+```bash copy
+npm install
+```
+
+#### Set up environment variables
+
+Create a `.env` file and add your environment variables:
 
-<ServerConfig />
+```bash copy
+touch .env
+```
+
+Edit the `.env` file and add your environment variables:
+
+```bash copy
+OPENAI_API_KEY=<your-openai-api-key>
+# Add other required environment variables
+```
+
+#### Build the application
+
+```bash copy
+npm run build
+```
+
+#### Run the application
+
+```bash copy
+node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
+```
+
+<Callout>
+Your Mastra application will run on port 4111 by default. Ensure your reverse proxy is configured to forward requests to this port.
+</Callout>
+
+</Steps>
 
 </Tabs.Tab>
 
@@ -109,3 +173,9 @@ const mastraClient = new MastraClient({
   baseUrl: "https://<your-domain-name>",
 });
 ```
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)
+- [Digital Ocean App Platform documentation](https://docs.digitalocean.com/products/app-platform/)
+- [Digital Ocean Droplets documentation](https://docs.digitalocean.com/products/droplets/)

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

@@ -1,22 +1,22 @@
 ---
-title: "Create your own Eval"
-description: "Mastra allows so create your own evals, here is how."
+title: "Create a custom eval"
+description: "Mastra allows you to create your own evals, here is how."
 ---
 
-# Create your own Eval
+# Create a Custom 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.
+Create a custom eval by extending the `Metric` class and implementing the `measure` method. This gives you full control over how scores are calculated and what information is returned. For LLM-based evaluations, extend the `MastraAgentJudge` class to define how the model reasons and scores output.
 
-## Basic example
+## Native JavaScript evaluation
 
-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).
+You can write lightweight custom metrics using plain JavaScript/TypeScript. These are ideal for simple string comparisons, pattern checks, or other rule-based logic.
 
-## Creating a custom LLM-Judge
+See our [Word Inclusion example](/examples/evals/custom-native-javascript-eval.mdx), which scores responses based on the number of reference words found in the output.
 
-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:
+## LLM as a judge evaluation
+
+For more complex evaluations, you can build a judge powered by an LLM. This lets you capture more nuanced criteria, like factual accuracy, tone, or reasoning.
+
+See the [Real World Countries example](/examples/evals/custom-llm-judge-eval.mdx) for a complete walkthrough of building a custom judge and metric that evaluates real-world factual accuracy.
 
-- 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/getting-started/installation.mdx

@@ -68,6 +68,22 @@ You can also run the Mastra CLI in non-interactive mode by passing all required
 npx create-mastra@latest --project-name hello-mastra --example --components tools,agents,workflows --llm openai
 ```
 
+**Install with a template**
+
+Start with a pre-built template that demonstrates specific use cases:
+
+```bash copy
+npx create-mastra@latest --template template-name
+```
+
+For example, to create a text-to-SQL application:
+
+```bash copy
+npx create-mastra@latest --template text-to-sql
+```
+
+> Browse available templates and learn more in [Templates](/docs/getting-started/templates).
+
 > See the [create-mastra](/reference/cli/create-mastra) documentation for a full list of available CLI options.
 
 ### Add your API key