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

package/.docs/raw/guides/getting-started/quickstart.mdx

@@ -0,0 +1,97 @@
+---
+title: "Quickstart"
+description: Get started with Mastra using the create mastra CLI to build a server with agents, workflows, and tools.
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import { VideoPlayer } from "@site/src/components/video-player";
+
+# Mastra Quickstart
+
+The `create mastra` CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt
+
+If you need more control over the setup, see the [manual installation guide](/docs/v1/getting-started/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.
+
+## Before you begin
+
+* You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
+
+## Initialize Mastra
+
+You can run `create mastra` anywhere on your machine.
+
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+<Tabs>
+<TabItem value="npm" label="npm">
+
+```bash copy
+npm create mastra@beta
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash copy
+pnpm create mastra@beta
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash copy
+yarn create mastra@beta
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash copy
+bun create mastra@beta
+```
+
+:::warning
+
+Due to a [known issue with Bun](https://github.com/oven-sh/bun/issues/25314) you'll need to run these steps after creating the project:
+
+- `bun add @mastra/server@beta`
+- Delete your `node_modules` folder
+- Delete your `bun.lock` file
+- Run `bun install` to reinstall your packages
+
+:::
+
+</TabItem>
+</Tabs>
+
+This creates a new directory for your project with a `src/mastra` folder containing an example weather agent and the following files:
+
+- `index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+- `agents/weather-agent.ts` - a weather agent with a prompt that uses the tool
+
+:::tip
+
+You can use [flags](/reference/v1/cli/create-mastra#cli-flags)  with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates)
+
+:::
+
+## Test your agent
+
+Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at [localhost:4111](http://localhost:4111).
+
+Try asking about the weather. If your API key is set up correctly, you'll get a response:
+
+<VideoPlayer src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4" />
+
+[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 app using the guides below.
+
+## Next steps
+
+- Integrate Mastra with your frontend framework: [Next.js](/guides/v1/getting-started/next-js), [React](/guides/v1/getting-started/vite-react), or [Astro](/guides/v1/getting-started/astro)
+- Read more about [Mastra's features](/docs/v1#why-mastra)
+- 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/{frameworks/web-frameworks → guides/getting-started}/sveltekit.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your SvelteKit project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your SvelteKit project | Frameworks"
 description: A step-by-step guide to integrating Mastra with SvelteKit.
 ---
 
@@ -27,27 +27,27 @@ Use this guide to scaffold and integrate Mastra with your SvelteKit project.
 
 Install Mastra
 
-Install the required Mastra packages:
+Install the required packages:
 
 <Tabs>
   <TabItem value="npm" label="npm">
     ```bash copy
-    npm install mastra@beta @mastra/core@beta @mastra/libsql@beta
+    npm install mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
   <TabItem value="yarn" label="yarn">
     ```bash copy
-    yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta
+    yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
   <TabItem value="pnpm" label="pnpm">
     ```bash copy
-    pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta
+    pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
   <TabItem value="bun" label="bun">
     ```bash copy
-    bun add mastra@beta @mastra/core@beta @mastra/libsql@beta
+    bun add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
 </Tabs>
@@ -128,14 +128,13 @@ Add `.mastra` to your `.gitignore` file:
 
 Update the Mastra Agent
 
-```diff title="src/mastra/agents/weather-agent.ts"
-- import { openai } from "@ai-sdk/openai";
-+ import { createOpenAI } from "@ai-sdk/openai";
+```typescript title="src/mastra/agents/weather-agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
 
-+ const openai = createOpenAI({
-+   apiKey: import.meta.env?.VITE_OPENAI_API_KEY || process.env.VITE_OPENAI_API_KEY,
-+   compatibility: "strict"
-+ });
+ const openai = createOpenAI({
+   apiKey: import.meta.env?.VITE_OPENAI_API_KEY || process.env.VITE_OPENAI_API_KEY,
+   compatibility: "strict"
+ });
 ```
 
 By reading env vars from both `import.meta.env` and `process.env`, we ensure that the API key is available in both the SvelteKit dev server and the Mastra Dev Server.
@@ -258,27 +257,27 @@ If you need more details or information about a different location, feel free to
 
 <StepItem>
 
-Install the required Mastra packages:
+Install the required packages:
 
 <Tabs>
   <TabItem value="npm" label="npm">
     ```bash copy
-    npm install mastra@beta @mastra/core@beta @mastra/libsql@beta
+    npm install mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
   <TabItem value="yarn" label="yarn">
     ```bash copy
-    yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta
+    yarn add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
   <TabItem value="pnpm" label="pnpm">
     ```bash copy
-    pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta
+    pnpm add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
   <TabItem value="bun" label="bun">
     ```bash copy
-    bun add mastra@beta @mastra/core@beta @mastra/libsql@beta
+    bun add mastra@beta @mastra/core@beta @mastra/libsql@beta @ai-sdk/openai
     ```
   </TabItem>
 </Tabs>
@@ -359,14 +358,13 @@ Add `.mastra` to your `.gitignore` file:
 
 Update the Mastra Agent
 
-```diff title="src/mastra/agents/weather-agent.ts"
-- import { openai } from "@ai-sdk/openai";
-+ import { createOpenAI } from "@ai-sdk/openai";
+```typescript title="src/mastra/agents/weather-agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
 
-+ const openai = createOpenAI({
-+   apiKey: import.meta.env?.VITE_OPENAI_API_KEY || process.env.VITE_OPENAI_API_KEY,
-+   compatibility: "strict"
-+ });
+const openai = createOpenAI({
+   apiKey: import.meta.env?.VITE_OPENAI_API_KEY || process.env.VITE_OPENAI_API_KEY,
+   compatibility: "strict"
+ });
 ```
 
 By reading env vars from both `import.meta.env` and `process.env`, we ensure that the API key is available in both the SvelteKit dev server and the Mastra Dev Server.
@@ -499,4 +497,4 @@ If you need more details or information about a different location, feel free to
 
 ## Next steps
 
-- [Monorepo Deployment](../../deployment/monorepo)
+- [Monorepo Deployment](/docs/v1/deployment/monorepo)

package/.docs/raw/{frameworks/web-frameworks → guides/getting-started}/vite-react.mdx

@@ -1,12 +1,12 @@
 ---
-title: "Integrate Mastra in your Vite/React project | Frameworks | Mastra Docs"
-description: A step-by-step guide to integrating Mastra with Vite and React.
+title: "Integrate Mastra in your React + Vite project | Frameworks"
+description: A step-by-step guide to integrating Mastra with React and Vite.
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Integrate Mastra in your Vite/React project
+# Integrate Mastra in your React + Vite project
 
 Mastra integrates with Vite, making it easy to:
 
@@ -14,11 +14,11 @@ Mastra integrates with Vite, making it easy to:
 - Simplify deployment with a unified codebase for frontend and backend
 - Take advantage of Mastra's Client SDK
 
-Use this guide to scaffold and integrate Mastra with your Vite/React project.
+Use this guide to scaffold and integrate Mastra with your React + Vite project.
 
 :::warning
 
-This guide assumes you're using Vite/React with React Router v7 at the root of your project, e.g., `app`.
+This guide assumes you're using React + Vite with React Router v7 at the root of your project, e.g., `app`.
 
 :::
 
@@ -81,7 +81,7 @@ npx mastra@latest init
 
 :::warning
 
-By default, `mastra init` suggests `src` as the install location. If you're using Vite/React at the root of your project (e.g., `app`, not `src/app`), enter `.` when prompted:
+By default, `mastra init` suggests `src` as the install location. If you're using React + Vite at the root of your project (e.g., `app`, not `src/app`), enter `.` when prompted:
 
 :::
 
@@ -252,4 +252,4 @@ The current weather in London is partly cloudy with a temperature of 19.3°C, fe
 
 ## Next steps
 
-- [Monorepo Deployment](../../deployment/monorepo)
+- [Monorepo Deployment](/docs/v1/deployment/monorepo)

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

@@ -16,7 +16,7 @@ You'll create a workflow that gathers information from a candidate's resume, the
 
 - 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)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Building the Workflow
 
@@ -58,13 +58,12 @@ To the existing `src/mastra/workflows/candidate-workflow.ts` file add the follow
 
 ```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"),
+  model: "openai/gpt-5.1",
 });
 
 const gatherCandidateInfo = createStep({

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

@@ -19,7 +19,7 @@ You'll learn how to create the agent and register it with Mastra. Next, you'll i
 
 - 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)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Creating the Agent
 
@@ -32,7 +32,6 @@ To create an agent in Mastra use the `Agent` class to define it and then registe
 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({
@@ -41,7 +40,7 @@ export const chefAgent = new 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"),
+  model: "openai/gpt-5.1",
 });
 ```
 

package/.docs/raw/guides/guide/notes-mcp-server.mdx

@@ -18,7 +18,7 @@ In this guide, you'll learn how to build a complete MCP (Model Context Protocol)
 
 - 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)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Adding necessary dependencies & files
 
@@ -38,7 +38,7 @@ npm install @mastra/mcp@beta
 
 <StepItem>
 
-After following the default [installation guide](/docs/v1/getting-started/installation) your project will include files that are not relevant for this guide. You can safely remove them:
+After following the default [installation guide](/guides/v1/getting-started/quickstart) your project will include files that are not relevant for this guide. You can safely remove them:
 
 ```bash copy
 rm -rf src/mastra/agents src/mastra/workflows src/mastra/tools/weather-tool.ts

package/.docs/raw/guides/guide/research-assistant.mdx

@@ -16,7 +16,7 @@ You'll use the foundational Transformer paper ["Attention Is All You Need"](http
 
 - 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)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## How RAG works
 
@@ -57,7 +57,7 @@ Let's define the agent's behavior, connect it to your Mastra project, and create
 
 Install additional dependencies
 
-After running the [installation guide](/docs/v1/getting-started/installation) you'll need to install additional dependencies:
+After running the [installation guide](/guides/v1/getting-started/quickstart) you'll need to install additional dependencies:
 
 ```bash copy
 npm install @mastra/rag@beta ai@^4.0.0
@@ -76,14 +76,14 @@ Create a new file `src/mastra/agents/researchAgent.ts` and define your agent:
 
 ```ts copy title="src/mastra/agents/researchAgent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 import { createVectorQueryTool } from "@mastra/rag";
 
 // Create a tool for semantic search over the paper embeddings
 const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "libSqlVector",
   indexName: "papers",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 export const researchAgent = new Agent({
@@ -94,7 +94,7 @@ export const researchAgent = new Agent({
     and provide accurate, well-supported answers based on the retrieved content.
     Focus on the specific content available in the tool and acknowledge if you cannot find sufficient information to answer a question.
     Base your responses only on the content provided, not on general knowledge.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: {
     vectorQueryTool,
   },
@@ -229,9 +229,8 @@ This allows the agent to efficiently search and retrieve relevant information.
 
 Open the `src/store.ts` file and add the following:
 
-```ts copy title="src/store.ts" {2-4, 20-99}
+```ts copy title="src/store.ts"
 import { MDocument } from "@mastra/rag";
-import { openai } from "@ai-sdk/openai";
 import { embedMany } from "ai";
 import { mastra } from "./mastra";
 
@@ -251,7 +250,7 @@ const chunks = await doc.chunk({
 
 // Generate embeddings
 const { embeddings } = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: chunks.map((chunk) => chunk.text),
 });
 

package/.docs/raw/guides/guide/stock-agent.mdx

@@ -17,7 +17,7 @@ In this guide, you're going to create a simple agent that fetches the last day's
 
 - 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)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Creating the Agent
 
@@ -30,7 +30,6 @@ To create an agent in Mastra use the `Agent` class to define it and then registe
 Create a new file `src/mastra/agents/stockAgent.ts` and define your agent:
 
 ```ts copy title="src/mastra/agents/stockAgent.ts"
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const stockAgent = new Agent({
@@ -38,7 +37,7 @@ export const stockAgent = new Agent({
   name: "Stock Agent",
   instructions:
     "You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 ```
 
@@ -104,8 +103,7 @@ export const stockPrices = createTool({
 
 Inside `src/mastra/agents/stockAgent.ts` import your newly created `stockPrices` tool and add it to the agent.
 
-```ts copy title="src/mastra/agents/stockAgent.ts" {3, 10-12}
-import { openai } from "@ai-sdk/openai";
+```ts copy title="src/mastra/agents/stockAgent.ts" {9-11}
 import { Agent } from "@mastra/core/agent";
 import { stockPrices } from "../tools/stockPrices";
 
@@ -114,7 +112,7 @@ export const stockAgent = new Agent({
   name: "Stock Agent",
   instructions:
     "You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: {
     stockPrices,
   },

package/.docs/raw/guides/guide/web-search.mdx

@@ -19,7 +19,7 @@ When building a web search agent, you have two main strategies to consider:
 
 - 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)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/getting-started/quickstart) to set up a new project)
 
 ## Using native search tools
 
@@ -61,7 +61,7 @@ Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'openai/gpt-4o-mini',
+        model: "openai/gpt-5.1",
     });
     ```
 
@@ -76,7 +76,7 @@ Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'google/gemini-2.5-flash',
+        model: "google/gemini-2.5-flash",
     });
     ```
 
@@ -93,7 +93,7 @@ Setup the tool:
 <Tabs>
     <TabItem value="openai" label="Open AI">
 
-    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-11}
+    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-12}
     import { openai } from "@ai-sdk/openai";
     import { Agent } from "@mastra/core/agent";
 
@@ -102,7 +102,7 @@ Setup the tool:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'openai/gpt-4o-mini',
+        model: "openai/gpt-5.1",
         tools: {
             webSearch: openai.tools.webSearch()
         }
@@ -112,7 +112,7 @@ Setup the tool:
     </TabItem>
     <TabItem value="gemini" label="Gemini">
 
-    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-11}
+    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-14}
     import { google } from "@ai-sdk/google";
     import { Agent } from "@mastra/core/agent";
 
@@ -121,9 +121,11 @@ Setup the tool:
         name: "Search Agent",
         instructions:
             "You are a search agent that can search the web for information.",
-        model: 'google/gemini-2.5-flash',
+        model: "google/gemini-2.5-flash",
         tools: {
-            webSearch: google.tools.googleSearch()
+          webSearch: google.tools.googleSearch({
+            mode: "MODE_DYNAMIC"
+          })
         }
     });
     ```
@@ -191,7 +193,7 @@ export const searchAgent = new Agent({
   name: "Search Agent",
   instructions:
     "You are a search agent that can search the web for information.",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
 });
 ```
 
@@ -252,7 +254,7 @@ export const searchAgent = new Agent({
   name: "Search Agent",
   instructions:
     "You are a search agent that can search the web for information.",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   tools: {
     webSearch,
   },