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

package/.docs/raw/guides/index.mdx

@@ -1,43 +1,11 @@
 ---
 title: "Overview"
 description: "Guides on building with Mastra"
+showCopyButton: false
 ---
 
 import { CardGrid, CardGridItem } from "@site/src/components/CardGrid";
 
-# Guides
+# Mastra Guides
 
-While examples show quick implementations and docs explain specific features, these guides are a bit longer and designed to demonstrate core Mastra concepts:
-
-<CardGrid>
-  <CardGridItem
-    title="AI Recruiter"
-    description="Create a workflow that processes candidate resumes and conducts interviews, demonstrating branching logic and LLM integration in Mastra workflows."
-    href="/guides/v1/guide/ai-recruiter"
-  />
-  <CardGridItem
-    title="Chef Assistant"
-    description="Build an AI chef agent that helps users cook meals with available ingredients, showing how to create interactive agents with custom tools."
-    href="/guides/v1/guide/chef-michel"
-  />
-  <CardGridItem
-    title="Research Assistant"
-    description="Develop an AI research assistant that analyzes academic papers using Retrieval Augmented Generation (RAG), demonstrating document processing and question answering."
-    href="/guides/v1/guide/research-assistant"
-  />
-  <CardGridItem
-    title="Stock Agent"
-    description="Implement a simple agent that fetches stock prices, illustrating the basics of creating tools and integrating them with Mastra agents."
-    href="/guides/v1/guide/stock-agent"
-  />
-  <CardGridItem
-    title="Notes MCP Server"
-    description="Build an AI notes assistant that helps users manage their notes, showing how to create interactive agents with custom tools."
-    href="/guides/v1/guide/notes-mcp-server"
-  />
-  <CardGridItem
-    title="Web Search"
-    description="A step-by-step guide to creating an agent that can search the web."
-    href="/guides/v1/guide/web-search"
-  />
-</CardGrid>
+Mastra offers a variety of guides to help you build and work with Mastra, from building agents and workflows to using the Mastra SDK and API, and implementing different UI frameworks. To find what you need, use the left-hand side navigation to browse by topic or use the search bar to look up specific implementation details, frameworks, or features.

package/.docs/raw/guides/migrations/agentnetwork.mdx

@@ -40,7 +40,7 @@ const agent = new AgentNetwork({
   name: "agent-network",
   agents: [agent1, agent2],
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
 });
@@ -61,7 +61,7 @@ const agent = new Agent({
   name: "agent-network",
   agents: { agent1, agent2 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
   memory,
@@ -83,7 +83,7 @@ const agent = new NewAgentNetwork({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
 });
@@ -104,7 +104,7 @@ const agent = new Agent({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
   memory,

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](/guides/v1/build-your-ui/ai-sdk-ui).
+
+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 v1/agent-get-agents .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -54,7 +54,7 @@ To migrate, update all imports and parameter names from `RuntimeContext`/`runtim
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/runtime-context .
+npx @mastra/codemod@beta v1/runtime-context .
 ```
 
 :::
@@ -79,7 +79,7 @@ To migrate, replace property access with the corresponding getter methods.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/agent-property-access .
+npx @mastra/codemod@beta v1/agent-property-access .
 ```
 
 :::
@@ -104,7 +104,7 @@ To migrate, update voice method calls to use the `agent.voice` namespace.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/agent-voice .
+npx @mastra/codemod@beta v1/agent-voice .
 ```
 
 :::
@@ -140,7 +140,7 @@ To migrate, update processor method names.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/agent-processor-methods .
+npx @mastra/codemod@beta v1/agent-processor-methods .
 ```
 
 :::
@@ -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.
@@ -192,6 +202,46 @@ To migrate, update from `output` or `experimental_output` to `structuredOutput.s
   });
 ```
 
+### Agent `id` field is now required
+
+The `id` field is now required when creating an Agent. Previously, agents could be created without an explicit ID, but this is no longer supported.
+
+To migrate, add an `id` field to all Agent configurations.
+
+```diff
+  const agent = new Agent({
++   id: 'my-agent',
+    name: 'My Agent',
+    instructions: 'You are a helpful assistant',
+    model: openai('gpt-4'),
+  });
+```
+
+The `id` can be the same as the `name`, or you can use a different identifier. The ID will be used when calling `mastra.getAgentById()` and must be unique within your Mastra instance.
+
+```typescript
+// Register agent with Mastra
+const mastra = new Mastra({
+  agents: {
+    myAgent: agent, // key can differ from id
+  },
+});
+
+// Retrieve by ID
+const agent = mastra.getAgentById('my-agent');
+```
+
+### Stream API responses now redact sensitive data
+
+The Mastra server now automatically redacts sensitive information from agent stream responses. This prevents accidental exposure of system prompts, tool definitions, and API keys in `step-start`, `step-finish`, and `finish` stream chunks.
+
+**What's redacted:**
+- `request.body` containing LLM request payloads (system prompts, tool schemas)
+- `metadata.request` in step results
+- `output.steps[].request` in nested step data
+
+This behavior is enabled by default. If you need access to the full request data (e.g., for debugging or internal services), you can disable redaction when using server adapters directly (e.g., `@mastra/hono` or `@mastra/express`).
+
 ## Removed
 
 ### `generateVNext` and `streamVNext` methods
@@ -212,7 +262,7 @@ To migrate, use the standard `generate()` and `stream()` methods.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/agent-generate-stream-v-next .
+npx @mastra/codemod@beta v1/agent-generate-stream-v-next .
 ```
 
 :::

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

@@ -28,7 +28,7 @@ To migrate, update all imports from `@mastra/core` to use the appropriate subpat
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/mastra-core-imports .
+npx @mastra/codemod@beta v1/mastra-core-imports .
 ```
 
 :::
@@ -53,16 +53,16 @@ To migrate, rename the `experimental_auth` key to `auth` in your Mastra configur
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/experimental-auth .
+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 v1/mcp-get-mcp-servers .
+npx @mastra/codemod@beta v1/mastra-plural-apis .
 ```
 
 :::
@@ -46,7 +46,7 @@ To migrate, replace all calls to `mcp.getTools()` with `mcp.listTools()`.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/mcp-get-tools .
+npx @mastra/codemod@beta v1/mcp-get-tools .
 ```
 
 :::
@@ -67,7 +67,7 @@ To migrate, replace all calls to `mcp.getToolsets()` with `mcp.listToolsets()`.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod v1/mcp-get-toolsets .
+npx @mastra/codemod@beta v1/mcp-get-toolsets .
 ```
 
 :::

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