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

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.
@@ -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
@@ -263,3 +313,73 @@ To migrate, remove the `TMetrics` generic parameter and configure scorers using
     // ...
   });
 ```
+
+### Tripwire response format changed
+
+The tripwire response format has changed from separate `tripwire` and `tripwireReason` fields to a single `tripwire` object containing all related data.
+
+To migrate, update your code to access tripwire data from the new object structure.
+
+```diff
+  const result = await agent.generate('Hello');
+
+- if (result.tripwire) {
+-   console.log(result.tripwireReason);
+- }
++ if (result.tripwire) {
++   console.log(result.tripwire.reason);
++   // New fields available:
++   // result.tripwire.retry - whether this step should be retried
++   // result.tripwire.metadata - additional metadata from the processor
++   // result.tripwire.processorId - which processor triggered the tripwire
++ }
+```
+
+For streaming responses:
+
+```diff
+  for await (const chunk of stream.fullStream) {
+    if (chunk.type === 'tripwire') {
+-     console.log(chunk.payload.tripwireReason);
++     console.log(chunk.payload.reason);
++     // New fields available:
++     // chunk.payload.retry
++     // chunk.payload.metadata
++     // chunk.payload.processorId
+    }
+  }
+```
+
+The step results now also include tripwire information:
+
+```diff
+  const result = await agent.generate('Hello');
+
+  for (const step of result.steps) {
+-   // No tripwire info on steps
++   if (step.tripwire) {
++     console.log('Step was blocked:', step.tripwire.reason);
++   }
+  }
+```
+
+### `prepareStep` messages format
+
+The `prepareStep` callback now receives messages in `MastraDBMessage` format instead of AI SDK v5 model message format. This change unifies `prepareStep` with the new `processInputStep` processor method, which runs at each step of the agentic loop.
+
+If you need the old AI SDK v5 format, use `messageList.get.all.aiV5.model()`:
+
+```diff
+  agent.generate({
+    prompt: 'Hello',
+    prepareStep: async ({ messages, messageList }) => {
+-     // messages was AI SDK v5 ModelMessage format
+-     console.log(messages[0].content);
++     // messages is now MastraDBMessage format
++     // Use messageList to get AI SDK v5 format if needed:
++     const aiSdkMessages = messageList.get.all.aiV5.model();
+
+      return { toolChoice: 'auto' };
+    },
+  });
+```

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.
 

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

@@ -11,11 +11,11 @@ Tool execution signatures have been updated to use separate input and context pa
 
 ### `createTool` execute signature to `(inputData, context)` format
 
-All **`createTool`** execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
+All `createTool` execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
 
 **Note:** This change only applies to `createTool`. If you're using `createStep` for workflows, the signature remains `async (inputData, context)` and does not need to be changed.
 
-To migrate, update **`createTool`** signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
+To migrate, update `createTool` signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
 
 ```diff
   createTool({
@@ -35,7 +35,7 @@ To migrate, update **`createTool`** signatures to use `inputData` as the first p
 
 ### `createTool` context properties organization
 
-Context properties in **`createTool`** are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
+Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
 
 For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
 
@@ -83,6 +83,11 @@ For tools that are executed inside a workflow, access workflow-specific properti
   });
 ```
 
+The `suspendPayload` gets validated against the `suspendSchema` when the tool is executed. If the suspendPayload doesn't match the `suspendSchema`, a warning is logged and the error is returned as tool output, but suspension continues.
+Also, when the tool is resumed, the `resumeData` gets validated against the `resumeSchema`. If the resumeData doesn't match the `resumeSchema`, the tool will return a `ValidationError`, preventing the tool resumption.
+
+To skip the `suspendSchema` or `resumeSchema` validation, do not define `suspendSchema` or `resumeSchema` in the tool creation.
+
 :::note
 For MCP-specific tool context changes, see the [MCP migration guide](/guides/v1/migrations/upgrade-to-v1/mcp).
 :::
@@ -113,3 +118,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.