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

package/.docs/raw/reference/ai-sdk/network-route.mdx

@@ -0,0 +1,99 @@
+---
+title: "Reference: networkRoute() | AI SDK"
+description: API reference for networkRoute(), a function to create network route handlers for streaming network execution in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# networkRoute()
+
+Creates a network route handler for streaming network execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent network, and streams the response back to the client in AI SDK-compatible format. Agent networks allow a routing agent to delegate tasks to other agents. You have to use it inside a [custom API route](/docs/v1/server-db/custom-api-routes).
+
+Use [`handleNetworkStream()`](/reference/v1/ai-sdk/handle-network-stream) if you need a framework-agnostic handler.
+
+## Usage example
+
+This example shows how to set up a network route at the `/network` endpoint that uses an agent with the ID `weatherAgent`.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { networkRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: "/network",
+        agent: "weatherAgent",
+      }),
+    ],
+  },
+});
+```
+
+You can also use dynamic agent routing based on an `agentId`. The URL `/network/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { networkRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: "/network/:agentId",
+      }),
+    ],
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "path",
+      type: "string",
+      description: "The route path (e.g., `/network` or `/network/:agentId`). Include `:agentId` for dynamic agent routing.",
+      isOptional: false,
+      defaultValue: "'/network/:agentId'",
+    },
+    {
+      name: "agent",
+      type: "string",
+      description: "The ID of the routing agent to use for this network route. Required if the path doesn't include `:agentId`.",
+      isOptional: true,
+    },
+    {
+      name: "defaultOptions",
+      type: "AgentExecutionOptions",
+      description: "Default options passed to agent execution. These can include instructions, memory configuration, maxSteps, and other execution settings.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Additional configuration
+
+You can use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the network route, for example to pass additional configuration to the agent:
+
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } = useChat({
+  transport: new DefaultChatTransport({
+    api: "http://localhost:4111/network",
+    prepareSendMessagesRequest({ messages }) {
+      return {
+        body: {
+          messages,
+          // Pass memory config
+          memory: {
+            thread: "user-1",
+            resource: "user-1",
+          },
+        },
+      };
+    },
+  }),
+});
+```

package/.docs/raw/reference/ai-sdk/to-ai-sdk-stream.mdx

@@ -0,0 +1,289 @@
+---
+title: "Reference: toAISdkStream() | AI SDK"
+description: API reference for toAISdkStream(), a function to convert Mastra streams to AI SDK-compatible streams.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# toAISdkStream()
+
+Converts Mastra streams (agent, network, or workflow) to AI SDK-compatible streams. Use this function when you need to manually transform Mastra streams for use with AI SDK's `createUIMessageStream()` and `createUIMessageStreamResponse()`.
+
+This is useful when building custom streaming endpoints outside Mastra's provided route helpers such as [`chatRoute()`](/reference/v1/ai-sdk/chat-route) or [`workflowRoute()`](/reference/v1/ai-sdk/workflow-route).
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript title="app/api/chat/route.ts" copy
+import { mastra } from "../../mastra";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  const stream = await myAgent.stream(messages);
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: "agent" })) {
+        await writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  });
+}
+```
+
+:::tip
+
+Pass `messages` to `originalMessages` in `createUIMessageStream()` to avoid duplicated assistant messages in the UI. See [Troubleshooting: Repeated Assistant Messages](https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages) for details.
+
+:::
+
+## Parameters
+
+The first parameter is the Mastra stream to convert. It can be one of:
+- `MastraModelOutput` - An agent stream from `agent.stream()`
+- `MastraAgentNetworkStream` - A network stream from `agent.network()`
+- `MastraWorkflowStream` or `WorkflowRunOutput` - A workflow stream
+
+The second parameter is an options object:
+
+<PropertiesTable
+  content={[
+    {
+      name: "from",
+      type: "'agent' | 'network' | 'workflow'",
+      description: "The type of Mastra stream being converted.",
+      isOptional: false,
+      defaultValue: "'agent'",
+    },
+    {
+      name: "lastMessageId",
+      type: "string",
+      description: "(Agent only) The ID of the last message in the conversation.",
+      isOptional: true,
+    },
+    {
+      name: "sendStart",
+      type: "boolean",
+      description: "(Agent only) Whether to send start events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendFinish",
+      type: "boolean",
+      description: "(Agent only) Whether to send finish events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendReasoning",
+      type: "boolean",
+      description: "(Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream reasoning content from models that support extended thinking.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "sendSources",
+      type: "boolean",
+      description: "(Agent only) Whether to include source citations in the output.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "includeTextStreamParts",
+      type: "boolean",
+      description: "(Workflow only) Whether to include text stream parts in the output.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "messageMetadata",
+      type: "(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined",
+      description: "(Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.",
+      isOptional: true,
+    },
+    {
+      name: "onError",
+      type: "(error: unknown) => string",
+      description: "(Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Examples
+
+### Converting a workflow stream
+
+```typescript title="app/api/workflow/route.ts" copy {13}
+import { mastra } from "../../mastra";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+
+export async function POST(req: Request) {
+  const { input } = await req.json();
+  const workflow = mastra.getWorkflow("myWorkflow");
+  const run = workflow.createRun();
+  const stream = await run.stream({ inputData: input });
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: "workflow" })) {
+        await writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  });
+}
+```
+
+### Converting a network stream
+
+```typescript title="app/api/network/route.ts" copy {12}
+import { mastra } from "../../mastra";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const routingAgent = mastra.getAgent("routingAgent");
+  const stream = await routingAgent.network(messages);
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: "network" })) {
+        await writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  });
+}
+```
+
+### Converting an agent stream with reasoning enabled
+
+```typescript title="app/api/reasoning/route.ts" copy {8-12,17-20}
+import { mastra } from "../../mastra";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const reasoningAgent = mastra.getAgent("reasoningAgent");
+  const stream = await reasoningAgent.stream(messages, {
+    providerOptions: {
+      openai: { reasoningEffort: "high" },
+    },
+  });
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: "agent",
+        sendReasoning: true,
+      })) {
+        await writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  });
+}
+```
+
+### Using messageMetadata
+
+```typescript title="app/api/chat-with-metadata/route.ts" copy {13-19}
+import { mastra } from "../../mastra";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const myAgent = mastra.getAgent("weatherAgent");
+  const stream = await myAgent.stream(messages);
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: "agent",
+        messageMetadata: ({ part }) => ({
+          timestamp: Date.now(),
+          partType: part.type,
+        }),
+      })) {
+        await writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  });
+}
+```
+
+### Client-side stream transformation
+
+If you're using the Mastra client SDK (`@mastra/client-js`) on the client side and want to convert streams to AI SDK format:
+
+```typescript title="client-stream-to-ai-sdk.ts" copy {14-23,25-35}
+import { MastraClient } from "@mastra/client-js";
+import { createUIMessageStream } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
+import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
+
+const client = new MastraClient({
+  baseUrl: "http://localhost:4111",
+});
+
+const agent = client.getAgent("weatherAgent");
+const response = await agent.stream("What is the weather in Tokyo?");
+
+// Convert the client SDK stream to a ReadableStream<ChunkType>
+const chunkStream = new ReadableStream<ChunkType>({
+  async start(controller) {
+    await response.processDataStream({
+      onChunk: async (chunk) => {
+        controller.enqueue(chunk);
+      },
+    });
+    controller.close();
+  },
+});
+
+// Transform to AI SDK format
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(
+      chunkStream as unknown as MastraModelOutput,
+      { from: "agent" }
+    )) {
+      await writer.write(part);
+    }
+  },
+});
+
+for await (const part of uiMessageStream) {
+  console.log(part);
+}
+```

package/.docs/raw/reference/ai-sdk/with-mastra.mdx

@@ -0,0 +1,119 @@
+---
+title: "Reference: withMastra() | AI SDK"
+description: API reference for withMastra(), a function to use Mastra functionality in AI SDK.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# withMastra()
+
+Wraps an AI SDK model with Mastra processors and/or memory.
+
+## Usage example
+
+```typescript title="src/example.ts" copy
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+import { withMastra } from '@mastra/ai-sdk';
+import type { Processor } from '@mastra/core/processors';
+
+const loggingProcessor: Processor<'logger'> = {
+  id: 'logger',
+  async processInput({ messages }) {
+    console.log('Input:', messages.length, 'messages');
+    return messages;
+  },
+};
+
+const model = withMastra(openai('gpt-4o'), {
+  inputProcessors: [loggingProcessor],
+});
+
+const { text } = await generateText({
+  model,
+  prompt: 'What is 2 + 2?',
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "LanguageModelV2",
+      description: "Any AI SDK language model (e.g., `openai('gpt-4o')`, `anthropic('claude-3-opus')`).",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "WithMastraOptions",
+      description: "Configuration object for processors and memory.",
+      isOptional: true,
+    },
+    {
+      name: "options.inputProcessors",
+      type: "InputProcessor[]",
+      description: "Input processors to run before the LLM call.",
+      isOptional: true,
+    },
+    {
+      name: "options.outputProcessors",
+      type: "OutputProcessor[]",
+      description: "Output processors to run on the LLM response.",
+      isOptional: true,
+    },
+    {
+      name: "options.memory",
+      type: "WithMastraMemoryOptions",
+      description: "Memory configuration - enables automatic message history persistence.",
+      isOptional: true,
+    },
+    {
+      name: "options.memory.storage",
+      type: "MemoryStorage",
+      description: "Storage adapter for message persistence (e.g., LibSQLStore, PostgresStore).",
+      isOptional: false,
+    },
+    {
+      name: "options.memory.threadId",
+      type: "string",
+      description: "Thread ID for conversation persistence.",
+      isOptional: false,
+    },
+    {
+      name: "options.memory.resourceId",
+      type: "string",
+      description: "Resource ID (user/session identifier).",
+      isOptional: true,
+    },
+    {
+      name: "options.memory.lastMessages",
+      type: "number | false",
+      description: "Number of recent messages to retrieve, or false to disable.",
+      isOptional: true,
+    },
+    {
+      name: "options.memory.semanticRecall",
+      type: "WithMastraSemanticRecallOptions",
+      description: "Semantic recall configuration (RAG-based memory retrieval).",
+      isOptional: true,
+    },
+    {
+      name: "options.memory.workingMemory",
+      type: "MemoryConfig['workingMemory']",
+      description: "Working memory configuration (persistent user data).",
+      isOptional: true,
+    },
+    {
+      name: "options.memory.readOnly",
+      type: "boolean",
+      description: "Read-only mode - prevents saving new messages.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+A wrapped model compatible with `generateText`, `streamText`, `generateObject`, and `streamObject`.

package/.docs/raw/reference/ai-sdk/workflow-route.mdx

@@ -0,0 +1,110 @@
+---
+title: "Reference: workflowRoute() | AI SDK"
+description: API reference for workflowRoute(), a function to create workflow route handlers for streaming workflow execution in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# workflowRoute()
+
+Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](/docs/v1/server-db/custom-api-routes).
+
+Use [`handleWorkflowStream()`](/reference/v1/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.
+
+:::tip Agent streaming in workflows
+
+When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
+
+See [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-text-chunks-to-ui) for more details.
+
+:::
+
+## Usage example
+
+This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: "/workflow",
+        workflow: "weatherWorkflow",
+      }),
+    ],
+  },
+});
+```
+
+You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: "/workflow/:workflowId",
+      }),
+    ],
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "path",
+      type: "string",
+      description: "The route path (e.g., `/workflow` or `/workflow/:workflowId`). Include `:workflowId` for dynamic workflow routing.",
+      isOptional: true,
+      defaultValue: "'/api/workflows/:workflowId/stream'",
+    },
+    {
+      name: "workflow",
+      type: "string",
+      description: "Fixed workflow ID when not using dynamic routing.",
+      isOptional: true,
+      defaultValue: "undefined",
+    },
+    {
+      name: "includeTextStreamParts",
+      type: "boolean",
+      description: "Whether to include text stream parts in the output.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+  ]}
+/>
+
+## Additional configuration
+
+You can use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the workflow route, for example to pass additional configuration to the workflow:
+
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } = useChat({
+  transport: new DefaultChatTransport({
+    api: "http://localhost:4111/workflow",
+    prepareSendMessagesRequest({ messages }) {
+      return {
+        body: {
+          inputData: {
+            city: messages[messages.length - 1].parts[0].text,
+          },
+          // Or resumeData for resuming a suspended workflow
+          resumeData: {
+            confirmation: messages[messages.length - 1].parts[0].text
+          }
+        },
+      };
+    },
+  }),
+});
+```

package/.docs/raw/reference/auth/auth0.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraAuthAuth0 Class | Auth | Mastra Docs"
+title: "Reference: MastraAuthAuth0 Class | Auth"
 description: "API reference for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
 ---
 

package/.docs/raw/reference/auth/clerk.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraAuthClerk Class | Auth | Mastra Docs"
+title: "Reference: MastraAuthClerk Class | Auth"
 description: "API reference for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication."
 ---
 

package/.docs/raw/reference/auth/firebase.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraAuthFirebase Class | Auth | Mastra Docs"
+title: "Reference: MastraAuthFirebase Class | Auth"
 description: "API reference for the MastraAuthFirebase class, which authenticates Mastra applications using Firebase Authentication."
 ---
 

package/.docs/raw/reference/auth/jwt.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraJwtAuth Class | Auth | Mastra Docs"
+title: "Reference: MastraJwtAuth Class | Auth"
 description: "API reference for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
 ---
 

package/.docs/raw/reference/auth/supabase.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraAuthSupabase Class | Auth | Mastra Docs"
+title: "Reference: MastraAuthSupabase Class | Auth"
 description: "API reference for the MastraAuthSupabase class, which authenticates Mastra applications using Supabase Auth."
 ---
 

package/.docs/raw/reference/auth/workos.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MastraAuthWorkos Class | Auth | Mastra Docs"
+title: "Reference: MastraAuthWorkos Class | Auth"
 description: "API reference for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication."
 ---
 

package/.docs/raw/reference/cli/create-mastra.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: create-mastra | CLI | Mastra Docs"
+title: "Reference: create-mastra | CLI"
 description: Documentation for the create-mastra command, which creates a new Mastra project with interactive setup options.
 ---