@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

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

@@ -147,7 +147,7 @@ npx @mastra/codemod@beta v1/agent-processor-methods .
 
 ### Default options method renames for AI SDK versions
 
-Default options methods have been renamed to clarify legacy (AI SDK v4) vs new (AI SDK v5) APIs. This change helps developers understand which AI SDK version they're targeting.
+Default options methods have been renamed to clarify legacy (AI SDK v4) vs new (AI SDK v5+) APIs. This change helps developers understand which AI SDK version they're targeting.
 
 To migrate, update method names based on which AI SDK version you're using.
 
@@ -158,7 +158,7 @@ To migrate, update method names based on which AI SDK version you're using.
 + const options = await agent.getDefaultGenerateOptionsLegacy();
 + const streamOptions = await agent.getDefaultStreamOptionsLegacy();
 
-  // For new AI SDK v5 (default)
+  // For new AI SDK v5+ (default)
   const streamOptions = await agent.getDefaultStreamOptions();
 ```
 
@@ -213,7 +213,7 @@ To migrate, add an `id` field to all Agent configurations.
 +   id: 'my-agent',
     name: 'My Agent',
     instructions: 'You are a helpful assistant',
-    model: openai('gpt-4'),
+    model: 'openai/gpt-4',
   });
 ```
 
@@ -246,7 +246,7 @@ This behavior is enabled by default. If you need access to the full request data
 
 ### `generateVNext` and `streamVNext` methods
 
-The deprecated `generateVNext()` and `streamVNext()` methods have been removed. These methods were previously used for AI SDK v5 compatibility but are now the standard implementation.
+The deprecated `generateVNext()` and `streamVNext()` methods have been removed. These methods were previously used for AI SDK v5+ compatibility but are now the standard implementation.
 
 To migrate, use the standard `generate()` and `stream()` methods.
 
@@ -313,3 +313,104 @@ 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('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' };
+    },
+  });
+```
+
+### `threadId` and `resourceId` to `memory` option
+
+The `threadId` and `resourceId` options have been removed from `agent.stream()` and `agent.generate()`. Use the `memory` option instead, which provides a cleaner API for memory configuration.
+
+To migrate, move `threadId` and `resourceId` into the `memory` option:
+
+```diff
+  await agent.stream('Hello', {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+```
+
+The `memory` option also supports passing thread metadata when creating new threads:
+
+```typescript
+await agent.stream('Hello', {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+});
+```

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

@@ -5,7 +5,21 @@ description: "Learn how to migrate CLI changes when upgrading to v1."
 
 # CLI
 
-The CLI has been simplified by removing deployment commands, configuration flags, and starter files.
+The CLI has been simplified by removing deployment commands, configuration flags, and starter files. A new migration command has been added to help with database schema upgrades.
+
+## Added
+
+### `mastra migrate` command
+
+A new `mastra migrate` command helps run database migrations when upgrading Mastra versions. This is particularly useful when upgrading from older versions that may have data incompatibilities.
+
+```bash
+npx mastra migrate
+```
+
+The command bundles your project, connects to your configured storage, and runs any necessary migrations. Currently supports migrating duplicate spans entries that may prevent unique constraint creation.
+
+See the [Storage migration guide](/guides/v1/migrations/upgrade-to-v1/storage#duplicate-spans-migration) for details on when this migration is needed.
 
 ## Removed
 

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

@@ -9,6 +9,103 @@ Client SDK changes align with server-side API updates including renamed utilitie
 
 ## Changed
 
+### `messages` is now identical to `@mastra/core/agent` syntax
+
+The `messages` argument is now the first argument of the `generate`, `stream` and `network` method calls, similar to the NodeJS version in `@mastra/core/agent`.
+
+To migrate, move `messages` to the first argument of the method call:
+
+**Using `@mastra/client-js`:**
+
+```diff
+  const agent = client.getAgent('my-agent');
+
+-  await agent.generate({
+-    messages: [...]
++  await agent.generate([...], {
+  });
+
+-  await agent.stream({
+-    messages: [...]
++  await agent.stream([...], {
+  });
+
+-  await agent.network({
+-    messages: [...]
++  await agent.network([...], {
+  });
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/client-msg-function-args .
+```
+
+:::
+
+### `threadId` and `resourceId` to `memory` option
+
+The `threadId` and `resourceId` options have been removed from agent method calls. Use the `memory` option instead, which provides a cleaner API for memory configuration. This applies to both `@mastra/client-js` and `@mastra/react` packages.
+
+To migrate, move `threadId` and `resourceId` into the `memory` option:
+
+**Using `@mastra/client-js`:**
+
+```diff
+  const agent = client.getAgent('my-agent');
+
+  await agent.generate([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+
++  await agent.stream([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+```
+
+**Using `@mastra/react` `useChat` hook:**
+
+The `useChat` hook internally passes the memory option when you provide a `threadId`. No changes are needed in your component code if you're using the hook's built-in memory handling. However, if you were manually passing options to `sendMessage`, update them accordingly:
+
+```diff
+  const { sendMessage } = useChat({ agentId: 'my-agent' });
+
+  await sendMessage({
+    message: 'Hello',
+    mode: 'stream',
+-   threadId: 'thread-123',
++   threadId: 'thread-123', // Still works - internally converted to memory option
+  });
+```
+
+The `memory` option also supports passing thread metadata when creating new threads:
+
+```typescript
+await agent.generate([...], {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+});
+```
+
 ### Client SDK types from `Get*` to `List*`
 
 Client SDK types have been renamed from `Get*` to `List*` pattern. This change aligns type names with the method naming convention.
@@ -85,8 +182,52 @@ npx @mastra/codemod@beta v1/client-get-memory-thread .
 
 :::
 
+### Unified `runById` API for workflow runs
+
+The `runById()` method now returns a unified `WorkflowState` object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate `runById()` and `runExecutionResult()` methods.
+
+The method also accepts an options object with optional `fields` and `withNestedWorkflows` parameters for performance optimization.
+
+```diff
+  const workflow = client.getWorkflow('my-workflow');
+
+- // Previously: runById returned raw WorkflowRun with snapshot
+- const run = await workflow.runById(runId, requestContext);
+- // Separately: runExecutionResult returned processed execution state
+- const result = await workflow.runExecutionResult(runId);
+
++ // Now: Single method returns unified WorkflowState
++ const run = await workflow.runById(runId, {
++   requestContext,  // Optional request context
++   fields: ['status', 'result'],  // Optional: request only specific fields
++   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
++ });
++ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
+```
+
 ## Removed
 
+### `runExecutionResult` method and `GetWorkflowRunExecutionResultResponse` type
+
+The `runExecutionResult()` method and `GetWorkflowRunExecutionResultResponse` type have been removed from `@mastra/client-js`. The `/execution-result` API endpoints have also been removed.
+
+To migrate, use `runById()` instead, which now returns the same unified `WorkflowState` with both metadata and processed execution state.
+
+```diff
+- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const result = await workflow.runExecutionResult(runId);
+
++ const workflow = client.getWorkflow('my-workflow');
++ const result = await workflow.runById(runId);
++ // Or with options for performance optimization:
++ const result = await workflow.runById(runId, {
++   fields: ['status', 'result'],  // Only fetch specific fields
++   withNestedWorkflows: false,     // Skip expensive nested workflow data
++ });
+```
+
 ### `toAISdkFormat` function
 
 The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. This change provides clearer naming for stream conversion utilities.
@@ -155,6 +296,35 @@ To migrate, use workflow streaming APIs instead of watch.
 + }
 ```
 
+### Run-related methods cannot be called directly on workflow instance
+
+Run-related methods cannot be called directly on workflow instance. You need to create a run instance first using `createRun()` method.
+
+
+```diff
+- const result = await workflow.start({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const result = await run.start({ inputData: { ... } });
+```
+
+```diff
+- const result = await workflow.stream({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
+
+The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
+
+To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods instead.
+
+```diff
++ const run = await workflow.createRun({ runId: '123' });
+- const stream = await run.streamVNext({ inputData: { ... } });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
 ### Deprecated stream endpoints
 
 Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.

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

@@ -0,0 +1,42 @@
+---
+title: "Deployment | v1 Migration Guide"
+description: "Learn how to migrate deployment configuration when upgrading to v1."
+---
+
+# Deployment
+
+The `CloudflareDeployer` configuration has been updated to use standard `wrangler.json` property names.
+
+## Changed
+
+### CloudflareDeployer uses standard wrangler.json property names
+
+The `CloudflareDeployer` constructor now accepts standard `wrangler.json` property names instead of custom camelCase variants. This change aligns the deployer with Cloudflare's official configuration format and provides access to all wrangler configuration options.
+
+Deprecated fields are automatically migrated at runtime with console warnings, but you should update your code to use the new field names.
+
+```diff
+  const deployer = new CloudflareDeployer({
+-   projectName: 'my-worker',
++   name: 'my-worker',
+-   d1Databases: [
++   d1_databases: [
+      {
+        binding: 'DB',
+        database_name: 'my-db',
+        database_id: 'xxx',
+      },
+    ],
+-   kvNamespaces: [
++   kv_namespaces: [
+      {
+        binding: 'KV',
+        id: 'yyy',
+      },
+    ],
+  });
+```
+
+The `workerNamespace` field has been removed as it is no longer used.
+
+For all available configuration options, see the [Wrangler configuration documentation](https://developers.cloudflare.com/workers/wrangler/configuration/).

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

@@ -158,38 +158,3 @@ To migrate, update any code that references tools by their configuration keys to
 - mastra.getTool('searchTool');
 + mastra.getTool(weatherSearchTool.id);
 ```
-
-## Removed
-
-### `memory` property from Mastra class
-
-The `memory` property has been removed from the Mastra class. Memory is now configured at the Agent level rather than globally.
-
-To migrate, move memory configuration from the Mastra constructor to individual Agent constructors.
-
-```diff
-- const mastra = new Mastra({
--   memory: new Memory({
--     storage: libsqlStore,
--     vector: libsqlVector,
--     embedder: fastembed,
--   }),
-- });
-- 
-- const agent = new Agent({
--   name: 'my-agent',
-- });
-
-+ const mastra = new Mastra({
-+   // memory removed from here
-+ });
-+ 
-+ const agent = new Agent({
-+   name: 'my-agent',
-+   memory: new Memory({
-+     storage: libsqlStore,
-+     vector: libsqlVector,
-+     embedder: fastembed,
-+   }),
-+ });
-```

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

@@ -97,6 +97,35 @@ To migrate, if you were relying on the previous defaults, explicitly set these v
   });
 ```
 
+### `memory.readOnly` moved to `memory.options.readOnly`
+
+The `readOnly` property has been moved from the top-level of the memory option to inside `options`. This change aligns `readOnly` with other memory configuration options like `lastMessages` and `semanticRecall`.
+
+To migrate, move `readOnly` from the top level to inside `options`.
+
+```diff
+  agent.stream('Hello', {
+    memory: {
+      thread: threadId,
+      resource: resourceId,
+-     readOnly: true,
++     options: {
++       readOnly: true,
++     },
+    },
+  });
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod@beta v1/memory-readonly-to-options .
+```
+
+:::
+
 ### `Memory.query()` renamed to `Memory.recall()`
 
 The `Memory.query()` method has been renamed to `Memory.recall()`. The new method returns a simpler format with just `{ messages: MastraDBMessage[] }` instead of multiple format variations. This change better describes the action of retrieving messages from memory and simplifies the API.
@@ -252,18 +281,26 @@ To migrate, use `MastraDBMessage` for storage or AI SDK v5 message formats direc
 
 The `processors` config option in the Memory constructor has been deprecated and now throws an error. Processors should be configured at the Agent level instead. This change provides clearer configuration boundaries and better encapsulation.
 
-To migrate, move processor configuration from Memory to Agent.
+To migrate, move processor configuration from Memory to Agent using `inputProcessors` and/or `outputProcessors`.
 
 ```diff
++ import { TokenLimiter } from '@mastra/core/processors';
++
   const memory = new Memory({
     storage,
     vector,
     embedder,
 -   processors: [/* ... */],
   });
-  
+
   const agent = new Agent({
     memory,
-+   processors: [/* ... */],
++   inputProcessors: [
++     new TokenLimiter({ limit: 4000 }), // Limits historical messages to fit context window
++   ],
   });
 ```
+
+Additionally, the `@mastra/memory/processors` import path has been removed. Import processors from `@mastra/core/processors` instead. See the [processors migration guide](/guides/v1/migrations/upgrade-to-v1/processors#memory-processor-exports-moved-to-core) for details.
+
+For more information on using processors with agents, see the [Processors docs](/docs/v1/agents/processors). For a complete example with memory, see the [TokenLimiter reference](/reference/v1/processors/token-limiter-processor#extended-usage-example).

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

@@ -5,6 +5,12 @@ description: "Overview of breaking changes when upgrading to Mastra v1."
 
 # Upgrade to Mastra v1
 
+:::info[First update to latest 0.x version]
+Before upgrading to v1, make sure you've updated to the latest 0.x version of Mastra. Follow the [upgrade to latest 0.x guide](https://mastra.ai/guides/migrations/upgrade-to-latest-0x) first, then return here to complete the v1 migration.
+:::
+
+Mastra v1 is coming in January 2026. We recommend starting any new projects with the beta, or upgrading your existing project today to get ahead.
+
 This guide provides a comprehensive overview of breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.
 
 :::tip[Need help?]
@@ -15,12 +21,12 @@ Need help with the migration? Join our [Discord community](https://discord.gg/BT
 
 ### 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.
+Use your package manager to update your project's versions. Be sure to update **all** Mastra packages at the same time to ensure compatibility (all `@mastra/*` packages and `mastra`).
 
 Here's how you update the most commonly used packages:
 
 ```shell
-npm install @mastra/core@beta mastra@beta @mastra/loggers@beta @mastra/memory@beta
+npm install @mastra/core@beta @mastra/loggers@beta @mastra/memory@beta mastra@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.
@@ -43,6 +49,12 @@ npx @mastra/codemod@beta v1
 
 :::
 
+:::note[Database Migration Required]
+
+If you're using PostgreSQL or LibSQL storage, you'll need to run a database migration. See the [Storage migration guide](/guides/v1/migrations/upgrade-to-v1/storage#database-migration) for details.
+
+:::
+
 ## Breaking Changes by Area
 
 - **[Mastra Class](/guides/v1/migrations/upgrade-to-v1/mastra)** - Import restructuring and property access changes.
@@ -52,10 +64,12 @@ npx @mastra/codemod@beta v1
 - **[Memory](/guides/v1/migrations/upgrade-to-v1/memory)** - Configuration now requires explicit parameters and defaults changed.
 - **[Storage](/guides/v1/migrations/upgrade-to-v1/storage)** - Pagination standardized and methods renamed to list pattern.
 - **[Vectors](/guides/v1/migrations/upgrade-to-v1/vectors)** - Vector store methods renamed to list pattern.
+- **[RAG](/guides/v1/migrations/upgrade-to-v1/rag)** - Parameter naming updated for clarity.
 - **[MCP](/guides/v1/migrations/upgrade-to-v1/mcp)** - Tool context reorganized and deprecated client classes removed.
 - **[Tracing](/guides/v1/migrations/upgrade-to-v1/tracing)** - OTEL telemetry replaced with dedicated observability package and exporters.
 - **[Evals & Scorers](/guides/v1/migrations/upgrade-to-v1/evals)** - Scorers API consolidated with new naming conventions.
 - **[CLI](/guides/v1/migrations/upgrade-to-v1/cli)** - Commands and flags removed for simpler interface.
+- **[Deployment](/guides/v1/migrations/upgrade-to-v1/deployment)** - CloudflareDeployer configuration updated to use standard wrangler.json property names.
 - **[Client SDKs](/guides/v1/migrations/upgrade-to-v1/client)** - Types and utilities renamed for consistency.
 - **[Voice Packages](/guides/v1/migrations/upgrade-to-v1/voice)** - Packages renamed from speech to voice.
 
@@ -96,6 +110,7 @@ npx @mastra/codemod@beta v1
 
 ### Low Impact Changes
 
+- Rename `keepSeparator` to `separatorPosition` in chunk options - [RAG](/guides/v1/migrations/upgrade-to-v1/rag)
 - Rename `createRunAsync` to `createRun` - [Workflows](/guides/v1/migrations/upgrade-to-v1/workflows)
 - Update voice package names from `@mastra/speech-*` to `@mastra/voice-*` - [Voice Packages](/guides/v1/migrations/upgrade-to-v1/voice)
 - Update scorer methods: `runExperiment` → `runEvals`, `getScorerByName` → `getScorerById` - [Evals & Scorers](/guides/v1/migrations/upgrade-to-v1/evals)

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

@@ -60,3 +60,14 @@ If you have used `InputProcessor`, replace it with `Processor` which implements
 - import { InputProcessor, ModerationProcessor } from '@mastra/core/agent/input-processors/processors';
 + import { Processor, ModerationProcessor } from '@mastra/core/processors';
 ```
+
+### Memory processor exports moved to core
+
+The `@mastra/memory/processors` export has been removed. All processors are now exported from `@mastra/core/processors`. This change consolidates all processor exports in a single location.
+
+To migrate, update your import paths from `@mastra/memory/processors` to `@mastra/core/processors`.
+
+```diff
+- import { TokenLimiter, ToolCallFilter } from '@mastra/memory/processors';
++ import { TokenLimiter, ToolCallFilter } from '@mastra/core/processors';
+```

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

@@ -0,0 +1,47 @@
+---
+title: "RAG | v1 Migration Guide"
+description: "Migrate RAG-related breaking changes when upgrading to v1."
+---
+
+# RAG
+
+The RAG package has renamed chunking parameters and narrowed their types.
+
+## Changed
+
+### `keepSeparator` to `separatorPosition`
+
+The `keepSeparator` parameter has been renamed to `separatorPosition` with a simplified type. The old parameter had a confusing `boolean | 'start' | 'end'` type where `true` was secretly an alias for `'start'`. The new parameter uses explicit `'start' | 'end'` values, and omitting the parameter discards the separator.
+
+To migrate, replace `keepSeparator` with `separatorPosition` using the mapping below:
+
+| Old value | New value |
+|-----------|-----------|
+| `keepSeparator: true` | `separatorPosition: 'start'` |
+| `keepSeparator: 'start'` | `separatorPosition: 'start'` |
+| `keepSeparator: 'end'` | `separatorPosition: 'end'` |
+| `keepSeparator: false` | Remove the parameter |
+| Parameter omitted | No change needed |
+
+```diff
+  await doc.chunk({
+    strategy: 'character',
+    separator: '.',
+-   keepSeparator: true,
++   separatorPosition: 'start',
+  });
+
+  await doc.chunk({
+    strategy: 'character',
+    separator: '.',
+-   keepSeparator: 'end',
++   separatorPosition: 'end',
+  });
+
+  await doc.chunk({
+    strategy: 'character',
+    separator: '.',
+-   keepSeparator: false,
++   // Parameter removed - separator is discarded by default
+  });
+```