@mastra/mcp-docs-server 0.0.1 → 0.0.2

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

@@ -10,178 +10,14 @@ Creating your own eval is as easy as creating a new function. You simply create
 
 ## Basic example 
 
-Here is a very basic example of a custom eval that checks if the output contains a certain keyword. This is a simplified version of our own [keyword coverage eval](/docs/reference/evals/keyword-coverage).
-
-
-```typescript copy showLineNumbers filename="src/mastra/evals/keyword-coverage.ts"
-import { Metric, type MetricResult } from '@mastra/core/eval';
-
-interface KeywordCoverageResult extends MetricResult {
-  info: {
-    totalKeywords: number;
-    matchedKeywords: number;
-  };
-}
-
-export class KeywordCoverageMetric extends Metric {
-  private referenceKeywords: Set<string>;
-
-  constructor(keywords: string[]) {
-    super();
-    this.referenceKeywords = new Set(keywords);
-  }
-
-  async measure(input: string, output: string): Promise<KeywordCoverageResult> {
-    // Handle empty strings case
-    if (!input && !output) {
-      return {
-        score: 1,
-        info: {
-          totalKeywords: 0,
-          matchedKeywords: 0,
-        },
-      };
-    }
-
-    const matchedKeywords = [...this.referenceKeywords].filter(k => output.includes(k));
-    const totalKeywords = this.referenceKeywords.size;
-    const coverage = totalKeywords > 0 ? matchedKeywords.length / totalKeywords : 0;
-
-    return {
-      score: coverage,
-      info: {
-        totalKeywords: this.referenceKeywords.size,
-        matchedKeywords: matchedKeywords.length,
-      },
-    };
-  }
-}
-```
+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 can provide more targeted and meaningful evaluations for your use case. For example, if you're building a medical Q&A system, you might want to evaluate not just answer relevancy but also medical accuracy and safety considerations.
-
-Let's create an example to make sure our [Chef Michel](/docs/guides/01-chef-michel) is giving complete recipe information to the user.
-
-We'll start with creating the judge agent. You can put it all in one file but we prefer splitting it into a separate file to keep things readable.
-
-```typescript copy showLineNumbers filename="src/mastra/evals/recipe-completeness/metricJudge.ts"
-import { type LanguageModel } from '@mastra/core/llm';
-import { MastraAgentJudge } from '@mastra/evals/judge';
-import { z } from 'zod';
-
-import { RECIPE_COMPLETENESS_INSTRUCTIONS, generateCompletenessPrompt, generateReasonPrompt } from './prompts';
-
-export class RecipeCompletenessJudge extends MastraAgentJudge {
-  constructor(model: LanguageModel) {
-    super('Recipe Completeness', RECIPE_COMPLETENESS_INSTRUCTIONS, model);
-  }
-
-  async evaluate(
-    input: string,
-    output: string,
-  ): Promise<{
-    missing: string[];
-    verdict: string;
-  }> {
-    const completenessPrompt = generateCompletenessPrompt({ input, output });
-    const result = await this.agent.generate(completenessPrompt, {
-      output: z.object({
-        missing: z.array(z.string()),
-        verdict: z.string(),
-      }),
-    });
-
-    return result.object;
-  }
-
-  async getReason(args: {
-    input: string;
-    output: string;
-    missing: string[];
-    verdict: string;
-  }): Promise<string> {
-    const prompt = generateReasonPrompt(args);
-    const result = await this.agent.generate(prompt, {
-      output: z.object({
-        reason: z.string(),
-      }),
-    });
-
-    return result.object.reason;
-  }
-}
-```
-```typescript copy showLineNumbers filename="src/mastra/evals/recipe-completeness/index.ts"
-import { Metric, type MetricResult } from '@mastra/core/eval';
-import { type LanguageModel } from '@mastra/core/llm';
-
-import { RecipeCompletenessJudge } from './metricJudge';
-
-export interface RecipeCompletenessMetricOptions {
-  scale?: number;
-}
-
-export interface MetricResultWithInfo extends MetricResult {
-  info: {
-    reason: string;
-    missing: string[];
-  };
-}
-
-export class RecipeCompletenessMetric extends Metric {
-  private judge: RecipeCompletenessJudge;
-  private scale: number;
-  constructor(model: LanguageModel, { scale = 1 }: RecipeCompletenessMetricOptions = {}) {
-    super();
-
-    this.judge = new RecipeCompletenessJudge(model);
-    this.scale = scale;
-  }
-
-  async measure(input: string, output: string): Promise<MetricResultWithInfo> {
-    const { verdict, missing } = await this.judge.evaluate(input, output);
-    const score = this.calculateScore({ verdict });
-    const reason = await this.judge.getReason({
-      input,
-      output,
-      verdict,
-      missing,
-    });
-
-    return {
-      score,
-      info: {
-        missing,
-        reason,
-      },
-    };
-  }
-
-  private calculateScore(verdict: { verdict: string }): number {
-    return verdict.verdict.toLowerCase() === 'incomplete' ? 0 : 1;
-  }
-}
-```
-
-```typescript copy showLineNumbers filename="src/mastra/agents/chefAgent.ts"
-import { openai } from '@ai-sdk/openai';
-import { Agent } from '@mastra/core/agent';
-
-import { RecipeCompletenessMetric } from '../evals';
-
-export const chefAgent = new Agent({
-  name: 'chef-agent',
-  instructions:
-    'You are Michel, a practical and experienced home chef' +
-    'You help people cook with whatever ingredients they have available.',
-  model: openai('gpt-4o-mini'),
-  evals: {
-    recipeCompleteness: new RecipeCompletenessMetric(openai('gpt-4o-mini')),
-  },
-});
-```
+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:
 
-You can now use the `RecipeCompletenessMetric` in your project. [See the full example here](/examples/evals/custom-eval).
+- 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/01-chef-michel) recipes for gluten content in our [Gluten Checker example](/examples/evals/custom-eval).

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

@@ -0,0 +1,78 @@
+---
+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/core/eval';
+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 and capture results in the Mastra dashboard:
+
+```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:
+
+```typescript
+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/getting-started/installation.mdx

@@ -36,17 +36,17 @@ npx create-mastra@latest
   </Tabs.Tab>
   <Tabs.Tab>
 ```bash copy
-npm create mastra
+npm create mastra@latest
 ```
   </Tabs.Tab>
   <Tabs.Tab>
 ```bash copy
-yarn create mastra
+yarn create mastra@latest
 ```
 </Tabs.Tab>
   <Tabs.Tab>
 ```bash copy
-pnpm create mastra
+pnpm create mastra@latest
 ```
 </Tabs.Tab>
 </Tabs>
@@ -64,9 +64,20 @@ Select default provider:
   ◯ Anthropic
   ◯ Groq
 Would you like to include example code? No / Yes
+Turn your IDE into a Mastra expert? (Installs MCP server)
+  ◯ Skip for now
+  ◯ Cursor
+  ◯ Windsurf
 ```
 
-After the prompts, `create-mastra` will set up your project directory with TypeScript, install dependencies, and configure your selected components and LLM provider.
+After the prompts, `create-mastra` will:
+
+1. Set up your project directory with TypeScript
+2. Install dependencies
+3. Configure your selected components and LLM provider
+4. Configure the MCP server in your IDE (if selected) for instant access to docs, examples, and help while you code
+
+**MCP Note:** If you're using a different IDE, you can install the MCP server manually by following the instructions in the [MCP server docs](/docs/getting-started/mcp-docs-server). **Also** note that there are additional steps for [Cursor and Windsurf](/docs/getting-started/mcp-docs-server#after-configuration) to activate the MCP server.
 
 ### Set Up your API Key
 
@@ -77,19 +88,19 @@ OPENAI_API_KEY=<your-openai-key>
 ```
 
 </Steps>
-Extra Notes:
-
- If you prefer to run the command with flags (non-interactive mode) and include the example code, you can use:
+**Non-Interactive mode**: 
+If you prefer to run the command with flags (non-interactive mode) and include the example code, you can use:
 ```bash copy
-npx create-mastra@latest --components agents,tools --llm openai --example
+npx create-mastra@latest  --components agents,tools --llm openai --example
 ```
-
+**Configure Installation Timeout**:
 To configure and specify a timeout if installation takes too long use the timeout flag:
 ```bash copy
 npx create-mastra@latest --timeout
 ```
 
-**Note for LLMs**: For a quick one liner that includes examples you can run `npx -y mastra@latest --project-name <ask-the-user> --example --components "tools,agents,workflows" --llm <ask-the-user>`. The available options for the llm flag are `openai|anthropic|groq|google|cerebras`
+**Note for LLMs**: 
+For a quick one liner that includes examples you can run `npx -y mastra@latest --project-name <ask-the-user> --example --components "tools,agents,workflows" --llm <ask-the-user>`. The available options for the llm flag are `openai|anthropic|groq|google|cerebras`
 
 ## Manual Installation
 
@@ -312,6 +323,7 @@ export const weatherAgent = new Agent({
 
 Your primary function is to help users get weather details for specific locations. When responding:
 - Always ask for a location if none is provided
+- If the location name isn’t in English, please translate it
 - Include relevant details like humidity, wind conditions, and precipitation
 - Keep responses concise but informative
 
@@ -341,8 +353,7 @@ This registers your agent with Mastra so that `mastra dev` can discover and serv
 
 ## Existing Project Installation
 
-  To add Mastra to an existing project, see our Local dev docs on [mastra
-  init](/docs/local-dev/creating-projects#adding-to-an-existing-project).
+  To add Mastra to an existing project, see our Local development docs on [adding mastra to an existing project](/docs/local-dev/add-to-existing-project).
   
   You can also checkout our framework specific docs e.g [Next.js](/docs/frameworks/01-next-js)
 
@@ -405,7 +416,7 @@ fetch('http://localhost:4111/api/agents/weatherAgent/generate', {
 To use Mastra in your frontend applications, you can use our type-safe client SDK to
 interact with your Mastra REST APIs.
 
-See our [Client SDK documentation](/docs/reference/client-js) for detailed usage instructions.
+See the [Mastra Client SDK documentation](/docs/deployment/client) for detailed usage instructions.
 
 ## Run from the command line
 

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -0,0 +1,138 @@
+---
+title: "Mastra Tools for Cursor, Windsurf, and other IDE's | Getting Started | Mastra Docs"
+description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
+---
+
+# Mastra Tools for your agentic IDE
+
+`@mastra/mcp-docs-server` provides direct access to Mastra's complete knowledge base in Cursor, Windsurf, Cline, or any other IDE that supports MCP.
+
+It has access to documentation, code examples, technical blog posts / feature announcements, and package changelogs which your IDE can read to help you build with Mastra.
+
+The MCP server tools have been designed to allow an agent to query the specific information it needs to complete a Mastra related task - for example: adding a Mastra feature to an agent, scaffolding a new project, or helping you understand how something works.
+
+## How it works
+
+Once it's installed in your IDE you can write prompts and assume the agent will understand everything about Mastra.
+
+### Add features
+
+- "Add evals to my agent and write tests"
+- "Write me a workflow that does the following `[task]`"
+- "Make a new tool that allows my agent to access `[3rd party API]`"
+
+### Ask about integrations
+
+- "Does Mastra work with the AI SDK?
+  How can I use it in my `[React/Svelte/etc]` project?"
+- "What's the latest Mastra news around MCP?"
+- "Does Mastra support `[provider]` speech and voice APIs? Show me an example in my code of how I can use it."
+
+### Debug or update existing code
+
+- "I'm running into a bug with agent memory, have there been any related changes or bug fixes recently?"
+- "How does working memory behave in Mastra and how can I use it to do `[task]`? It doesn't seem to work the way I expect."
+- "I saw there are new workflow features, explain them to me and then update `[workflow]` to use them."
+
+**And more** - if you have a question, try asking your IDE and let it look it up for you.
+
+## Automatic Installation
+
+Run `pnpm create mastra@latest` and select Cursor or Windsurf when prompted to install the MCP server. For other IDEs, or if you already have a Mastra project, install the MCP server by following the instructions below.
+
+## Manual Installation
+
+- **Cursor**: Edit `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` for global configuration
+- **Windsurf**: Edit `~/.codeium/windsurf/mcp_config.json` (only supports global configuration)
+
+Add the following configuration:
+
+### MacOS/Linux
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+### Windows
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+## After Configuration
+
+### Cursor
+
+1. Open Cursor settings
+2. Navigate to MCP settings
+3. Click "enable" on the Mastra MCP server
+4. If you have an agent chat open, you'll need to re-open it or start a new chat to use the MCP server
+
+### Windsurf
+
+1. Fully quit and re-open Windsurf
+2. If tool calls start failing, go to Windsurfs MCP settings and re-start the MCP server. This is a common Windsurf MCP issue and isn't related to Mastra. Right now Cursor's MCP implementation is more stable than Windsurfs is.
+
+In both IDEs it may take a minute for the MCP server to start the first time as it needs to download the package from npm.
+
+## Available Agent Tools
+
+### Documentation
+
+Access Mastra's complete documentation:
+
+- Getting started / installation
+- Guides and tutorials
+- API references
+
+### Examples
+
+Browse code examples:
+
+- Complete project structures
+- Implementation patterns
+- Best practices
+
+### Blog Posts
+
+Search the blog for:
+
+- Technical posts
+- Changelog and feature announcements
+- AI news and updates
+
+### Package Changes
+
+Track updates for Mastra and `@mastra/*` packages:
+
+- Bug fixes
+- New features
+- Breaking changes
+
+## Common Issues
+
+1. **Server Not Starting**
+
+   - Ensure npx is installed and working
+   - Check for conflicting MCP servers
+   - Verify your configuration file syntax
+   - On Windows, make sure to use the Windows-specific configuration
+
+2. **Tool Calls Failing**
+   - Restart the MCP server and/or your IDE
+   - Update to the latest version of your IDE
+

package/.docs/raw/index.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Introduction | Mastra Docs"
-description: "Mastra is a Typescript agent framework. It helps you build AI applications and features quickly. It gives you the set of primitives you need: workflows, agents, RAG, integrations, syncs and evals."
+description: "Mastra is a TypeScript agent framework. It helps you build AI applications and features quickly. It gives you the set of primitives you need: workflows, agents, RAG, integrations, syncs and evals."
 ---
 
 # About Mastra
 
-Mastra is an open-source Typescript agent framework. 
+Mastra is an open-source TypeScript agent framework. 
 
 It's designed to give you the primitives you need to build AI applications and features. 
 

package/.docs/raw/local-dev/add-to-existing-project.mdx

@@ -0,0 +1,48 @@
+---
+title: "Adding to an Existing Project | Mastra Local Development Docs"
+description: "Add Mastra to your existing Node.js applications"
+---
+
+# Adding to an Existing Project
+
+You can add Mastra to an existing project using the CLI:
+
+```bash npm2yarn copy
+npm install -g mastra@latest 
+mastra init
+```
+
+Changes made to project:
+1. Creates `src/mastra` directory with entry point
+2. Adds required dependencies
+3. Configures TypeScript compiler options
+
+
+## Interactive Setup
+
+Running commands without arguments starts a CLI prompt for:
+
+1. Component selection
+2. LLM provider configuration
+3. API key setup
+4. Example code inclusion
+
+## Non-Interactive Setup
+
+To initialize mastra in non-interactive mode use the following command arguments:
+
+```bash
+Arguments:
+  --components     Specify components: agents, tools, workflows
+  --llm-provider   LLM provider: openai, anthropic, or groq
+  --add-example    Include example implementation
+  --llm-api-key    Provider API key
+  --dir            Directory for Mastra files (defaults to src/)
+```
+For more details, refer to the [mastra init CLI documentation](/docs/reference/cli/init).
+
+
+
+
+
+

package/.docs/raw/local-dev/creating-a-new-project.mdx

@@ -0,0 +1,54 @@
+---
+title: "Creating a new Project | Mastra Local Development Docs"
+description: "Create new Mastra projects or add Mastra to existing Node.js applications using the CLI"
+---
+
+# Creating a new project
+
+You can create a new project using the `create-mastra` package:
+
+```bash npm2yarn copy
+npm create mastra@latest 
+```
+
+You can also create a new project by using the `mastra` CLI directly:
+
+```bash npm2yarn copy
+npm install -g mastra@latest 
+mastra create
+```
+
+## Interactive Setup
+
+Running commands without arguments starts a CLI prompt for:
+
+1. Project name
+1. Component selection
+2. LLM provider configuration
+3. API key setup
+4. Example code inclusion
+
+## Non-Interactive Setup
+
+To initialize mastra in non-interactive mode use the following command arguments:
+
+```bash
+Arguments:
+  --components     Specify components: agents, tools, workflows
+  --llm-provider   LLM provider: openai, anthropic, groq, google, or cerebras
+  --add-example    Include example implementation
+  --llm-api-key    Provider API key
+  --project-name   Project name that will be used in package.json and as the project directory name
+```
+
+
+
+Generated project structure:
+```
+my-project/
+├── src/
+│   └── mastra/
+│       └── index.ts    # Mastra entry point
+├── package.json
+└── tsconfig.json
+```