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

package/.docs/raw/{getting-started/installation.mdx → guides/guide/manual-install.mdx}

@@ -1,94 +1,20 @@
 ---
-title: "Install Mastra | Getting Started | Mastra Docs"
-description: Guide on installing Mastra and setting up the necessary prerequisites for running it with various LLM providers.
+title: "Manual Install | Guides"
+description: Set up a Mastra project manually without using the create mastra CLI.
 ---
 
 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";
 
-# Install Mastra
-
-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/v1/cli/mastra#mastra-init) for existing projects.
-
-## Before you start
-
-- 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`
-
-You can run `create mastra` anywhere on your machine.
-
-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.
-
-<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
-```
-
-</TabItem>
-</Tabs>
-
-:::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/v1/getting-started/templates). Read the [CLI reference](/reference/v1/cli/create-mastra) for all options.
-
-:::
-
-### Test your agent
-
-Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at 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" />
-
-:::note
-
-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.
+# Manual Install
 
+:::info
+Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [Standalone Server Quickstart](/guides/v1/quickstarts/standalone-server), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
 :::
 
-[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/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
-
-If you prefer not to use our automatic `create mastra` CLI tool, you can set up your project yourself by following the guide below.
+If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.
 
 <Steps>
 

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/quickstarts/standalone-server) 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/quickstarts/standalone-server) 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/quickstarts/standalone-server) 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/quickstarts/standalone-server) you'll need to install additional dependencies:
 
 ```bash copy
 npm install @mastra/rag@beta ai@^4.0.0

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/quickstarts/standalone-server) to set up a new project)
 
 ## Creating the Agent
 

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/quickstarts/standalone-server) to set up a new project)
 
 ## Using native search tools
 

package/.docs/raw/guides/migrations/ai-sdk-v4-to-v5.mdx

@@ -0,0 +1,119 @@
+---
+title: "Migration: AI SDK v4 to v5 | Migration Guide"
+description: "Mastra-specific guidance for upgrading from AI SDK v4 to v5."
+---
+
+# Migrate from AI SDK v4 to v5
+
+Looking for integration docs? See [Using AI SDK](/docs/v1/frameworks/agentic-uis/ai-sdk).
+
+Follow the official [AI SDK v5 Migration Guide](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0) for all AI SDK core breaking changes, package updates, and API changes.
+
+This guide covers only the Mastra-specific aspects of the migration.
+
+- **Data compatibility**: New data stored in v5 format will no longer work if you downgrade from v5 to v4
+- **Backup recommendation**: Keep DB backups from before you upgrade to v5
+
+### Memory and Storage
+
+Mastra automatically handles AI SDK v4 data using its internal `MessageList` class, which manages format conversion—including v4 to v5. No database migrations are required; your existing messages are translated on the fly and continue working after you upgrade.
+
+### Message Format Conversion
+
+For cases where you need to manually convert messages between AI SDK and Mastra formats, use the `convertMessages()` utility:
+
+```typescript
+import { convertMessages } from "@mastra/core/agent";
+
+// Convert AI SDK v4 messages to v5
+const aiv5Messages = convertMessages(aiv4Messages).to("AIV5.UI");
+
+// Convert Mastra messages to AI SDK v5
+const aiv5Messages = convertMessages(mastraMessages).to("AIV5.Core");
+
+// Supported output formats:
+// 'Mastra.V2', 'AIV4.UI', 'AIV5.UI', 'AIV5.Core', 'AIV5.Model'
+```
+
+This utility is helpful when you want to fetch messages directly from your storage DB and convert them for use in AI SDK.
+
+### Type Inference for Tools
+
+When using tools with TypeScript in AI SDK v5, Mastra provides type inference helpers to ensure type safety for your tool inputs and outputs.
+
+#### `InferUITool`
+
+The `InferUITool` type helper infers the input and output types of a single Mastra tool:
+
+```typescript title="app/types.ts" copy
+import { InferUITool, createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get the current weather",
+  inputSchema: z.object({
+    location: z.string().describe("The city and state"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  execute: async (inputData) => {
+    return {
+      temperature: 72,
+      conditions: "sunny",
+    };
+  },
+});
+
+// Infer the types from the tool
+type WeatherUITool = InferUITool<typeof weatherTool>;
+// This creates:
+// {
+//   input: { location: string };
+//   output: { temperature: number; conditions: string };
+// }
+```
+
+#### `InferUITools`
+
+The `InferUITools` type helper infers the input and output types of multiple tools:
+
+```typescript title="app/mastra/tools.ts" copy
+import { InferUITools, createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// Using weatherTool from the previous example
+const tools = {
+  weather: weatherTool,
+  calculator: createTool({
+    id: "calculator",
+    description: "Perform basic arithmetic",
+    inputSchema: z.object({
+      operation: z.enum(["add", "subtract", "multiply", "divide"]),
+      a: z.number(),
+      b: z.number(),
+    }),
+    outputSchema: z.object({
+      result: z.number(),
+    }),
+    execute: async (inputData) => {
+      // implementation...
+      return { result: 0 };
+    },
+  }),
+};
+
+// Infer types from the tool set
+export type MyUITools = InferUITools<typeof tools>;
+// This creates:
+// {
+//   weather: { input: { location: string }; output: { temperature: number; conditions: string } };
+//   calculator: { input: { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }; output: { result: number } };
+// }
+```
+
+These type helpers provide full TypeScript support when using Mastra tools with AI SDK v5 UI components, ensuring type safety across your application.
+
+

package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx

@@ -25,7 +25,7 @@ To migrate, replace all calls to `mastra.getAgents()` with `mastra.listAgents()`
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod@beta v1/agent-get-agents .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -177,6 +177,16 @@ To migrate, move `abortSignal` from `modelSettings` to the top level.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/agent-abort-signal .
+```
+
+:::
+
 ### `output` to `structuredOutput.schema`
 
 The deprecated `output` and `experimental_output` options have been removed. This change consolidates on a single, stable API for structured output.

package/.docs/raw/guides/migrations/upgrade-to-v1/client.mdx

@@ -28,6 +28,16 @@ To migrate, update type imports to use the new naming pattern.
 + } from '@mastra/client-js';
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/client-sdk-types .
+```
+
+:::
+
 ### Pagination parameters from `offset/limit` to `page/perPage`
 
 All client SDK methods that used `offset/limit` now use `page/perPage`. This change provides a more intuitive pagination model aligned with web pagination patterns.
@@ -44,6 +54,16 @@ To migrate, update pagination parameters in all client SDK method calls. Example
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/client-offset-limit .
+```
+
+:::
+
 ### `getMemoryThread` parameter structure
 
 The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
@@ -51,10 +71,20 @@ The `getMemoryThread` method parameter structure has been updated. This change p
 To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
 
 ```diff
-- const thread = await client.memory.getMemoryThread(threadId, agentId);
-+ const thread = await client.memory.getMemoryThread({ threadId, agentId });
+- const thread = await client.getMemoryThread(threadId, agentId);
++ const thread = await client.getMemoryThread({ threadId, agentId });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/client-get-memory-thread .
+```
+
+:::
+
 ## Removed
 
 ### `toAISdkFormat` function
@@ -70,6 +100,16 @@ To migrate, use `toAISdkStream()` instead.
 + const stream = toAISdkStream(agentStream, { from: 'agent' });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/client-to-ai-sdk-format .
+```
+
+:::
+
 ### Network memory methods
 
 Network memory methods have been removed from `@mastra/client-js`. The `NetworkMemoryThread` class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.

package/.docs/raw/guides/migrations/upgrade-to-v1/evals.mdx

@@ -25,7 +25,7 @@ To migrate, replace all calls to `getScorers()` with `listScorers()`.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod@beta v1/evals-get-scorers .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -50,6 +50,16 @@ To migrate, update function calls from `runExperiment` to `runEvals`.
 + const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/evals-run-experiment .
+```
+
+:::
+
 ### `getScorerByName` to `getScorerById`
 
 The `getScorerByName()` method has been renamed to `getScorerById()`. Scorers now require an `id` field instead of `name`. This change aligns with the broader API pattern of using `id` for entity identification.
@@ -67,6 +77,16 @@ To migrate, update method calls and scorer configuration to use `id` instead of
 + const scorer = mastra.getScorerById('helpfulness-scorer');
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/evals-scorer-by-name .
+```
+
+:::
+
 ### Scorer configuration from `name` to `id`
 
 Scorers now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities.
@@ -120,6 +140,16 @@ To migrate, update import statements to use the new `scorers/prebuilt` path.
 + import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/evals-prebuilt-imports .
+```
+
+:::
+
 ### Scorer message types from `UIMessage` to `MastraDBMessage`
 
 Scorer input and output types now use `MastraDBMessage[]` instead of `UIMessage`. This change aligns scorers with the database-persisted message format for consistency across the framework.

package/.docs/raw/guides/migrations/upgrade-to-v1/mastra.mdx

@@ -60,9 +60,9 @@ npx @mastra/codemod@beta v1/experimental-auth .
 
 ### Required `id` parameter for all mastra primitives
 
-All storage, vector stores, agents, workflows, mcpServers, processors, scorers, tools now require an `id` parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.
+All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.
 
-All these primitives also now have a `get`, `list`, and `add` functions.
+All these primitives also now have `get`, `list`, and `add` functions.
 
 To migrate, add an `id` parameter to all storage and vector store instantiations. When using the same storage/vector class multiple times, ensure each instance has a unique ID.
 
@@ -105,12 +105,36 @@ When using separate instances for different purposes, use descriptive unique IDs
 
 ### Primitive plural APIs changes from `get<primitives>` to `list<primitive>`
 
+`get*` functions that returned all instances of a primitive have been renamed to `list*` to better reflect their purpose.
+
 ```diff
+- const agents = mastra.getAgents();
++ const agents = mastra.listAgents();
+- const vectors = mastra.getVectors();
++ const vectors = mastra.listVectors();
+- const workflows = mastra.getWorkflows();
++ const workflows = mastra.listWorkflows();
+- const scorers = mastra.getScorers();
++ const scorers = mastra.listScorers();
 - const mcpServers = mastra.getMCPServers();
 + const mcpServers = mastra.listMCPServers();
+- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
++ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
+- const logs = await mastra.getLogs('transportId');
++ const logs = await mastra.listLogs('transportId');
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
-### Each primtive has a `getById` and a `get` function
+:::
+
+### Each primitive has a `getById` and a `get` function
 
 ```typescript
 mastra.getMCPServer('myServer');          // Works (registry key)

package/.docs/raw/guides/migrations/upgrade-to-v1/mcp.mdx

@@ -25,7 +25,7 @@ To migrate, replace all calls to `mastra.getMCPServers()` with `mastra.listMCPSe
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod@beta v1/mcp-get-mcp-servers .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::

package/.docs/raw/guides/migrations/upgrade-to-v1/memory.mdx

@@ -111,6 +111,16 @@ To migrate, rename `query()` to `recall()` and update code that expects the old
 + const messages = result.messages;
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/memory-query-to-recall .
+```
+
+:::
+
 ### `Memory.recall()` parameter changes
 
 The `Memory.recall()` method now uses `StorageListMessagesInput` format with pagination, and the `vectorMessageSearch` parameter has been renamed to `vectorSearchString`. These changes align the memory API with the storage pagination API and provide more consistent naming.
@@ -132,6 +142,16 @@ To migrate, update method name, query parameters, and the vector search paramete
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/memory-vector-search-param .
+```
+
+:::
+
 ### `MastraMessageV2` type renamed to `MastraDBMessage`
 
 The `MastraMessageV2` type has been renamed to `MastraDBMessage` for clarity. This change better describes the purpose of this type as the database message format.
@@ -145,7 +165,15 @@ To migrate, replace all instances of `MastraMessageV2` with `MastraDBMessage`.
 + function yourCustomFunction(input: MastraDBMessage) {}
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/memory-message-v2-type .
+```
 
+:::
 
 ## Removed
 

package/.docs/raw/guides/migrations/upgrade-to-v1/overview.mdx

@@ -13,13 +13,35 @@ Need help with the migration? Join our [Discord community](https://discord.gg/BT
 
 ## Migration Strategy
 
-### Update all Mastra packages
+### Update all Mastra packages to `beta` tag
 
 Use your package manager to update your project's versions. Be sure to update **all** Mastra packages at the same time to ensure compatibility.
 
+Here's how you update the most commonly used packages:
+
+```shell
+npm install @mastra/core@beta mastra@beta @mastra/loggers@beta @mastra/memory@beta
+```
+
+Install any other Mastra package with the `@beta` tag and you'll get the latest beta version available. Be sure to update all Mastra packages (especially if you're in a monorepo) to avoid version mismatches.
+
 ### Update Node.js version
 
-Mastra v1 requires Node.js 22.13.0 or higher. Update your development and production environments accordingly.
+Mastra v1 requires Node.js **22.13.0** or higher. Update your development and production environments accordingly.
+
+### Go through migration checklist
+
+Work through the [migration checklist](#migration-checklist) below to update your codebase. Each item links to a detailed guide for that specific change.
+
+:::info[Codemods]
+
+We prepared automated [codemods](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) for you. If you want, you can run all v1 codemods at once:
+
+```sh
+npx @mastra/codemod@beta v1
+```
+
+:::
 
 ## Breaking Changes by Area
 
@@ -41,7 +63,7 @@ Mastra v1 requires Node.js 22.13.0 or higher. Update your development and produc
 
 Work through this checklist in order, starting with high-impact changes that affect most applications.
 
-:::info[Codemod]
+:::info[Codemods]
 
 We prepared automated [codemods](https://github.com/mastra-ai/mastra/tree/main/packages/codemod) for you. Throughout the migration guide you'll find instructions on how to use them for specific changes.