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

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

@@ -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!

package/.docs/raw/guides/guide/chef-michel.mdx

@@ -0,0 +1,271 @@
+---
+title: "Guide: Building an AI Chef Assistant | Mastra Agent Guides"
+description: Guide on creating a Chef Assistant agent in Mastra to help users cook meals with available ingredients.
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import YouTube from "@site/src/components/YouTube-player";
+
+# Building an AI Chef Assistant
+
+In this guide, you'll create a "Chef Assistant" agent that helps users cook meals with available ingredients.
+
+You'll learn how to create the agent and register it with Mastra. Next, you'll interact with the agent through your terminal and get to know different response formats. Lastly, you'll access the agent through Mastra's local API endpoints.
+
+<YouTube id="_tZhOqHCrF0" />
+
+## 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)
+
+## Creating the Agent
+
+To create an agent in Mastra use the `Agent` class to define it and then register it with Mastra.
+
+<Steps>
+
+<StepItem>
+
+Create a new file `src/mastra/agents/chefAgent.ts` and define your agent:
+
+```ts copy title="src/mastra/agents/chefAgent.ts"
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+export const chefAgent = new Agent({
+  id: "chef-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"),
+});
+```
+
+</StepItem>
+
+<StepItem>
+
+In your `src/mastra/index.ts` file, register the agent:
+
+```ts copy title="src/mastra/index.ts" {2, 5}
+import { Mastra } from "@mastra/core";
+import { chefAgent } from "./agents/chefAgent";
+
+export const mastra = new Mastra({
+  agents: { chefAgent },
+});
+```
+
+</StepItem>
+
+</Steps >
+
+## Interacting with the Agent
+
+Depending on your requirements you can interact and get responses from the agent in different formats. In the following steps you'll learn how to generate, stream, and get structured output.
+
+<Steps>
+
+<StepItem>
+
+Create a new file `src/index.ts` and add a `main()` function to it. Inside, craft a query to ask the agent and log its response.
+
+```ts copy title="src/index.ts"
+import { chefAgent } from "./mastra/agents/chefAgent";
+
+async function main() {
+  const query =
+    "In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make?";
+  console.log(`Query: ${query}`);
+
+  const response = await chefAgent.generate([{ role: "user", content: query }]);
+  console.log("\n👨‍🍳 Chef Michel:", response.text);
+}
+
+main();
+```
+
+Afterwards, run the script:
+
+```bash copy
+npx bun src/index.ts
+```
+
+You should get an output similar to this:
+
+```
+Query: In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make?
+
+👨‍🍳 Chef Michel: You can make a delicious pasta al pomodoro! Here's how...
+```
+
+</StepItem>
+
+<StepItem>
+
+In the previous example you might have waited a bit for the response without any sign of progress. To show the agent's output as it creates it you should instead stream its response to the terminal.
+
+```ts copy title="src/index.ts"
+import { chefAgent } from "./mastra/agents/chefAgent";
+
+async function main() {
+  const query =
+    "Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.";
+  console.log(`Query: ${query}`);
+
+  const stream = await chefAgent.stream([{ role: "user", content: query }]);
+
+  console.log("\n Chef Michel: ");
+
+  for await (const chunk of stream.textStream) {
+    process.stdout.write(chunk);
+  }
+
+  console.log("\n\n✅ Recipe complete!");
+}
+
+main();
+```
+
+Afterwards, run the script again:
+
+```bash copy
+npx bun src/index.ts
+```
+
+You should get an output similar to the one below. This time though you can read it line by line instead of one large block.
+
+```
+Query: Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.
+
+👨‍🍳 Chef Michel:
+Great! You can make a comforting chicken curry...
+
+✅ Recipe complete!
+```
+
+</StepItem>
+
+<StepItem>
+
+Instead of showing the agent's response to a human you might want to pass it along to another part of your code. For these instances your agent should return [structured output](/docs/v1/agents/overview#structured-output).
+
+Change your `src/index.ts` to the following:
+
+```ts copy title="src/index.ts"
+import { chefAgent } from "./mastra/agents/chefAgent";
+import { z } from "zod";
+
+async function main() {
+  const query =
+    "I want to make lasagna, can you generate a lasagna recipe for me?";
+  console.log(`Query: ${query}`);
+
+  // Define the Zod schema
+  const schema = z.object({
+    ingredients: z.array(
+      z.object({
+        name: z.string(),
+        amount: z.string(),
+      }),
+    ),
+    steps: z.array(z.string()),
+  });
+
+  const response = await chefAgent.generate(
+    [{ role: "user", content: query }],
+    {
+      structuredOutput: {
+        schema,
+      },
+    },
+  );
+  console.log("\n👨‍🍳 Chef Michel:", response.object);
+}
+
+main();
+```
+
+After running the script again you should get an output similar to this:
+
+```
+Query: I want to make lasagna, can you generate a lasagna recipe for me?
+
+👨‍🍳 Chef Michel: {
+  ingredients: [
+    { name: "Lasagna noodles", amount: "12 sheets" },
+    { name: "Ground beef", amount: "1 pound" },
+    // ...
+  ],
+  steps: [
+    "Preheat oven to 375°F (190°C).",
+    "Cook the lasagna noodles according to package instructions.",
+    // ...
+  ]
+}
+```
+
+</StepItem>
+
+</Steps >
+
+## Running the Agent Server
+
+Learn how to interact with your agent through Mastra's API.
+
+<Steps>
+
+<StepItem>
+
+You can run your agent as a service using the `mastra dev` command:
+
+```bash copy
+mastra dev
+```
+
+This will start a server exposing endpoints to interact with your registered agents. Within [Studio](/docs/v1/getting-started/studio) you can test your agent through a UI.
+
+</StepItem>
+
+<StepItem>
+
+By default, `mastra dev` runs on `http://localhost:4111`. Your Chef Assistant agent will be available at:
+
+```
+POST http://localhost:4111/api/agents/chefAgent/generate
+```
+
+</StepItem>
+
+<StepItem>
+
+You can interact with the agent using `curl` from the command line:
+
+```bash copy
+curl -X POST http://localhost:4111/api/agents/chefAgent/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {
+        "role": "user",
+        "content": "I have eggs, flour, and milk. What can I make?"
+      }
+    ]
+  }'
+```
+
+**Sample Response:**
+
+```json
+{
+  "text": "You can make delicious pancakes! Here's a simple recipe..."
+}
+```
+
+</StepItem>
+
+</Steps>