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

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

@@ -0,0 +1,265 @@
+---
+title: "Agent Class | v1 Migration Guide"
+description: "Learn how to migrate Agent class changes when upgrading to v1."
+---
+
+# Agent Class
+
+The Agent class has been updated with reorganized voice methods, updated property access patterns, and streamlined streaming APIs.
+
+## Changed
+
+### `getAgents` to `listAgents`
+
+The `mastra.getAgents()` method has been renamed to `mastra.listAgents()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
+
+To migrate, replace all calls to `mastra.getAgents()` with `mastra.listAgents()`.
+
+```diff
+- const agents = mastra.getAgents();
++ const agents = mastra.listAgents();
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/agent-get-agents .
+```
+
+:::
+
+### `RuntimeContext` to `RequestContext`
+
+The `RuntimeContext` class has been renamed to `RequestContext` throughout the codebase. This change provides clearer naming that better describes its purpose as request-specific data and aligns with web framework conventions.
+
+To migrate, update all imports and parameter names from `RuntimeContext`/`runtimeContext` to `RequestContext`/`requestContext`.
+
+```diff
+- import { RuntimeContext } from '@mastra/core/runtime-context';
++ import { RequestContext } from '@mastra/core/request-context';
+
+- const runtimeContext = new RuntimeContext();
+- runtimeContext.set('userTier', 'enterprise');
++ const requestContext = new RequestContext();
++ requestContext.set('userTier', 'enterprise');
+
+- await agent.generate(messages, { runtimeContext });
++ await agent.generate(messages, { requestContext });
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/runtime-context .
+```
+
+:::
+
+### Direct property access to getter methods
+
+Direct property access to `agent.llm`, `agent.tools`, and `agent.instructions` is deprecated. This change provides better encapsulation and consistency with the broader API design.
+
+To migrate, replace property access with the corresponding getter methods.
+
+```diff
+- const llm = agent.llm;
+- const tools = agent.tools;
+- const instructions = agent.instructions;
++ const llm = agent.getLLM();
++ const tools = agent.getTools();
++ const instructions = agent.getInstructions();
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/agent-property-access .
+```
+
+:::
+
+### Voice methods moved to `agent.voice` namespace
+
+Voice-related methods have been moved from the Agent class to the `agent.voice` namespace. This change provides better organization and clearer separation of concerns.
+
+To migrate, update voice method calls to use the `agent.voice` namespace.
+
+```diff
+- await agent.speak('Hello');
+- await agent.listen();
+- const speakers = agent.getSpeakers();
++ await agent.voice.speak('Hello');
++ await agent.voice.listen();
++ const speakers = agent.voice.getSpeakers();
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/agent-voice .
+```
+
+:::
+
+### `agent.fetchMemory()` to `(await agent.getMemory()).recall()`
+
+The `fetchMemory()` method has been replaced with a more explicit API. This change provides better clarity about the asynchronous nature of memory access.
+
+To migrate, replace `fetchMemory()` calls with the new API.
+
+```diff
+- const messages = await agent.fetchMemory({ threadId: 'thread-123' });
++ const memory = await agent.getMemory();
++ const result = await memory.recall({ threadId: 'thread-123' });
++ const messages = result.messages;
+```
+
+### Processor method names from `get*` to `list*`
+
+Agent processor methods have been renamed from `get*` to `list*` pattern for consistency with the broader API. This change aligns with the convention that `list*` methods return collections.
+
+To migrate, update processor method names.
+
+```diff
+- const inputProcessors = await agent.getInputProcessors(runtimeContext);
+- const outputProcessors = await agent.getOutputProcessors(runtimeContext);
++ const inputProcessors = await agent.listInputProcessors(requestContext);
++ const outputProcessors = await agent.listOutputProcessors(requestContext);
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod 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.
+
+To migrate, update method names based on which AI SDK version you're using.
+
+```diff
+  // For legacy AI SDK v4
+- const options = await agent.getDefaultGenerateOptions();
+- const streamOptions = await agent.getDefaultStreamOptions();
++ const options = await agent.getDefaultGenerateOptionsLegacy();
++ const streamOptions = await agent.getDefaultStreamOptionsLegacy();
+
+  // For new AI SDK v5 (default)
+  const streamOptions = await agent.getDefaultStreamOptions();
+```
+
+### `modelSettings.abortSignal` to top-level `abortSignal`
+
+The `abortSignal` option has been moved from `modelSettings` to the top level of stream/generate options. This change provides a clearer separation between model-specific settings and execution control.
+
+To migrate, move `abortSignal` from `modelSettings` to the top level.
+
+```diff
+  agent.stream('Hello', {
+-   modelSettings: {
+-     abortSignal: abortController.signal,
+-   },
++   abortSignal: abortController.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.
+
+To migrate, update from `output` or `experimental_output` to `structuredOutput.schema`.
+
+```diff
+  agent.stream('Hello', {
+-   output: z.object({ result: z.string() }),
++   structuredOutput: {
++     schema: z.object({ result: z.string() }),
++   },
+  });
+```
+
+## Removed
+
+### `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.
+
+To migrate, use the standard `generate()` and `stream()` methods.
+
+```diff
+- const result = await agent.generateVNext('Hello');
+- const stream = await agent.streamVNext('Hello');
++ const result = await agent.generate('Hello');
++ const stream = await agent.stream('Hello');
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/agent-generate-stream-v-next .
+```
+
+:::
+
+### `format` parameter from `stream()` and `generate()`
+
+The `format` parameter has been removed from `agent.stream()` and `agent.generate()` methods. AI SDK stream transformations are now handled by the `@mastra/ai-sdk` package. This change improves tree-shaking by moving AI SDK-specific code to a dedicated package.
+
+To migrate, use the `toAISdkStream()` function from `@mastra/ai-sdk` for AI SDK format conversion.
+
+```diff
+- const stream = await agent.stream(messages, {
+-   format: 'aisdk',
+- });
+
++ import { toAISdkStream } from '@mastra/ai-sdk';
++ 
++ const stream = await agent.stream(messages);
++ const aiSdkStream = toAISdkStream(stream, { from: 'agent' });
+```
+
+### `agent.toStep()` method
+
+The `toStep()` method has been removed from the Agent class. Agents can now be added directly to workflow steps without explicit conversion.
+
+To migrate, add agents directly to workflow steps. Workflows handle the transformation automatically.
+
+```diff
+- const step = agent.toStep();
+- const workflow = new Workflow({
+-   steps: [step],
+- });
+
++ const workflow = new Workflow({
++   steps: [agent],
++ });
+```
+
+### `TMetrics` generic parameter from Agent
+
+The `TMetrics` generic parameter has been removed from `AgentConfig` and the `Agent` constructor. Metrics/scorers are now configured using the scorers API instead of being part of the Agent type system.
+
+To migrate, remove the `TMetrics` generic parameter and configure scorers using the new API.
+
+```diff
+- const agent = new Agent<AgentId, Tools, Metrics>({
++ const agent = new Agent<AgentId, Tools>({
+    // ...
+  });
+```

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

@@ -0,0 +1,48 @@
+---
+title: "CLI | v1 Migration Guide"
+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.
+
+## Removed
+
+### `mastra deploy` command
+
+The `mastra deploy` command has been removed from the CLI. This change simplifies the CLI by removing vendor-specific deployment logic.
+
+To migrate, choose one of the [deployment platforms](/docs/v1/deployment/overview) of your choice.
+
+### `--env` flag from `mastra build`
+
+The `--env` flag has been removed from the `mastra build` command. This change simplifies the build command.
+
+To migrate, use `mastra start --env <env>` to start the build output with a custom environment.
+
+```diff
+- mastra build --env production
++ mastra build
++ mastra start --env production
+```
+
+### `--port` flag from `mastra dev`
+
+The `--port` flag has been removed from the `mastra dev` command. Port configuration is now handled through the Mastra instance configuration. This change centralizes port configuration.
+
+To migrate, use `server.port` on the Mastra instance instead of the CLI flag.
+
+```ts
+const mastra = new Mastra({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+### Telemetry options from CLI
+
+The `telemetry` option has been removed from CLI commands including the `--no-telemetry` / `-nt` flag. Telemetry configuration has been removed from the CLI. This change reflects the move of telemetry features to the observability package.
+
+To migrate, remove telemetry flags from CLI commands. Use `@mastra/observability` for tracing features.

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

@@ -0,0 +1,153 @@
+---
+title: "Client SDK | v1 Migration Guide"
+description: "Learn how to migrate client SDK changes when upgrading to v1."
+---
+
+# Client SDK
+
+Client SDK changes align with server-side API updates including renamed utilities, updated pagination, and type naming conventions.
+
+## Changed
+
+### 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.
+
+To migrate, update type imports to use the new naming pattern.
+
+```diff
+- import type {
+-   GetWorkflowRunsParams,
+-   GetWorkflowRunsResponse,
+-   GetMemoryThreadParams,
+- } from '@mastra/client-js';
++ import type {
++   ListWorkflowRunsParams,
++   ListWorkflowRunsResponse,
++   ListMemoryThreadsParams,
++ } from '@mastra/client-js';
+```
+
+### 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.
+
+To migrate, update pagination parameters in all client SDK method calls. Example:
+
+```diff
+  client.memory.listMessages({
+    threadId: 'thread-123',
+-   offset: 0,
+-   limit: 20,
++   page: 0,
++   perPage: 20,
+  });
+```
+
+### `getMemoryThread` parameter structure
+
+The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
+
+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 });
+```
+
+## Removed
+
+### `toAISdkFormat` function
+
+The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. This change provides clearer naming for stream conversion utilities.
+
+To migrate, use `toAISdkStream()` instead.
+
+```diff
+- import { toAISdkFormat } from '@mastra/ai-sdk';
+- const stream = toAISdkFormat(agentStream, { from: 'agent' });
++ import { toAISdkStream } from '@mastra/ai-sdk';
++ const stream = toAISdkStream(agentStream, { from: 'agent' });
+```
+
+### 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.
+
+To migrate, use regular memory APIs instead of network memory.
+
+```diff
+- import { MastraClient } from '@mastra/client-js';
+- 
+- const client = new MastraClient({ baseUrl: '...' });
+- const networkThread = client.networkMemory.getThread('thread-id');
+- const networkThread = client.memory.networkThread('thread-id', 'network-id');
+- await networkThread.get();
+- await networkThread.getMessages();
+
++ // Use regular memory thread APIs instead
++ const client = new MastraClient({ baseUrl: '...' });
++ const thread = client.memory.getThread('thread-id');
++ await thread.get();
++ const messages = await thread.listMessages();
+```
+
+### Watch-related types
+
+Watch-related types have been removed from `@mastra/client-js`. This includes `WorkflowWatchResult`, `WatchEvent`, and related types. This change reflects the removal of the watch API in favor of streaming.
+
+To migrate, use workflow streaming APIs instead of watch.
+
+```diff
+- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
+- 
+- const workflow = client.getWorkflow('my-workflow');
+- const run = await workflow.createRun();
+- await run.watch((event: WatchEvent) => {
+-   console.log('Event:', event);
+- });
+
++ const workflow = client.getWorkflow('my-workflow');
++ const run = await workflow.createRun();
++ const stream = await run.stream({ inputData: { ... } });
++ for await (const chunk of stream) {
++   console.log('Event:', chunk);
++ }
+```
+
+### 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.
+
+To migrate, use the standard stream endpoint or `@mastra/ai-sdk` for UI message transformations.
+
+```diff
+- const response = await fetch('/api/agents/my-agent/stream/vnext', {
+-   method: 'POST',
+-   body: JSON.stringify({ messages: [...] }),
+- });
+
++ const response = await fetch('/api/agents/my-agent/stream', {
++   method: 'POST',
++   body: JSON.stringify({ messages: [...] }),
++ });
++ 
++ // Or use @mastra/ai-sdk for UI message transformations
+```
+
+### Network memory API endpoints
+
+Network memory API endpoints have been removed including `/api/memory/network/*`. This change simplifies the memory API surface.
+
+To migrate, use regular memory API endpoints.
+
+```diff
+- const networkThread = await fetch('/api/memory/network/threads/thread-123');
++ const thread = await fetch('/api/memory/threads/thread-123');
+```
+
+### Eval-related client SDK types
+
+Several eval-related types have been removed from the client SDK including `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, and `GetTelemetryParams`. This change reflects the removal of legacy evals functionality.
+
+To migrate, use the new scorers API instead of legacy evals.

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

@@ -0,0 +1,230 @@
+---
+title: "Evals & Scorers | v1 Migration Guide"
+description: "Learn how to migrate evals and scorers changes when upgrading to v1."
+---
+
+# Evals & Scorers
+
+The evaluation API has been consolidated on the new scorers system with updated naming conventions and configuration requirements.
+
+## Changed
+
+### `getScorers` to `listScorers`
+
+The `getScorers()` method has been renamed to `listScorers()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
+
+To migrate, replace all calls to `getScorers()` with `listScorers()`.
+
+```diff
+- const scorers = mastra.getScorers();
++ const scorers = mastra.listScorers();
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/evals-get-scorers .
+```
+
+:::
+
+### `runExperiment` to `runEvals`
+
+The `runExperiment()` function has been renamed to `runEvals()`. This change provides clearer naming that better describes the evaluation functionality.
+
+To migrate, update function calls from `runExperiment` to `runEvals`.
+
+```diff
+- import { createScorer, runExperiment } from '@mastra/core/evals';
++ import { createScorer, runEvals } from '@mastra/core/evals';
+  import { myAgent } from './agents/my-agent';
+
+  const scorer = createScorer({
+    id: 'helpfulness-scorer',
+    // ...
+  });
+
+- const result = await runExperiment({ target: myAgent, scorers: [scorer], data: inputs });
++ const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });
+```
+
+### `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.
+
+To migrate, update method calls and scorer configuration to use `id` instead of `name`.
+
+```diff
+  const scorer = createScorer({
+-   name: 'helpfulness-scorer',
++   id: 'helpfulness-scorer',
+    // ...
+  });
+  
+- const scorer = mastra.getScorerByName('helpfulness-scorer');
++ const scorer = mastra.getScorerById('helpfulness-scorer');
+```
+
+### 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.
+
+To migrate, update scorer definitions to use `id` as the required field.
+
+```diff
+  const scorer = createScorer({
+-   name: 'helpfulness-scorer',
++   id: 'helpfulness-scorer',
++   name: 'Helpfulness Scorer', // optional
+    // ...
+  });
+```
+
+### Storage score APIs to `listScoresBy*` pattern
+
+Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change aligns with the broader storage API naming conventions.
+
+To migrate, update score query methods to use the new naming pattern.
+
+```diff
+- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
++ const scores = await storage.listScoresByScorerId({
++   scorerId: 'helpfulness-scorer',
++ });
+
+// Also available:
+// - listScoresByRunId
+// - listScoresByEntityId  
+// - listScoresBySpan
+```
+
+### Prebuilt scorer imports to `scorers/prebuilt` path
+
+Prebuilt scorer imports have been consolidated under a single `@mastra/evals/scorers/prebuilt` path instead of separate `scorers/llm` and `scorers/code` paths. This change simplifies imports and provides a clearer organization of prebuilt scorers.
+
+To migrate, update import statements to use the new `scorers/prebuilt` path.
+
+```diff
+  // LLM-based scorers
+- import { createHallucinationScorer } from '@mastra/evals/scorers/llm';
+- import { createFaithfulnessScorer } from '@mastra/evals/scorers/llm';
++ import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt';
++ import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt';
+
+  // Code-based scorers
+- import { createContentSimilarityScorer } from '@mastra/evals/scorers/code';
+- import { createCompletenessScorer } from '@mastra/evals/scorers/code';
++ import { createContentSimilarityScorer } from '@mastra/evals/scorers/prebuilt';
++ import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';
+```
+
+### 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.
+
+To migrate, update scorer implementations to use `MastraDBMessage` types and access message content through the nested `content` structure.
+
+```diff
+  import type {
+    ScorerRunInputForAgent,
+    ScorerRunOutputForAgent
+  } from '@mastra/core/evals';
+
+- // ScorerRunInputForAgent uses UIMessage[]
+- const inputMessages: UIMessage[] = run.input.inputMessages;
++ // ScorerRunInputForAgent now uses MastraDBMessage[]
++ import type { MastraDBMessage } from '@mastra/core/agent';
++ const inputMessages: MastraDBMessage[] = run.input.inputMessages;
+```
+
+### Message content structure to nested format
+
+Tool invocations and text content are now accessed through a nested `content` object structure instead of being flat properties on the message. This change provides better type safety and aligns with the database message format.
+
+To migrate, access tool invocations via `message.content.toolInvocations` and text via `message.content.content` or use the `getTextContentFromMastraDBMessage()` helper.
+
+```diff
++ import { getTextContentFromMastraDBMessage } from '@mastra/evals';
++
+  const run = await scorer.run(testRun);
+
+  // Accessing text content
+- const text = message.content;
++ const text = getTextContentFromMastraDBMessage(message);
++ // or directly: message.content.content
+
+  // Accessing tool invocations
+- const toolCalls = message.toolInvocations;
++ const toolCalls = message.content.toolInvocations;
+```
+
+## Removed
+
+### Legacy evals code
+
+Legacy evals code has been removed from `@mastra/core`. This includes legacy evaluation metrics, scorer/judge modules, and hook-based automatic evaluation code. This change simplifies the codebase by removing outdated evaluation approaches.
+
+To migrate, use the new evals/scorers API in `@mastra/core/evals` or `@mastra/evals`.
+
+```diff
+- // Legacy evals APIs
++ import { createScorer, runEvals } from '@mastra/core/evals';
++ 
++ const scorer = createScorer({
++   id: 'my-scorer',
++   // Use new scorer API
++ });
+```
+
+### Agent `TMetrics` generic parameter
+
+The `TMetrics` generic parameter has been removed from `AgentConfig` and the `Agent` constructor. Metrics/scorers are now configured using the scorers API instead of being part of the Agent type system. This change simplifies the Agent type signature.
+
+To migrate, remove the `TMetrics` generic parameter and configure scorers using the scorers API.
+
+```diff
+- const agent = new Agent<AgentId, Tools, Metrics>({
++ const agent = new Agent<AgentId, Tools>({
+    // ...
+  });
+```
+
+### Evals-related type exports
+
+Several evals-related type exports have been removed including `DeprecatedOutputOptions`, `Metric`, and processor option types. These types are now internal or have been replaced by the new scorers API. This change reduces API surface area.
+
+To migrate, remove references to these removed types and use the new scorers API.
+
+```diff
+- import type {
+-   DeprecatedOutputOptions,
+-   Metric,
+-   LanguageDetectorOptions,
+-   ModerationOptions,
+- } from '@mastra/core';
++ // Use new scorers API types
++ import type { Scorer } from '@mastra/core/evals';
+```
+
+### `createUIMessage` test helper
+
+The `createUIMessage()` test helper has been removed and replaced with `createTestMessage()`. The new helper creates `MastraDBMessage` objects with the nested content structure and supports optional tool invocations. This change aligns test utilities with the new message format.
+
+To migrate, replace `createUIMessage()` calls with `createTestMessage()` and update to use `MastraDBMessage` types.
+
+```diff
+- import { createUIMessage } from '@mastra/evals';
++ import { createTestMessage } from '@mastra/evals';
+
+  // Creating test messages
+- const message = createUIMessage({
+-   id: 'test-1',
++ const message = createTestMessage({
++   id: 'test-1', // optional, defaults to 'test-message'
+    role: 'user',
+    content: 'Hello',
+    toolInvocations: [], // optional
+  });
+```