@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.1

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

@@ -13,12 +13,12 @@ import { VideoPlayer } from "@site/src/components/video-player";
 
 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.
 
-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.
+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/v1/cli/mastra#mastra-init) for existing projects.
 
 ## Before you start
 
-- You'll need an API key from a [model provider](/models) to complete setup. We suggest starting with [OpenAI](https://platform.openai.com/api-keys), but if you need a provider that doesn't require a credit card, Google's [Gemini](https://aistudio.google.com/app/api-keys) is also an option.
-- [Install](https://nodejs.org/en/download) Node.js 20 or later.
+- You'll need an API key from a [model provider](/models/v1) to complete setup. We suggest starting with [OpenAI](https://platform.openai.com/api-keys), but if you need a provider that doesn't require a credit card, Google's [Gemini](https://aistudio.google.com/app/api-keys) is also an option.
+- [Install](https://nodejs.org/en/download) Node.js 22.13.0 or later.
 
 ## Install with `create mastra`
 
@@ -30,28 +30,28 @@ The wizard will guide you through setup, create a new directory for your project
 <TabItem value="npm" label="npm">
 
 ```bash copy
-npm create mastra@latest
+npm create mastra@beta
 ```
 
 </TabItem>
 <TabItem value="pnpm" label="pnpm">
 
 ```bash copy
-pnpm create mastra@latest
+pnpm create mastra@beta
 ```
 
 </TabItem>
 <TabItem value="yarn" label="yarn">
 
 ```bash copy
-yarn create mastra@latest
+yarn create mastra@beta
 ```
 
 </TabItem>
 <TabItem value="bun" label="bun">
 
 ```bash copy
-bun create mastra@latest
+bun create mastra@beta
 ```
 
 </TabItem>
@@ -59,7 +59,7 @@ bun create mastra@latest
 
 :::note
 
-You can use flags with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/docs/getting-started/templates). Read the [CLI reference](/reference/cli/create-mastra) for all options.
+You can use flags with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/docs/v1/getting-started/templates). Read the [CLI reference](/reference/v1/cli/create-mastra) for all options.
 
 :::
 
@@ -77,13 +77,13 @@ If you encounter an error, your API key may not be configured correctly. Double-
 
 :::
 
-[Studio](/docs/getting-started/studio) 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.
+[Studio](/docs/v1/getting-started/studio) 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.
 
 ### Next 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).
+- Read more about [Mastra's features](/docs/v1#why-mastra).
+- Integrate Mastra with your frontend framework: [Next.js](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/astro).
+- Build an agent from scratch following one of our [guides](/guides/v1).
 - 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
@@ -107,17 +107,17 @@ Initialize a TypeScript project and install the following dependencies:
 
 ```bash copy
 npm init -y
-npm install -D typescript @types/node mastra@latest
-npm install @mastra/core@latest zod@^4
+npm install -D typescript @types/node mastra@beta
+npm install @mastra/core@beta zod@^4
 ```
 
 </TabItem>
 <TabItem value="pnpm" label="pnpm">
 
 ```bash copy
-pnpm init -y
-pnpm add -D typescript @types/node mastra@latest
-pnpm add @mastra/core@latest zod@^4
+pnpm init
+pnpm add -D typescript @types/node mastra@beta
+pnpm add @mastra/core@beta zod@^4
 ```
 
 </TabItem>
@@ -125,8 +125,8 @@ pnpm add @mastra/core@latest zod@^4
 
 ```bash copy
 yarn init -y
-yarn add -D typescript @types/node mastra@latest
-yarn add @mastra/core@latest zod@^4
+yarn add -D typescript @types/node mastra@beta
+yarn add @mastra/core@beta zod@^4
 ```
 
 </TabItem>
@@ -134,8 +134,8 @@ yarn add @mastra/core@latest zod@^4
 
 ```bash copy
 bun init -y
-bun add -d typescript @types/node mastra@latest
-bun add @mastra/core@latest zod@^4
+bun add -d typescript @types/node mastra@beta
+bun add @mastra/core@beta zod@^4
 ```
 
 </TabItem>
@@ -206,7 +206,7 @@ GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
 
 :::note
 
-This guide uses Google Gemini, but you can use any supported [model provider](/models), including OpenAI, Anthropic, and more.
+This guide uses Google Gemini, but you can use any supported [model provider](/models/v1), including OpenAI, Anthropic, and more.
 
 :::
 
@@ -245,7 +245,7 @@ export const weatherTool = createTool({
 
 :::info
 
-We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](/docs/agents/using-tools).
+We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](/docs/v1/agents/using-tools).
 
 :::
 
@@ -266,6 +266,7 @@ import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
 export const weatherAgent = new Agent({
+  id: "weather-agent",
   name: "Weather Agent",
   instructions: `
       You are a helpful weather assistant that provides accurate weather information.
@@ -297,7 +298,7 @@ touch src/mastra/index.ts
 Add the following code:
 
 ```ts title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { weatherAgent } from "./agents/weather-agent";
 
 export const mastra = new Mastra({
@@ -309,7 +310,7 @@ export const mastra = new Mastra({
 
 <StepItem>
 
-You can now launch [Studio](/docs/getting-started/studio) and test your agent.
+You can now launch [Studio](/docs/v1/getting-started/studio) and test your agent.
 
 <Tabs>
 <TabItem value="npm" label="npm">

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

@@ -19,7 +19,7 @@ In this guide you'll learn how to add Mastra's MCP server to your AI tooling.
 
 ### create-mastra
 
-During the interactive [create-mastra](/reference/cli/create-mastra) wizard, choose one of your tools in the MCP step.
+During the interactive [create-mastra](/reference/v1/cli/create-mastra) wizard, choose one of your tools in the MCP step.
 
 ### Manual setup
 

package/.docs/raw/getting-started/project-structure.mdx

@@ -55,13 +55,13 @@ Top-level files define how your Mastra project is configured, built, and connect
 | File                  | Description                                                                                                       |
 | --------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | `src/mastra/index.ts` | Central entry point where you configure and initialize Mastra.                                                    |
-| `.env.example`        | Template for environment variables - copy and rename to `.env` to add your secret [model provider](/models) keys. |
+| `.env.example`        | Template for environment variables - copy and rename to `.env` to add your secret [model provider](/models/v1) keys. |
 | `package.json`        | Defines project metadata, dependencies, and available npm scripts.                                                |
 | `tsconfig.json`       | Configures TypeScript options such as path aliases, compiler settings, and build output.                          |
 
 ## Next 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).
+- Read more about [Mastra's features](/docs/v1#why-mastra).
+- Integrate Mastra with your frontend framework: [Next.js](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/astro).
+- Build an agent from scratch following one of our [guides](/guides/v1).
 - Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)!

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

@@ -61,7 +61,7 @@ The Studio UI provides an interactive development environment for you to test yo
 
 ### Agents
 
-Chat with your agent directly, dynamically switch [models](/models), and tweak settings like temperature and top-p to understand how they affect the output.
+Chat with your agent directly, dynamically switch [models](/models/v1), and tweak settings like temperature and top-p to understand how they affect the output.
 
 <VideoPlayer src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4" />
 
@@ -91,7 +91,7 @@ When you run an agent or workflow, the Observability tab displays traces that hi
 
 ![](https://mastra.ai/_next/image?url=%2Ftracingafter.png&w=1920&q=75)
 
-AI Tracing filters out low-level framework details so your traces stay focused and readable.
+Tracing filters out low-level framework details so your traces stay focused and readable.
 
 ### Scorers
 
@@ -99,7 +99,7 @@ The Scorers tab displays the results of your agent's scorers as they run. When m
 
 ## REST API
 
-The local development server exposes a complete set of REST API routes, allowing you to programmatically interact with your agents, workflows, and tools during development. This is particularly helpful if you plan to deploy the Mastra server, since the local development server uses the exact same API routes as the [production server](/docs/server-db/production-server), allowing you to develop and test against it with full parity.
+The local development server exposes a complete set of REST API routes, allowing you to programmatically interact with your agents, workflows, and tools during development. This is particularly helpful if you plan to deploy the Mastra server, since the local development server uses the exact same API routes as the [production server](/docs/v1/server-db/production-server), allowing you to develop and test against it with full parity.
 
 You can explore all available endpoints in the OpenAPI specification at http://localhost:4111/openapi.json, which details every endpoint and its request and response schemas.
 
@@ -116,7 +116,7 @@ The OpenAPI and Swagger endpoints are disabled in production by default. To enab
 By default, the development server runs at http://localhost:4111. You can change the `host` and `port` in the Mastra server configuration:
 
 ```typescript
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
   server: {
@@ -128,10 +128,10 @@ export const mastra = new Mastra({
 
 ### Local HTTPS
 
-Mastra supports local HTTPS development through the [`--https`](/reference/cli/mastra#--https) flag, which automatically creates and manages certificates for your project. When you run `mastra dev --https`, a private key and certificate are generated for localhost (or your configured host). For custom certificate management, you can provide your own key and certificate files through the server configuration:
+Mastra supports local HTTPS development through the [`--https`](/reference/v1/cli/mastra#--https) flag, which automatically creates and manages certificates for your project. When you run `mastra dev --https`, a private key and certificate are generated for localhost (or your configured host). For custom certificate management, you can provide your own key and certificate files through the server configuration:
 
 ```typescript
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import fs from "node:fs";
 
 export const mastra = new Mastra({
@@ -146,5 +146,5 @@ export const mastra = new Mastra({
 
 ## Next steps
 
-- Learn more about Mastra's suggested [project structure](/docs/getting-started/project-structure).
-- Integrate Mastra with your frontend framework of choice - [Next.js](/docs/frameworks/web-frameworks/next-js), [React](/docs/frameworks/web-frameworks/vite-react), or [Astro](/docs/frameworks/web-frameworks/astro).
+- Learn more about Mastra's suggested [project structure](/docs/v1/getting-started/project-structure).
+- Integrate Mastra with your frontend framework of choice - [Next.js](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/astro).

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

@@ -17,22 +17,22 @@ Install a template using the `create-mastra` command:
 <Tabs>
   <TabItem value="npm" label="npm">
     ```bash copy
-    npx create-mastra@latest --template template-name
+    npx create-mastra@beta --template template-name
     ```
   </TabItem>
   <TabItem value="yarn" label="yarn">
     ```bash copy
-    yarn dlx create-mastra@latest --template template-name
+    yarn dlx create-mastra@beta --template template-name
     ```
   </TabItem>
   <TabItem value="pnpm" label="pnpm">
     ```bash copy
-    pnpm create mastra@latest --template template-name
+    pnpm create mastra@beta --template template-name
     ```
   </TabItem>
   <TabItem value="bun" label="bun">
     ```bash copy
-    bun create mastra@latest --template template-name
+    bun create mastra@beta --template template-name
     ```
   </TabItem>
 </Tabs>
@@ -40,7 +40,7 @@ Install a template using the `create-mastra` command:
 For example, to create a text-to-SQL application:
 
 ```bash copy
-npx create-mastra@latest --template text-to-sql
+npx create-mastra@beta --template text-to-sql
 ```
 
 ## Setting Up a Template
@@ -70,4 +70,4 @@ After installation:
 Each template includes a comprehensive README with specific setup instructions and usage examples.
 :::
 
-For detailed information on creating templates, see the [Templates Reference](/reference/templates/overview).
+For detailed information on creating templates, see the [Templates Reference](/reference/v1/templates/overview).

package/.docs/raw/guides/guide/ai-recruiter.mdx

@@ -0,0 +1,264 @@
+---
+title: "Guide: Building an AI Recruiter | Mastra Workflows | Guides"
+description: Guide on building a recruiter workflow in Mastra to gather and process candidate information using LLMs.
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+
+# Building an AI Recruiter
+
+In this guide, you'll learn how Mastra helps you build workflows with LLMs.
+
+You'll create a workflow that gathers information from a candidate's resume, then branches to either a technical or behavioral question based on the candidate's profile. Along the way, you'll see how to structure workflow steps, handle branching, and integrate LLM calls.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](/models/v1)
+- An existing Mastra project (Follow the [installation guide](/docs/v1/getting-started/installation) to set up a new project)
+
+## Building the Workflow
+
+Set up the Workflow, define steps to extract and classify candidate data, and then ask suitable follow-up questions.
+
+<Steps>
+
+<StepItem>
+
+Create a new file `src/mastra/workflows/candidate-workflow.ts` and define your workflow:
+
+```ts copy title="src/mastra/workflows/candidate-workflow.ts"
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+export const candidateWorkflow = createWorkflow({
+  id: "candidate-workflow",
+  inputSchema: z.object({
+    resumeText: z.string(),
+  }),
+  outputSchema: z.object({
+    askAboutSpecialty: z.object({
+      question: z.string(),
+    }),
+    askAboutRole: z.object({
+      question: z.string(),
+    }),
+  }),
+}).commit();
+```
+
+</StepItem>
+
+<StepItem>
+
+You want to extract candidate details from the resume text and classify the person as "technical" or "non-technical". This step calls an LLM to parse the resume and returns structured JSON, including the name, technical status, specialty, and the original resume text. Defined through the `inputSchema` you get access to the `resumeText` inside `execute()`. Use it to prompt an LLM and return the organized fields.
+
+To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
+
+```ts copy title="src/mastra/workflows/candidate-workflow.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+const recruiter = new Agent({
+  id: "recruiter-agent",
+  name: "Recruiter Agent",
+  instructions: `You are a recruiter.`,
+  model: openai("gpt-4o-mini"),
+});
+
+const gatherCandidateInfo = createStep({
+  id: "gatherCandidateInfo",
+  inputSchema: z.object({
+    resumeText: z.string(),
+  }),
+  outputSchema: z.object({
+    candidateName: z.string(),
+    isTechnical: z.boolean(),
+    specialty: z.string(),
+    resumeText: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const resumeText = inputData?.resumeText;
+
+    const prompt = `Extract details from the resume text:
+"${resumeText}"`;
+
+    const res = await recruiter.generate(prompt, {
+      structuredOutput: {
+        schema: z.object({
+          candidateName: z.string(),
+          isTechnical: z.boolean(),
+          specialty: z.string(),
+          resumeText: z.string(),
+        }),
+      },
+    });
+
+    return res.object;
+  },
+});
+```
+
+Since you're using a Recruiter agent inside `execute()` you need to define it above the step and add the necessary imports.
+
+</StepItem>
+
+<StepItem>
+
+This step prompts a candidate who is identified as "technical" for more information about how they got into their specialty. It uses the entire resume text so the LLM can craft a relevant follow-up question.
+
+To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
+
+```ts copy title="src/mastra/workflows/candidate-workflow.ts"
+const askAboutSpecialty = createStep({
+  id: "askAboutSpecialty",
+  inputSchema: z.object({
+    candidateName: z.string(),
+    isTechnical: z.boolean(),
+    specialty: z.string(),
+    resumeText: z.string(),
+  }),
+  outputSchema: z.object({
+    question: z.string(),
+  }),
+  execute: async ({ inputData: candidateInfo }) => {
+    const prompt = `You are a recruiter. Given the resume below, craft a short question
+for ${candidateInfo?.candidateName} about how they got into "${candidateInfo?.specialty}".
+Resume: ${candidateInfo?.resumeText}`;
+    const res = await recruiter.generate(prompt);
+
+    return { question: res?.text?.trim() || "" };
+  },
+});
+```
+
+</StepItem>
+
+<StepItem>
+
+If the candidate is "non-technical", you want a different follow-up question. This step asks what interests them most about the role, again referencing their complete resume text. The `execute()` function solicits a role-focused query from the LLM.
+
+To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
+
+```ts title="src/mastra/workflows/candidate-workflow.ts" copy
+const askAboutRole = createStep({
+  id: "askAboutRole",
+  inputSchema: z.object({
+    candidateName: z.string(),
+    isTechnical: z.boolean(),
+    specialty: z.string(),
+    resumeText: z.string(),
+  }),
+  outputSchema: z.object({
+    question: z.string(),
+  }),
+  execute: async ({ inputData: candidateInfo }) => {
+    const prompt = `You are a recruiter. Given the resume below, craft a short question
+for ${candidateInfo?.candidateName} asking what interests them most about this role.
+Resume: ${candidateInfo?.resumeText}`;
+    const res = await recruiter.generate(prompt);
+    return { question: res?.text?.trim() || "" };
+  },
+});
+```
+
+</StepItem>
+
+<StepItem>
+
+You now combine the steps to implement branching logic based on the candidate's technical status. The workflow first gathers candidate data, then either asks about their specialty or about their role, depending on `isTechnical`. This is done by chaining `gatherCandidateInfo` with `askAboutSpecialty` and `askAboutRole`.
+
+To the existing `src/mastra/workflows/candidate-workflow.ts` file change the `candidateWorkflow` like so:
+
+```ts title="src/mastra/workflows/candidate-workflow.ts" copy {10-14}
+export const candidateWorkflow = createWorkflow({
+  id: "candidate-workflow",
+  inputSchema: z.object({
+    resumeText: z.string(),
+  }),
+  outputSchema: z.object({
+    askAboutSpecialty: z.object({
+      question: z.string(),
+    }),
+    askAboutRole: z.object({
+      question: z.string(),
+    }),
+  }),
+})
+  .then(gatherCandidateInfo)
+  .branch([
+    [async ({ inputData: { isTechnical } }) => isTechnical, askAboutSpecialty],
+    [async ({ inputData: { isTechnical } }) => !isTechnical, askAboutRole],
+  ])
+  .commit();
+```
+
+</StepItem>
+
+<StepItem>
+
+In your `src/mastra/index.ts` file, register the workflow:
+
+```ts copy title="src/mastra/index.ts" {2, 5}
+import { Mastra } from "@mastra/core";
+import { candidateWorkflow } from "./workflows/candidate-workflow";
+
+export const mastra = new Mastra({
+  workflows: { candidateWorkflow },
+});
+```
+
+</StepItem>
+
+</Steps>
+
+## Testing the Workflow
+
+You can test your workflow inside [Studio](/docs/v1/getting-started/studio) by starting the development server:
+
+```bash copy
+mastra dev
+```
+
+In the sidebar, navigate to **Workflows** and select **candidate-workflow**. In the middle you'll see a graph view of your workflow and on the right sidebar the **Run** tab is selected by default. Inside this tab you can enter a resume text, for example:
+
+```text copy
+Knowledgeable Software Engineer with more than 10 years of experience in software development. Proven expertise in the design and development of software databases and optimization of user interfaces.
+```
+
+After entering the resume text, press the **Run** button. You should now see two status boxes (`GatherCandidateInfo` and `AskAboutSpecialty`) which contain the output of the workflow steps.
+
+You can also test the workflow programmatically by calling [`.createRun()`](/reference/v1/workflows/workflow-methods/create-run) and [`.start()`](/reference/v1/workflows/run-methods/start). Create a new file `src/test-workflow.ts` and add the following:
+
+```ts copy title="src/test-workflow.ts"
+import { mastra } from "./mastra";
+
+const run = await mastra.getWorkflow("candidateWorkflow").createRun();
+
+const res = await run.start({
+  inputData: {
+    resumeText:
+      "Knowledgeable Software Engineer with more than 10 years of experience in software development. Proven expertise in the design and development of software databases and optimization of user interfaces.",
+  },
+});
+
+// Dump the complete workflow result (includes status, steps and result)
+console.log(JSON.stringify(res, null, 2));
+
+// Get the workflow output value
+if (res.status === "success") {
+  const question =
+    res.result.askAboutRole?.question ?? res.result.askAboutSpecialty?.question;
+
+  console.log(`Output value: ${question}`);
+}
+```
+
+Now, run the workflow and get output in your terminal:
+
+```bash copy
+npx tsx src/test-workflow.ts
+```
+
+You've just built a workflow to parse a resume and decide which question to ask based on the candidate's technical abilities. Congrats and happy hacking!