@mastra/mcp-docs-server 0.13.30-alpha.0 → 0.13.30-alpha.1

package/.docs/raw/getting-started/installation.mdx

@@ -5,27 +5,24 @@ description: Guide on installing Mastra and setting up the necessary prerequisit
 
 import { Callout, Steps } from "nextra/components";
 import { Tabs, Tab } from "@/components/tabs";
+import { VideoPlayer } from "@/components/video-player"
 
 # Install Mastra
 
-To get started with Mastra, you'll need access to a large language model (LLM). By default, Mastra is set up to work with [OpenAI](https://platform.openai.com/), so you'll need an API key to begin.
+The `create mastra` CLI command is the quickest way to start a new Mastra project. It walks you through setup and creates example agents, workflows, and tools for you to learn from or adapt. 
 
-Mastra also supports other LLM providers. For a full list of supported models and setup instructions, see [Model Providers](/docs/getting-started/model-providers).
+For more control over setup, or to add Mastra to an existing project, see the [manual installation guide](#install-manually). You can also use [`mastra init`](/reference/cli/mastra#mastra-init) for existing projects.
 
-## Prerequisites
+## Before you start
 
-- Node.js `v20.0` or higher
-- An API key from a supported [Model Provider](/docs/getting-started/model-providers)
+- You'll need an API key from a [model provider](/models) to complete setup. We recommend starting with [Gemini](https://aistudio.google.com/app/api-keys), as you likely already have a Google account and they don't require a card.
+- Node.js 20 or later.
 
-## Install using the `create mastra` CLI
+## Install with `create mastra`
 
-Our CLI is the fastest way to get started with Mastra. You can run `create mastra` anywhere on your machine.
+You can run `create mastra` anywhere on your machine. 
 
-<Steps>
-
-## Start the CLI wizard
-
-Run the following command to start the interactive setup:
+The wizard will guide you through setup, create a new directory for your project, and generate a weather agent with example workflows and tools to get you started.
 
 {/*
 LLM CONTEXT: This Tabs component shows different package manager commands for creating a new Mastra project.
@@ -34,109 +31,61 @@ This helps users choose their preferred package manager while following the same
 All commands achieve the same result - creating a new Mastra project with the interactive setup.
 */}
 
-<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
+<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
   <Tab>
     ```bash copy
-    npx create-mastra@latest
+    npm create mastra@latest -y
     ```
   </Tab>
   <Tab>
     ```bash copy
-    yarn dlx create-mastra@latest
+    pnpm create mastra@latest -y
     ```
   </Tab>
   <Tab>
     ```bash copy
-    pnpm create mastra@latest
+    yarn create mastra@latest -y
     ```
   </Tab>
   <Tab>
     ```bash copy
-    bun create mastra@latest
+    bun create mastra@latest -y
     ```
   </Tab>
 </Tabs>
 
+<Callout type="default">
+You can use flags with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/templates). Read the [CLI reference](/reference/cli/create-mastra) for all options.
+</Callout>
 
-**Install using CLI flags**
-
-You can also run the Mastra CLI in non-interactive mode by passing all required flags, for example:
-
-```bash copy
-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
-```
-
-> Browse available templates and learn more in [Templates](/docs/getting-started/templates).
-
-For example, to create a text-to-SQL application:
-
-```bash copy
-npx create-mastra@latest --template text-to-sql
-```
 
-> See the [create-mastra](/reference/cli/create-mastra) documentation for a full list of available CLI options.
+### Test your agent
 
-### Add your API key
+Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open the Playground at http://localhost:4111.
 
-Add your API key to the `.env` file:
+Try asking about the weather. If your API key is set up correctly, you'll get a response:
 
-```bash filename=".env" copy
-OPENAI_API_KEY=<your-api-key>
-```
-> This example uses OpenAI. Each LLM provider uses a unique name. See [Model Capabilities](/docs/getting-started/model-capability) for more information.
+<VideoPlayer
+  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4"
+/>
 
-### Launch the Mastra Development Server
+<Callout type="default">
+If you encounter an error, your API key may not be configured correctly. Double-check your setup and try again. Need more help? [Join our Discord](https://discord.gg/BTYqqHKUrf) and talk to the team directly.
+</Callout>
 
-You can now launch the [Mastra Development Server](/docs/server-db/local-dev-playground) and test your agent using the Mastra Playground.
+The [Playground](/docs/server-db/local-dev-playground) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your application using the guides below.
 
-{/*
-LLM CONTEXT: This Tabs component shows different package manager commands for starting Mastra's development server.
-Each tab displays the equivalent command for that specific package manager (npx, npm, yarn, pnpm, bun).
-This helps users choose their preferred package manager.
-All commands achieve the same result - starting Mastra's development server.
-*/}
 
-<Tabs items={["npm", "yarn", "pnpm", "bun", "Mastra CLI"]}>
-  <Tab>
-    ```bash copy
-    npm run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    yarn run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    pnpm run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    bun run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    mastra dev
-    ```
-  </Tab>
-</Tabs>
+### Next steps
 
-</Steps>
+- Read more about [Mastra's features](/docs#why-mastra).
+- Integrate Mastra with your frontend framework: [Next.js](/docs/frameworks/web-frameworks/next-js), [React](/docs/frameworks/web-frameworks/vite-react), or [Astro](/docs/frameworks/web-frameworks/astro).
+- Build an agent from scratch following one of our [guides](/guides).
+- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)!
 
 ## Install manually
 
-The following steps will walk you through installing Mastra manually.
+If you prefer not to use our automatic `create mastra` CLI tool, you can set up your project yourself by following the guide below.
 
 <Steps>
 
@@ -368,7 +317,7 @@ To install Mastra in an existing project, use the `mastra init` command.
 
 > See [mastra init](/reference/cli/init) for more information.
 
-## Next steps
+### Next steps
 
 - [Local Development](/docs/server-db/local-dev-playground)
 - [Deploy to Mastra Cloud](/docs/deployment/overview)

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

@@ -7,7 +7,7 @@ import YouTube from "@/components/youtube";
 
 # Mastra Docs Server
 
-The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full knowledge base, including documentation, code examples, blog posts, and changelogs, via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, or any tool that supports MCP.
+The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full knowledge base, including documentation, code examples, blog posts, and changelogs, via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, Codex or any tool that supports MCP.
 
 These tools are designed to help agents retrieve precise, task-specific information — whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
 
@@ -47,6 +47,18 @@ claude mcp add mastra -- npx -y @mastra/mcp-docs-server
 
 [More info on using MCP servers with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
 
+### OpenAI Codex CLI
+
+1. Register it from the terminal:
+
+    ```bash copy
+    codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server
+    ```
+
+2. Run `codex mcp list` to confirm the server shows as `enabled`.
+
+[More info on using MCP servers with OpenAI Codex](https://developers.openai.com/codex/mcp)
+
 ### Cursor
 
 Install by clicking the button below:

package/.docs/raw/index.mdx

@@ -1,23 +1,58 @@
 ---
-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."
+title: "About Mastra | Mastra Docs"
+description: "Mastra is an all-in-one framework for building AI-powered applications and agents with a modern TypeScript stack."
 ---
 
+import YouTube from "@/components/youtube";
+
 # About Mastra
 
-Mastra is an open-source TypeScript agent framework.
+From the team behind Gatsby, Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
+
+It includes everything you need to go from early prototypes to production-ready applications. Mastra integrates with frontend and backend frameworks like React, Next.js, and Node, or you can deploy it anywhere as a standalone server. It's the easiest way to build, tune, and scale reliable AI products.
+
+<YouTube id="8o_Ejbcw5s8" />
+
+## Why Mastra?
+
+Purpose-built for TypeScript and designed around established AI patterns, Mastra gives you everything you need to build great AI applications out-of-the-box.
+
+Some highlights include:
+
+- [**Model routing**](/models) - Connect to 40+ providers through one standard interface. Use models from OpenAI, Anthropic, Gemini, and more.
+
+- [**Agents**](/docs/agents/overview) - Build autonomous agents that use LLMs and tools to solve open-ended tasks. Agents reason about goals, decide which tools to use,  and iterate internally until the model emits a final answer or an optional stopping condition is met.
+
+- [**Workflows**](/docs/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
+
+- [**Human-in-the-loop**](/docs/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
+
+- **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/memory/conversation-history), [retrieve](/docs/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/memory/working-memory) and [semantic](/docs/memory/semantic-recall) memory so your agents behave coherently. 
+
+- **Integrations** - Bundle agents and workflows into existing React, Next.js, or Node.js apps, or ship them as standalone endpoints. When building UIs, integrate with agentic libraries like Vercel's AI SDK UI and CopilotKit to bring your AI assistant to life on the web.
+
+- **Production essentials** - Shipping reliable agents takes ongoing insight, evaluation, and iteration. With built-in [evals](/docs/evals/overview) and [observability](/docs/observability/overview), Mastra gives you the tools to observe, measure, and refine continuously.
+
+
+## What can you build?
+
+- AI-powered applications that combine language understanding, reasoning, and action to solve real-world tasks.
+
+- Conversational agents for customer support, onboarding, or internal queries.
+
+- Domain-specific copilots for coding, legal, finance, research, or creative work.
+
+- Workflow automations that trigger, route, and complete multi-step processes.
+
+- Decision-support tools that analyse data and provide actionable recommendations.
+
+Explore real-world examples in our [case studies](/blog/category/case-studies) and [community showcase](/showcase).
+
 
-It's designed to give you the primitives you need to build AI applications and features.
+## Get started
 
-You can use Mastra to build [AI agents](/docs/agents/overview.mdx) that have memory and can execute functions, or chain LLM calls in deterministic [workflows](/docs/workflows/overview.mdx). You can chat with your agents in Mastra's [local dev playground](/docs/server-db/local-dev-playground.mdx), feed them application-specific knowledge with [RAG](/docs/rag/overview.mdx), and score their outputs with Mastra's [evals](/docs/evals/overview.mdx).
+Follow the [Installation guide](/docs/getting-started/installation) for step-by-step setup with the CLI or a manual install.
 
-The main features include:
+If you're new to AI agents, check out our [templates](/docs/getting-started/templates), [course](/course), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
 
-- **[Model routing](https://sdk.vercel.ai/docs/introduction)**: Mastra uses the [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) for model routing, providing a unified interface to interact with any LLM provider including OpenAI, Anthropic, and Google Gemini.
-- **[Agent memory and tool calling](/docs/agents/agent-memory.mdx)**: With Mastra, you can give your agent tools (functions) that it can call. You can persist agent memory and retrieve it based on recency, semantic similarity, or conversation thread.
-- **[Workflow graphs](/docs/workflows/overview.mdx)**: When you want to execute LLM calls in a deterministic way, Mastra gives you a graph-based workflow engine. You can define discrete steps, log inputs and outputs at each step of each run, and pipe them into an observability tool. Mastra workflows have a simple syntax for control flow (`.then()`, `.branch()`, `.parallel()`) that allows branching and chaining.
-- **[Agent development playground](/docs/server-db/local-dev-playground.mdx)**: When you're developing an agent locally, you can chat with it and see its state and memory in Mastra's agent development environment.
-- **[Retrieval-augmented generation (RAG)](/docs/rag/overview.mdx)**: Mastra gives you APIs to process documents (text, HTML, Markdown, JSON) into chunks, create embeddings, and store them in a vector database. At query time, it retrieves relevant chunks to ground LLM responses in your data, with a unified API on top of multiple vector stores (Pinecone, pgvector, etc) and embedding providers (OpenAI, Cohere, etc).
-- **[Deployment](/docs/deployment/deployment.mdx)**: Mastra supports bundling your agents and workflows within an existing React, Next.js, or Node.js application, or into standalone endpoints. The Mastra deploy helper lets you easily bundle agents and workflows into a Node.js server using Hono, or deploy it onto a serverless platform like Vercel, Cloudflare Workers, or Netlify.
-- **[Evals](/docs/evals/overview.mdx)**: Mastra provides automated evaluation metrics that use model-graded, rule-based, and statistical methods to assess LLM outputs, with built-in metrics for toxicity, bias, relevance, and factual accuracy. You can also define your own evals.
-- **[Observability](/docs/observability/overview.mdx)**: Mastra provides specialized AI tracing to monitor LLM operations, agent decisions, and tool executions. Track token usage, latency, and conversation flows with native exporters for Langfuse, Braintrust, and Mastra Cloud. Structured logging provides additional debugging capabilities for comprehensive monitoring.
+We can't wait to see what you build ✌️ 

package/.docs/raw/observability/ai-tracing/exporters/otel.mdx

@@ -68,6 +68,9 @@ export const mastra = new Mastra({
                 dataset: 'production', // Optional dataset name
               }
             },
+            resourceAttributes: { // Optional OpenTelemetry Resource Attributes for the trace
+              ['deployment.environment']: 'dev',
+            },
           }),
         ],
       },

package/.docs/raw/reference/observability/ai-tracing/exporters/otel.mdx

@@ -57,6 +57,12 @@ interface OtelExporterConfig {
       description: "Logger level (default: 'warn')",
       required: false,
     },
+    {
+      name: "resourceAttributes",
+      type: "DetectedResourceAttributes",
+      description: "Optional OpenTelemetry Resource Attributes (values here override any defaults)",
+      required: false,
+    }
   ]}
 />
 

package/.docs/raw/reference/scorers/answer-relevancy.mdx

@@ -7,8 +7,6 @@ description: Documentation for the Answer Relevancy Scorer in Mastra, which eval
 
 The `createAnswerRelevancyScorer()` function accepts a single options object with the following properties:
 
-For usage example, see the [Answer Relevancy Examples](/examples/scorers/answer-relevancy).
-
 ## Parameters
 
 <PropertiesTable
@@ -103,11 +101,111 @@ The scorer evaluates relevancy through query-answer alignment, considering compl
 
 ### Score Interpretation
 
-- 1.0: Perfect relevance - complete and accurate
-- 0.7-0.9: High relevance - minor gaps or imprecisions
-- 0.4-0.6: Moderate relevance - significant gaps
-- 0.1-0.3: Low relevance - major issues
-- 0.0: No relevance - incorrect or off-topic
+A relevancy score between 0 and 1:
+
+- **1.0**: The response fully answers the query with relevant and focused information.
+- **0.7–0.9**: The response mostly answers the query but may include minor unrelated content.
+- **0.4–0.6**: The response partially answers the query, mixing relevant and unrelated information.
+- **0.1–0.3**: The response includes minimal relevant content and largely misses the intent of the query.
+- **0.0**: The response is entirely unrelated and does not answer the query.
+
+## Examples
+
+### High relevancy example
+
+In this example, the response accurately addresses the input query with specific and relevant information.
+
+```typescript filename="src/example-high-answer-relevancy.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/llm";
+
+const scorer = createAnswerRelevancyScorer({ model: openai("gpt-4o-mini") });
+
+const inputMessages = [{ role: 'user', content: "What are the health benefits of regular exercise?" }];
+const outputMessage = { text: "Regular exercise improves cardiovascular health, strengthens muscles, boosts metabolism, and enhances mental well-being through the release of endorphins." };
+
+const result = await scorer.run({
+  input: inputMessages,
+  output: outputMessage,
+});
+
+console.log(result);
+```
+
+#### High relevancy output
+
+The output receives a high score because it accurately answers the query without including unrelated information.
+
+```typescript
+{
+  score: 1,
+  reason: 'The score is 1 because the output directly addresses the question by providing multiple explicit health benefits of regular exercise, including improvements in cardiovascular health, muscle strength, metabolism, and mental well-being. Each point is relevant and contributes to a comprehensive understanding of the health benefits.'
+}
+```
+
+### Partial relevancy example
+
+In this example, the response addresses the query in part but includes additional information that isn’t directly relevant.
+
+```typescript filename="src/example-partial-answer-relevancy.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/llm";
+
+const scorer = createAnswerRelevancyScorer({ model: openai("gpt-4o-mini") });
+
+const inputMessages = [{ role: 'user', content: "What should a healthy breakfast include?" }];
+const outputMessage = { text: "A nutritious breakfast should include whole grains and protein. However, the timing of your breakfast is just as important - studies show eating within 2 hours of waking optimizes metabolism and energy levels throughout the day." };
+
+const result = await scorer.run({
+  input: inputMessages,
+  output: outputMessage,
+});
+
+console.log(result);
+```
+
+#### Partial relevancy output
+
+The output receives a lower score because it partially answers the query. While some relevant information is included, unrelated details reduce the overall relevance.
+
+```typescript
+{
+  score: 0.25,
+  reason: 'The score is 0.25 because the output provides a direct answer by mentioning whole grains and protein as components of a healthy breakfast, which is relevant. However, the additional information about the timing of breakfast and its effects on metabolism and energy levels is not directly related to the question, leading to a lower overall relevance score.'
+}
+```
+
+## Low relevancy example
+
+In this example, the response does not address the query and contains information that is entirely unrelated.
+
+```typescript filename="src/example-low-answer-relevancy.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/llm";
+
+const scorer = createAnswerRelevancyScorer({ model: openai("gpt-4o-mini") });
+
+const inputMessages = [{ role: 'user', content: "What are the benefits of meditation?" }];
+const outputMessage = { text: "The Great Wall of China is over 13,000 miles long and was built during the Ming Dynasty to protect against invasions." };
+
+const result = await scorer.run({
+  input: inputMessages,
+  output: outputMessage,
+});
+
+console.log(result);
+```
+
+#### Low relevancy output
+
+The output receives a score of 0 because it fails to answer the query or provide any relevant information.
+
+```typescript
+{
+  score: 0,
+  reason: 'The score is 0 because the output about the Great Wall of China is completely unrelated to the benefits of meditation, providing no relevant information or context that addresses the input question.'
+}
+```
 
 ## Related