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

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

@@ -0,0 +1,39 @@
+---
+title: "Voice | v1 Migration Guide"
+description: "Learn how to migrate voice package changes when upgrading to v1."
+---
+
+# Voice Packages
+
+Voice packages have been renamed from speech to voice with updated class names and API methods.
+
+## Changed
+
+### Voice configuration property names
+
+Voice configuration properties have been renamed for consistency. `speakProvider` is now `output`, `listenProvider` is now `input`, and `realtimeProvider` is now `realtime`. This change provides more intuitive property names.
+
+To migrate, update configuration property names when configuring agents with voice capabilities.
+
+```diff
+  const agent = new Agent({
+    voice: {
+-     speakProvider: murfVoice,
+-     listenProvider: deepgramVoice,
+-     realtimeProvider: openaiRealtime,
++     output: murfVoice,
++     input: deepgramVoice,
++     realtime: openaiRealtime,
+    },
+  });
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your code automatically:
+
+```shell
+npx @mastra/codemod v1/voice-property-names .
+```
+
+:::

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

@@ -0,0 +1,178 @@
+---
+title: "Workflows | v1 Migration Guide"
+description: "Learn how to migrate workflow-related changes when upgrading to v1."
+---
+
+# Workflows
+
+Legacy workflow features have been removed.
+
+## Changed
+
+### `getWorkflows` to `listWorkflows`
+
+The `mastra.getWorkflows()` method has been renamed to `mastra.listWorkflows()`. 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.getWorkflows()` with `mastra.listWorkflows()`.
+
+```diff
+- const workflows = mastra.getWorkflows();
++ const workflows = mastra.listWorkflows();
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your imports automatically:
+
+```shell
+npx @mastra/codemod v1/workflows-get-workflows .
+```
+
+:::
+
+### `RuntimeContext` to `RequestContext` in step context
+
+The parameter name `runtimeContext` has been changed to `requestContext` in workflow step execution context. This change aligns with the global rename for clarity.
+
+To migrate, update references from `runtimeContext` to `requestContext` in step execution functions.
+
+```diff
+  createStep({
+-   execute: async ({ runtimeContext } ) => {
+-     const userTier = context.runtimeContext.get('userTier');
++   execute: async ({ requestContext } ) => {
++     const userTier = requestContext.get('userTier');
+      return { result: userTier };
+    },
+  });
+```
+
+:::tip[Codemod]
+
+You can use Mastra's codemod CLI to update your imports automatically:
+
+```shell
+npx @mastra/codemod v1/runtime-context .
+```
+
+:::
+
+### `createRunAsync` to `createRun`
+
+The `createRunAsync()` method has been renamed to `createRun()`. This change simplifies the API by removing the redundant "Async" suffix since all run creation is asynchronous.
+
+To migrate, rename method calls from `createRunAsync` to `createRun`.
+
+```diff
+- await workflow.createRunAsync({ input: { ... } });
++ await workflow.createRun({ input: { ... } });
+```
+
+### `runCount` to `retryCount` (deprecated)
+
+The `runCount` parameter has been deprecated in favor of `retryCount` in workflow step execution. This change provides clearer naming that better describes retry behavior. The old `runCount` still works but shows deprecation warnings.
+
+To migrate, rename `runCount` to `retryCount` in step execution functions.
+
+```diff
+  createStep({
+    execute: async (inputData, context) => {
+-     console.log(`Step run ${context.runCount} times`);
++     console.log(`Step retry count: ${context.retryCount}`);
+    },
+  });
+```
+
+### `getWorkflowRuns` to `listWorkflowRuns`
+
+The `getWorkflowRuns()` method has been renamed to `listWorkflowRuns()`. This change aligns with the convention that `list*` methods return collections.
+
+To migrate, rename method calls from `getWorkflowRuns` to `listWorkflowRuns`.
+
+```diff
+- const runs = await workflow.getWorkflowRuns({ fromDate, toDate });
++ const runs = await workflow.listWorkflowRuns({ fromDate, toDate });
+```
+
+## Removed
+
+### Legacy workflows export
+
+The `./workflows/legacy` export path has been removed from `@mastra/core`. Legacy workflows are no longer supported.
+
+To migrate, use the new workflow API. There is no direct migration path from legacy workflows.
+
+```diff
+- import { LegacyWorkflow } from '@mastra/core/workflows/legacy';
++ // Legacy workflows are no longer supported
++ // Migrate to the new workflow API
+```
+
+### `pipeThrough` and `pipeTo` methods from WorkflowRunOutput
+
+The `pipeThrough()` and `pipeTo()` methods on `WorkflowRunOutput` are deprecated. These methods still work but show console warnings.
+
+To migrate, use the `fullStream` property instead of calling methods directly on the run output.
+
+```diff
+  const run = await workflow.createRun({ input: { ... } });
+- await run.pipeTo(writableStream);
+- const transformed = run.pipeThrough(transformStream);
++ await run.fullStream.pipeTo(writableStream);
++ const transformed = run.fullStream.pipeThrough(transformStream);
+```
+
+### Watch events API
+
+Legacy watch events have been removed and consolidated on the v2 events API. The `watch()` method and related watch endpoints are no longer available.
+
+To migrate, use the workflow events API or streaming instead of watch events.
+
+```diff
+- const workflow = mastraClient.getWorkflow('my-workflow');
+- const run = await workflow.createRun();
+- await run.watch((event) => {
+-   console.log('Step completed:', event);
+- });
+
++ const workflow = mastraClient.getWorkflow('my-workflow');
++ const run = await workflow.createRun();
++ const stream = await run.stream({ inputData: { ... } });
++ for await (const chunk of stream) {
++   console.log('Step completed:', chunk);
++ }
+```
+
+### `waitForEvent` API
+
+The `waitForEvent` API has been removed from workflows. Use the suspend/resume API instead.
+
+To migrate, use suspend/resume API for waiting on workflow execution milestones.
+
+```diff
+- workflow.waitForEvent('step-complete', step1).commit();
++ workflow.then(step1).commit();
++ // Use suspend/resume API instead, in step1 execute function
+createStep({
+- execute: async (inputData, context) => {
+-  // ... execution logic 
+- }
++ execute: async (inputData, context) => {
++   if (!context.resumeData) {
++     return context.suspend({})
++   }
++   //..continue execution logic
++ }
+});
++
++ // after workflow is suspended, you can resume it
++ const result = await run.start({ inputData: { ... } });
++ if (result.status === 'suspended') {
++   const resumedResult = await run.resume({
++     resumeData: {
++       event: 'step-complete',
++     },
++     step: 'step1',
++   });
++ }
+```

package/.docs/raw/guides/migrations/vnext-to-standard-apis.mdx

@@ -0,0 +1,367 @@
+---
+title: "Migration: VNext to Standard APIs | Migration Guide"
+description: "Learn how to migrate from VNext methods to the new standard agent APIs in Mastra."
+---
+
+#  Migrate from VNext to Standard APIs
+
+As of `v0.20.0` for `@mastra/core`, the following changes apply.
+
+## Legacy APIs (AI SDK v4)
+
+The original methods have been renamed and maintain backward compatibility with **AI SDK v4** and `v1` models.
+
+- `.stream()` → `.streamLegacy()`
+- `.generate()` → `.generateLegacy()`
+
+## Standard APIs (AI SDK v5)
+
+These are now the current APIs with full **AI SDK v5** and `v2` model compatibility.
+
+- `.streamVNext()` → `.stream()`
+- `.generateVNext()` → `.generate()`
+
+## Migration paths
+
+If you're already using `.streamVNext()` and `.generateVNext()` use find/replace to change methods to `.stream()` and `.generate()` respectively.
+
+If you're using the old `.stream()` and `.generate()`, decide whether you want to upgrade or not. If you don't, use find/replace to change to `.streamLegacy()` and `.generateLegacy()`.
+
+Choose the migration path that fits your needs:
+
+### Keep using AI SDK v4 models
+
+- Rename all your `.stream()` and `.generate()` calls to `.streamLegacy()` and `.generateLegacy()` respectively.
+
+> No further changes required.
+
+### Keep using AI SDK v5 models
+
+- Rename all your `.streamVNext()` and `.generateVNext()` calls to `.stream()` and `.generate()` respectively.
+
+> No further changes required.
+
+### Upgrade from AI SDK v4 to v5
+
+- Bump all your model provider packages by a major version.
+
+> This will ensure that they are all v5 models now. Follow the guide below to understand the key differences and update your code accordingly.
+
+## Key differences
+
+The updated `.stream()` and `.generate()` methods differ from their legacy counterparts in behavior, compatibility, return types, and available options. This section highlights the most important changes you need to understand when migrating.
+
+### Model version support
+
+**Legacy APIs**
+
+- `.generateLegacy()`
+- `.streamLegacy()`
+
+Only support **AI SDK v4** models (`specificationVersion: 'v1'`)
+
+**Standard APIs**
+
+- `.generate()`
+- `.stream()`
+
+Only support **AI SDK v5** models (`specificationVersion: 'v2'`)
+
+> This is enforced at runtime with clear error messages.
+
+### Return types
+
+**Legacy APIs**
+
+- `.generateLegacy()`
+  Returns: `GenerateTextResult` or `GenerateObjectResult`
+
+- `.streamLegacy()`
+  Returns: `StreamTextResult` or `StreamObjectResult`
+
+See the following API references for more information:
+
+- [Agent.generateLegacy()](/reference/v1/agents/generateLegacy)
+- [Agent.streamLegacy()](/reference/v1/streaming/agents/streamLegacy)
+
+**Standard APIs**
+
+- `.generate()`
+  - `format: 'mastra'` (default): Returns `MastraModelOutput.getFullOutput()`
+  - `format: 'aisdk'`: Returns `AISDKV5OutputStream.getFullOutput()`
+  - Internally calls `.stream()` and awaits `.getFullOutput()`
+
+- `.stream()`
+  - `format: 'mastra'` (default): Returns `MastraModelOutput<OUTPUT>`
+  - `format: 'aisdk'`: Returns `AISDKV5OutputStream<OUTPUT>`
+
+See the following API references for more information:
+
+- [Agent.generate()](/reference/v1/agents/generate)
+- [Agent.stream()](/reference/v1/streaming/agents/stream)
+
+### Format control
+
+**Legacy APIs**
+
+No `format` option: Always return AI SDK v4 types
+
+```typescript showLineNumbers copy
+// Mastra native format (default)
+const result = await agent.stream(messages);
+```
+
+**Standard APIs**
+
+Use `format` option to choose output:
+
+- `'mastra'` (default)
+- `'aisdk'` (AI SDK v5 compatible)
+
+```typescript showLineNumbers copy
+// AI SDK v5 compatibility
+const result = await agent.stream(messages, {
+  format: "aisdk",
+});
+```
+
+### New options in standard APIs
+
+The following options are available in the standard `.stream()` and `generate()`, but **NOT** in their legacy counterparts:
+
+- `format` - Choose between 'mastra' or 'aisdk' output format:
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    format: "aisdk", // or 'mastra' (default)
+  });
+  ```
+
+- `system` - Custom system message (separate from instructions).
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    system: "You are a helpful assistant",
+  });
+  ```
+
+- `structuredOutput` - Enhanced structured output with model override and custom options.
+  - `jsonPromptInjection` - Used to override the default behaviour of passing response_format to the model. This will inject context into the prompt to coerce the model into returning structured outputs.
+  - `model` - If a model is added this will create a sub agent to structure the response from the main agent. The main agent will call tools and return text, and the sub agent will return an object that conforms to your schema provided. This is a replacement for `experimental_output`.
+  - `errorStrategy` - Determines what happens when the output doesn’t match the schema:
+    - 'warn' - log a warning
+    - 'error' - throw an error
+    - 'fallback' - return a fallback value you provide
+
+    ```typescript showLineNumbers copy
+    const result = await agent.generate(messages, {
+      structuredOutput: {
+        schema: z.object({
+          name: z.string(),
+          age: z.number(),
+        }),
+        model: "openai/gpt-4o-mini", // Optional model override for structuring
+        errorStrategy: "fallback",
+        fallbackValue: { name: "unknown", age: 0 },
+        instructions: "Extract user information", // Override default structuring instructions
+      },
+    });
+    ```
+
+- `stopWhen` - Flexible stop conditions (step count, token limit, etc).
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000,
+  });
+  ```
+
+- `providerOptions` - Provider-specific options (e.g., OpenAI-specific settings)
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    providerOptions: {
+      openai: {
+        store: true,
+        metadata: { userId: "123" },
+      },
+    },
+  });
+  ```
+
+- `onChunk` - Callback for each streaming chunk.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    onChunk: (chunk) => {
+      console.log("Received chunk:", chunk);
+    },
+  });
+  ```
+
+- `onError` - Error callback.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    onError: (error) => {
+      console.error("Stream error:", error);
+    },
+  });
+  ```
+
+- `onAbort` - Abort callback.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    onAbort: () => {
+      console.log("Stream aborted");
+    },
+  });
+  ```
+
+- `activeTools` - Specify which tools are active for this execution.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    activeTools: ["search", "calculator"], // Only these tools will be available
+  });
+  ```
+
+- `abortSignal` - AbortSignal for cancellation.
+
+  ```typescript showLineNumbers copy
+  const controller = new AbortController();
+  const result = await agent.stream(messages, {
+    abortSignal: controller.signal,
+  });
+
+  // Later: controller.abort();
+  ```
+
+- `prepareStep` - Callback before each step in multi-step execution.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    prepareStep: ({ step, state }) => {
+      console.log("About to execute step:", step);
+      return {
+        /* modified state */
+      };
+    },
+  });
+  ```
+
+- `requireToolApproval` - Require approval for all tool calls.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    requireToolApproval: true,
+  });
+  ```
+
+### Legacy options that moved
+
+- `temperature` and other `modelSettings`.
+
+  Unified in `modelSettings`
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    modelSettings: {
+      temperature: 0.7,
+      maxTokens: 1000,
+      topP: 0.9,
+    },
+  });
+  ```
+
+- `resourceId` and `threadId`.
+
+  Moved to memory object.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.stream(messages, {
+    memory: {
+      resource: "user-123",
+      thread: "thread-456",
+    },
+  });
+  ```
+
+### Deprecated or removed options
+
+- `experimental_output`
+
+  Use `structuredOutput` instead to allow for tool calls and an object return.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.generate(messages, {
+    structuredOutput: {
+      schema: z.object({
+        summary: z.string(),
+      }),
+      model: "openai/gpt-4o",
+    },
+  });
+  ```
+
+- `output`
+
+  The `output` property is deprecated in favor of `structuredOutput`, to achieve the same results, omit the model and only pass `structuredOutput.schema`, optionally add `jsonPromptInjection: true` if your model does not natively support `response_format`.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.generate(messages, {
+    structuredOutput: {
+      schema: {
+        z.object({
+          name: z.string()
+        })
+      }
+    },
+  });
+  ```
+
+- `memoryOptions`
+
+  Use `memory` instead.
+
+  ```typescript showLineNumbers copy
+  const result = await agent.generate(messages, {
+    memory: {
+      // ...
+    },
+  });
+  ```
+
+### Type changes
+
+**Legacy APIs**
+
+- `CoreMessage[]`
+
+See the following API references for more information:
+
+- [Agent.generateLegacy()](/reference/v1/agents/generateLegacy)
+- [Agent.streamLegacy()](/reference/v1/streaming/agents/streamLegacy)
+
+**Standard APIs**
+
+- `ModelMessage[]`
+
+  `toolChoice` uses the AI SDK v5 `ToolChoice` type.
+
+  ```typescript showLineNumbers copy
+  type ToolChoice<TOOLS extends Record<string, unknown>> =
+    | "auto"
+    | "none"
+    | "required"
+    | {
+        type: "tool";
+        toolName: Extract<keyof TOOLS, string>;
+      };
+  ```
+
+See the following API references for more information:
+
+- [Agent.generate()](/reference/v1/agents/generate)
+- [Agent.stream()](/reference/v1/streaming/agents/stream)

package/.docs/raw/index.mdx

@@ -9,7 +9,7 @@ import YouTube from "@site/src/components/YouTube-player";
 
 # About Mastra
 
-From the team behind Gatsby, Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
+Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
 
 It includes everything you need to go from early prototypes to production-ready applications. Mastra integrates with frontend and backend frameworks like React, Next.js, and Node, or you can deploy it anywhere as a standalone server. It's the easiest way to build, tune, and scale reliable AI products.
 
@@ -21,19 +21,19 @@ Purpose-built for TypeScript and designed around established AI patterns, Mastra
 
 Some highlights include:
 
-- [**Model routing**](/models) - Connect to 40+ providers through one standard interface. Use models from OpenAI, Anthropic, Gemini, and more.
+- [**Model routing**](/models/v1) - Connect to 40+ providers through one standard interface. Use models from OpenAI, Anthropic, Gemini, and more.
 
-- [**Agents**](/docs/agents/overview) - Build autonomous agents that use LLMs and tools to solve open-ended tasks. Agents reason about goals, decide which tools to use, and iterate internally until the model emits a final answer or an optional stopping condition is met.
+- [**Agents**](/docs/v1/agents/overview) - Build autonomous agents that use LLMs and tools to solve open-ended tasks. Agents reason about goals, decide which tools to use, and iterate internally until the model emits a final answer or an optional stopping condition is met.
 
-- [**Workflows**](/docs/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
+- [**Workflows**](/docs/v1/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
 
-- [**Human-in-the-loop**](/docs/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
+- [**Human-in-the-loop**]/docs/v1/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/v1/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
 
-- **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/memory/conversation-history), [retrieve](/docs/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/memory/working-memory) and [semantic](/docs/memory/semantic-recall) memory so your agents behave coherently.
+- **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/v1/memory/conversation-history), [retrieve](/docs/v1/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/v1/memory/working-memory) and [semantic](/docs/v1/memory/semantic-recall) memory so your agents behave coherently.
 
 - **Integrations** - Bundle agents and workflows into existing React, Next.js, or Node.js apps, or ship them as standalone endpoints. When building UIs, integrate with agentic libraries like Vercel's AI SDK UI and CopilotKit to bring your AI assistant to life on the web.
 
-- **Production essentials** - Shipping reliable agents takes ongoing insight, evaluation, and iteration. With built-in [scorers](/docs/scorers/overview) and [observability](/docs/observability/overview), Mastra gives you the tools to observe, measure, and refine continuously.
+- **Production essentials** - Shipping reliable agents takes ongoing insight, evaluation, and iteration. With built-in [scorers](/docs/v1/evals/overview) and [observability](/docs/v1/observability/overview), Mastra gives you the tools to observe, measure, and refine continuously.
 
 ## What can you build?
 
@@ -51,8 +51,8 @@ Explore real-world examples in our [community showcase](/showcase).
 
 ## Get started
 
-Follow the [Installation guide](/docs/getting-started/installation) for step-by-step setup with the CLI or a manual install.
+Follow the [Installation guide](/docs/v1/getting-started/installation) for step-by-step setup with the CLI or a manual install.
 
-If you're new to AI agents, check out our [templates](/docs/getting-started/templates), [course](https://mastra.ai/book), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
+If you're new to AI agents, check out our [templates](/docs/v1/getting-started/templates), [course](https://mastra.ai/book), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
 
 We can't wait to see what you build ✌️

package/.docs/raw/{observability/logging.mdx → logging.mdx}

@@ -7,14 +7,14 @@ description: Learn how to use logging in Mastra to monitor execution, capture ap
 
 Mastra's logging system captures function execution, input data, and output responses in a structured format.
 
-When deploying to Mastra Cloud, logs are shown on the [Logs](../mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are shown on the [Logs]/docs/v1/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## PinoLogger
 
-When [initializing a new Mastra project](../getting-started/installation) using the CLI, `PinoLogger` is included by default.
+When [initializing a new Mastra project]/docs/v1/getting-started/installation) using the CLI, `PinoLogger` is included by default.
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({
@@ -26,7 +26,7 @@ export const mastra = new Mastra({
 });
 ```
 
-> See the [PinoLogger](/reference/observability/logging/pino-logger) API reference for all available configuration options.
+> See the [PinoLogger]/reference/v1/logging/pino-logger) API reference for all available configuration options.
 
 ## Logging from workflows and tools
 

package/.docs/raw/mastra-cloud/dashboard.mdx

@@ -7,7 +7,7 @@ import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
 
 # Navigating the Dashboard
 
-This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Studio](/docs/mastra-cloud/dashboard#studio).
+This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Studio](/docs/v1/mastra-cloud/dashboard#studio).
 
 <MastraCloudCallout />
 
@@ -97,4 +97,4 @@ Each MCP Server includes API endpoints for HTTP and SSE, along with IDE configur
 
 ## Next steps
 
-- [Understanding Tracing and Logs](/docs/mastra-cloud/observability)
+- [Understanding Tracing and Logs](/docs/v1/mastra-cloud/observability)