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

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

@@ -9,6 +9,26 @@ Storage APIs have been standardized with consistent pagination and naming patter
 
 ## Changed
 
+### Required `id` property for storage instances
+
+Storage instances now require an `id` property. This unique identifier is used for tracking and managing storage instances within Mastra. The `id` should be a descriptive, unique string for each storage instance in your application.
+
+To migrate, add an `id` field to your storage constructor.
+
+```diff
+  const storage = new PostgresStore({
++   id: 'main-postgres-store',
+    connectionString: process.env.POSTGRES_CONNECTION_STRING,
+    schemaName: 'public',
+  });
+
+  const upstashStore = new UpstashStore({
++   id: 'upstash-cache-store',
+    url: process.env.UPSTASH_REDIS_REST_URL,
+    token: process.env.UPSTASH_REDIS_REST_TOKEN,
+  });
+```
+
 ### Pagination from `offset/limit` to `page/perPage`
 
 All pagination APIs now use `page` and `perPage` instead of `offset` and `limit`. This change provides a more intuitive pagination model that aligns with common web pagination patterns.
@@ -50,6 +70,16 @@ To migrate, rename the method and update pagination parameters. You can now use
 + });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/storage-get-messages-paginated .
+```
+
+:::
+
 ### `getThreadsByResourceId` to `listThreadsByResourceId`
 
 The `getThreadsByResourceId()` method has been renamed to `listThreadsByResourceId()`. This change aligns with the convention that `list*` methods return collections.
@@ -65,6 +95,16 @@ To migrate, rename the method call and update pagination parameters.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/storage-get-threads-by-resource .
+```
+
+:::
+
 ### `getWorkflowRuns` to `listWorkflowRuns`
 
 The `getWorkflowRuns()` method has been renamed to `listWorkflowRuns()`. This change aligns with the convention that `list*` methods return collections.
@@ -81,6 +121,16 @@ To migrate, rename the method call and update pagination parameters.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/storage-list-workflow-runs .
+```
+
+:::
+
 ### `getMessagesById` to `listMessagesById`
 
 The `getMessagesById()` method has been renamed to `listMessagesById()`. This change aligns with the convention that `list*` methods return collections.
@@ -94,6 +144,16 @@ To migrate, rename the method call.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/storage-list-messages-by-id .
+```
+
+:::
+
 ### Storage `getMessages` and `saveMessages` signatures
 
 The `getMessages()` and `saveMessages()` methods have changed signatures and return types. Format overloads have been removed, and the methods now always work with `MastraDBMessage`. This change simplifies the API by removing format variations.
@@ -169,6 +229,16 @@ To migrate, pass the connection string as an object property.
 + });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/vector-pg-constructor .
+```
+
+:::
+
 ### PGVector `defineIndex` to `buildIndex`
 
 The `defineIndex()` method has been removed in favor of `buildIndex()`. This change provides clearer naming for the index building operation.
@@ -198,6 +268,16 @@ To migrate, rename the parameter.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/storage-postgres-schema-name .
+```
+
+:::
+
 ### Score storage methods to `listScoresBy*` pattern
 
 Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change provides consistency with the broader API naming conventions.

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

@@ -113,3 +113,63 @@ npx @mastra/codemod@beta v1/runtime-context .
 ```
 
 :::
+
+This applies to all tool executions, whether called directly or through agents and workflows. The type narrowing ensures you handle validation errors appropriately and prevents runtime errors when accessing output properties.
+
+### Tool output validation with `outputSchema`
+
+Tools with an `outputSchema` now validate their return values at runtime. Previously, `outputSchema` was only used for type inference - the output was never validated.
+
+If your tool returns data that doesn't match its `outputSchema`, it will now return a `ValidationError` instead of the invalid data.
+
+To fix validation errors, ensure the tool's output matches the schema definition:
+
+```diff
+  const getUserTool = createTool({
+    id: "get-user",
+    outputSchema: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string().email(),
+    }),
+    execute: async (inputData) => {
+-     return { id: "123", name: "John" }; // Missing email
++     return { id: "123", name: "John", email: "john@example.com" };
+    },
+  });
+```
+
+When validation fails, the tool returns a `ValidationError`:
+
+```diff
++ // Before v1 - invalid output would silently pass through
+  await getUserTool.execute({});
+- // { id: "123", name: "John" } - missing email
++ // {
++ //   error: true,
++ //   message: "Tool output validation failed for get-user. The tool returned invalid output:\n- email: Required\n\nReturned output: {...}",
++ //   validationErrors: { ... }
++ // }
+```
+
+### `tool.execute` return type includes `ValidationError`
+
+The return type of `tool.execute` now includes `ValidationError` to handle validation failures. You must narrow the result type before accessing output schema properties to satisfy TypeScript's type checking.
+
+When calling `tool.execute`, check if the result contains an error before accessing output properties:
+
+```typescript
+const result = await getUserTool.execute({});
+
+// Type-safe check for validation errors
+if ('error' in result && result.error) {
+  console.error('Validation failed:', result.message);
+  console.error('Details:', result.validationErrors);
+  return;
+}
+
+// TypeScript knows result is valid here
+console.log(result.id, result.name, result.email);
+```
+
+Alternatively, update the `outputSchema` to match your actual output, or remove `outputSchema` entirely if you don't need validation.

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

@@ -5,10 +5,34 @@ description: "Learn how to migrate vector-related changes when upgrading to v1."
 
 # Vectors
 
-Vector store methods have been renamed to follow consistent naming conventions.
+Vector store constructors now require an `id` property, and vector store methods have been renamed to follow consistent naming conventions.
 
 ## Changed
 
+### Required `id` property for vector store instances
+
+Vector store instances now require an `id` property. This unique identifier is used for tracking and managing vector store instances within Mastra. The `id` should be a descriptive, unique string for each vector store in your application.
+
+To migrate, add an `id` field to your vector store constructor.
+
+```diff
+  const vectorStore = new PgVector({
++   id: 'main-vector-store',
+    connectionString: process.env.POSTGRES_CONNECTION_STRING,
+  });
+
+  const chromaStore = new ChromaVector({
++   id: 'chroma-embeddings',
+    url: process.env.CHROMA_URL,
+  });
+
+  const pineconeStore = new PineconeVector({
++   id: 'pinecone-production',
+    apiKey: process.env.PINECONE_API_KEY,
+    environment: process.env.PINECONE_ENVIRONMENT,
+  });
+```
+
 ### `getVectors` to `listVectors`
 
 The `getVectors()` method has been renamed to `listVectors()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.

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

@@ -25,7 +25,7 @@ To migrate, replace all calls to `mastra.getWorkflows()` with `mastra.listWorkfl
 You can use Mastra's codemod CLI to update your imports automatically:
 
 ```shell
-npx @mastra/codemod@beta v1/workflows-get-workflows .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -68,6 +68,16 @@ To migrate, rename method calls from `createRunAsync` to `createRun`.
 + await workflow.createRun({ input: { ... } });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-create-run-async .
+```
+
+:::
+
 ### `runCount` to `retryCount` (deprecated)
 
 The `runCount` parameter has been deprecated in favor of `retryCount` in workflow step execution. This change provides clearer naming that better describes retry behavior. The old `runCount` still works but shows deprecation warnings.
@@ -83,6 +93,16 @@ To migrate, rename `runCount` to `retryCount` in step execution functions.
   });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-run-count .
+```
+
+:::
+
 ### `getWorkflowRuns` to `listWorkflowRuns`
 
 The `getWorkflowRuns()` method has been renamed to `listWorkflowRuns()`. This change aligns with the convention that `list*` methods return collections.
@@ -94,6 +114,28 @@ To migrate, rename method calls from `getWorkflowRuns` to `listWorkflowRuns`.
 + const runs = await workflow.listWorkflowRuns({ fromDate, toDate });
 ```
 
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/workflow-list-runs .
+```
+
+:::
+
+### Inputs are validated by default
+
+Previously, inputs weren't validated by default. The [`validateInputs`](/reference/v1/workflows/workflow#workflowoptions) flag determines whether to validate the workflow inputs or not. This boolean has been flipped to `true`. If you want the old behavior or have workflows whose schemas don't need to be validated, set `validateInputs: false`.
+
+```diff
+createWorkflow({
++  options: {
++    validateInputs: false
++  }
+})
+```
+
 ## Removed
 
 ### Legacy workflows export

package/.docs/raw/guides/quickstarts/nextjs.mdx

@@ -5,11 +5,11 @@ description: "Get started with Mastra, Next.js, and AS SDK UI. Quickly."
 
 # Next.js Quickstart
 
-In this quickstart, you'll build an AI agent with tool-calling capabilities using [Mastra](/docs/v1), then connect it to Next.js by importing and calling the agent directly within your routes. 
+In this quickstart, you'll build a tool-calling AI agent using Mastra, then connect it to Next.js by importing and calling the agent directly from your routes.
 
-You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience. 
+You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience.
 
-In ~5 minutes, you'll have a functional AI-powered app ready to extend with your own tools and logic.
+In about 5 minutes, you'll have a functional AI-powered app ready to extend with your own tools and logic.
 
 <figure>
 ![Screenshot of a chat-style web app displaying a completed "weatherTool" tool call, answering "What is the weather in London?" with a JSON result. A message suggests offering activity ideas, and a text input field is at the bottom.](/img/nextjs-quickstart.png)
@@ -18,7 +18,7 @@ In ~5 minutes, you'll have a functional AI-powered app ready to extend with your
 
 ## 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](https://platform.openai.com/api-keys).
+* 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).
 
 ## Create a new Next.js app
 
@@ -41,7 +41,7 @@ npx create-next-app \
 This creates a project called `my-nextjs-agent`, but you can replace it with any name you want.
 
 ## Initialize Mastra
-`cd` and run [`mastra init`](/reference/v1/cli/create-mastra). 
+`cd` and run [`mastra init`](/reference/v1/cli/create-mastra).
 
 When prompted, choose a provider (e.g. OpenAI) and enter your key:
 
@@ -58,14 +58,15 @@ This creates a `src/mastra` folder with an example weather agent and the followi
 You'll call `weather-agent.ts` from your Next.js routes in the next steps.
 
 
-## Install AI SDK UI and AI Elements
+## Install AI SDK and AI Elements
 
-Install AI SDK UI along with the Mastra adapter:
+Install AI SDK along with the Mastra adapter:
 
 ```bash
 npm install \
     @mastra/ai-sdk \
-    @ai-sdk/react 
+    @ai-sdk/react \
+    ai
 ```
 
 Next, initialize AI Elements. When prompted, choose the default options:
@@ -112,7 +113,7 @@ export async function GET() {
     resourceId: "weather-chat",
   });
 
-  const uiMessages = 
+  const uiMessages =
     convertMessages(response?.uiMessages ?? []).to("AIV5.UI");
   return NextResponse.json(uiMessages);
 }
@@ -190,8 +191,8 @@ function Chat() {
                 {message.parts?.map((part: any, i: number) => {
                   if (part.type === 'text') {
                     return (
-                      <Message 
-                        key={`${message.id}-${i}`} 
+                      <Message
+                        key={`${message.id}-${i}`}
                         from={message.role}>
                           <MessageContent>
                             <MessageResponse>{part.text}</MessageResponse>
@@ -251,16 +252,16 @@ This component connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-u
 It renders the response text using the [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) component, and shows any tool invocations with the [`<Tool>`](https://ai-sdk.dev/elements/components/tool) component.
 
 
-## Test your agent 
+## Test your agent
 1. Run your Next.js app with `npm run dev`
 
 2. Open the chat at http://localhost:3000/chat
 
-3. Try asking about the weather. If your API key is set up correctly, you'll get a response.
+3. Try asking about the weather. If your API key is set up correctly, you'll get a response
 
 ## Next steps
 
-Congratulations on building your Mastra agent with Next.js! 🎉 
+Congratulations on building your Mastra agent with Next.js! 🎉
 
 From here, you can extend the project with your own tools and logic:
 
@@ -268,8 +269,8 @@ From here, you can extend the project with your own tools and logic:
 - Give your agent its own [tools](/docs/v1/agents/using-tools)
 - Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
 
-When you're ready, read more about how Mastra integrates with AI SDK and Next.js, and how to deploy to Vercel:
+When you're ready, read more about how Mastra integrates with AI SDK and Next.js, and how to deploy your agent anywhere, including Vercel:
 
 - Integrate Mastra with [AI SDK](/docs/v1/frameworks/agentic-uis/ai-sdk)
-- Use Mastra in your [Next.js app](/docs/v1/frameworks/web-frameworks/next-js)
-- Deploy your agent to [Vercel](/docs/v1/deployment/serverless-platforms/vercel-deployer)
+- Deploy your agent to [Vercel](/docs/v1/deployment/cloud-providers/vercel-deployer)
+- Deploy your agent [anywhere](/docs/v1/deployment/overview)

package/.docs/raw/guides/quickstarts/standalone-server.mdx

@@ -0,0 +1,86 @@
+---
+title: "Standalone Server Quickstart"
+description: Get started with Mastra using the create mastra CLI to build a standalone 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";
+
+# Standalone Server Quickstart
+
+The `create mastra` CLI command is the quickest way to spin up a standalone Mastra server. 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](/guides/v1/guide/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
+```
+
+</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](/docs/v1/getting-started/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](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/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/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: "About Mastra | Mastra Docs"
+title: "About Mastra"
 sidebar_position: 2
 sidebar_label: "Introduction"
 description: "Mastra is an all-in-one framework for building AI-powered applications and agents with a modern TypeScript stack."
@@ -51,8 +51,8 @@ Explore real-world examples in our [community showcase](/showcase).
 
 ## Get started
 
-Follow the [Installation guide](/docs/v1/getting-started/installation) for step-by-step setup with the CLI or a manual install.
+Choose a [quickstart](/docs/v1/getting-started/quickstart) to get started, or see the [manual installation guide](/guides/v1/guide/manual-install) if you need more control over your setup.
 
-If you're new to AI agents, check out our [templates](/docs/v1/getting-started/templates), [course](https://mastra.ai/book), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
+If you're new to AI agents, check out our [templates](/docs/v1/getting-started/templates), [course](https://mastra.ai/course), and [YouTube videos](https://youtube.com/@mastra-ai). You can also join our [Discord](https://discord.gg/BTYqqHKUrf) community to get help and share your projects.
 
 We can't wait to see what you build ✌️

package/.docs/raw/logging.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Logging | Observability | Mastra Docs"
+title: "Logging | Observability"
 description: Learn how to use logging in Mastra to monitor execution, capture application behavior, and improve the accuracy of AI applications.
 ---
 
@@ -7,14 +7,14 @@ description: Learn how to use logging in Mastra to monitor execution, capture ap
 
 Mastra's logging system captures function execution, input data, and output responses in a structured format.
 
-When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/deployment/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
-## PinoLogger
+## Configuring logs with PinoLogger
 
-When [initializing a new Mastra project](/docs/v1/getting-started/installation) using the CLI, `PinoLogger` is included by default.
+When [initializing a new Mastra project](/guides/v1/quickstarts/standalone-server) using the CLI, `PinoLogger` is included by default.
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
+import { Mastra } from "@mastra/core/mastra";
 import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({
@@ -28,7 +28,7 @@ export const mastra = new Mastra({
 
 > See the [PinoLogger](/reference/v1/logging/pino-logger) API reference for all available configuration options.
 
-## Logging from workflows and tools
+## Customizing logs
 
 Mastra provides access to a logger instance via the `mastra.getLogger()` method, available inside both workflow steps and tools. The logger supports standard severity levels: `debug`, `info`, `warn`, and `error`.
 
@@ -79,7 +79,7 @@ export const testTool = createTool({
 });
 ```
 
-## Logging with additional data
+### Logging with additional data
 
 Logger methods accept an optional second argument for additional data. This can be any value, such as an object, string, or number.