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

package/.docs/raw/reference/agents/listAgents.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.listAgents() | Agents"
 description: "Documentation for the `Agent.listAgents()` method in Mastra agents, which retrieves the sub-agents that the agent can access."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.listAgents()
@@ -9,7 +11,7 @@ The `.listAgents()` method retrieves the sub-agents configured for an agent, res
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.listAgents();
 ```
 
@@ -42,7 +44,7 @@ await agent.listAgents();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 import { RequestContext } from "@mastra/core/request-context";
 
 await agent.listAgents({

package/.docs/raw/reference/agents/listScorers.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.listScorers() | Agents"
 description: "Documentation for the `Agent.listScorers()` method in Mastra agents, which retrieves the scoring configuration."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.listScorers()
@@ -9,7 +11,7 @@ The `.listScorers()` method retrieves the scoring configuration configured for a
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.listScorers();
 ```
 
@@ -42,7 +44,7 @@ await agent.listScorers();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.listScorers({
   requestContext: new RequestContext(),
 });
@@ -66,4 +68,4 @@ await agent.listScorers({
 ## Related
 
 - [Agents overview](/docs/v1/agents/overview)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/reference/agents/listTools.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.listTools() | Agents"
 description: "Documentation for the `Agent.listTools()` method in Mastra agents, which retrieves the tools that the agent can use."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.listTools()
@@ -9,7 +11,7 @@ The `.listTools()` method retrieves the tools configured for an agent, resolving
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.listTools();
 ```
 
@@ -42,7 +44,7 @@ await agent.listTools();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.listTools({
   requestContext: new RequestContext(),
 });

package/.docs/raw/reference/agents/listWorkflows.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.listWorkflows() | Agents"
 description: "Documentation for the `Agent.listWorkflows()` method in Mastra agents, which retrieves the workflows that the agent can execute."
+packages:
+  - "@mastra/core"
 ---
 
 # Agent.listWorkflows()
@@ -9,7 +11,7 @@ The `.listWorkflows()` method retrieves the workflows configured for an agent, r
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.listWorkflows();
 ```
 
@@ -42,7 +44,7 @@ await agent.listWorkflows();
 
 ## Extended usage example
 
-```typescript copy
+```typescript
 await agent.listWorkflows({
   requestContext: new RequestContext(),
 });

package/.docs/raw/reference/agents/network.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Agent.network() | Agents"
 description: "Documentation for the `Agent.network()` method in Mastra agents, which enables multi-agent collaboration and routing."
+packages:
+  - "@mastra/core"
 ---
 
 import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
@@ -15,7 +17,7 @@ The `.network()` method enables multi-agent collaboration and routing. This meth
 
 ## Usage example
 
-```typescript copy
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { agent1, agent2 } from "./agents";
 import { workflow1 } from "./workflows";
@@ -254,6 +256,48 @@ await agent.network(`
       ],
     },
     MODEL_SETTINGS_OBJECT,
+    {
+      name: "structuredOutput",
+      type: "StructuredOutputOptions",
+      isOptional: true,
+      description:
+        "Configuration for generating a typed structured output from the network result.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "schema",
+              type: "ZodSchema | JSONSchema7",
+              isOptional: false,
+              description:
+                "The schema to validate the output against. Can be a Zod schema or JSON Schema.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "model",
+              type: "MastraModelConfig",
+              isOptional: true,
+              description:
+                "Model to use for generating the structured output. Defaults to the agent's model.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "instructions",
+              type: "string",
+              isOptional: true,
+              description:
+                "Custom instructions for generating the structured output.",
+            },
+          ],
+        },
+      ],
+    },
     {
       name: "runId",
       type: "string",
@@ -303,5 +347,73 @@ await agent.network(`
       type: "Promise<{ promptTokens: number; completionTokens: number; totalTokens: number }>",
       description: "A promise that resolves to token usage statistics",
     },
+    {
+      name: "object",
+      type: "Promise<OUTPUT | undefined>",
+      description:
+        "A promise that resolves to the structured output object. Only available when structuredOutput option is provided. Resolves to undefined if no schema was specified.",
+    },
+    {
+      name: "objectStream",
+      type: "ReadableStream<Partial<OUTPUT>>",
+      description:
+        "A stream of partial objects during structured output generation. Useful for streaming partial results as they're being generated.",
+    },
   ]}
 />
+
+## Structured Output
+
+When you need typed, validated results from your network, use the `structuredOutput` option. The network will generate a response matching your schema after task completion.
+
+```typescript
+import { z } from "zod";
+
+const resultSchema = z.object({
+  summary: z.string().describe("A brief summary of the findings"),
+  recommendations: z.array(z.string()).describe("List of recommendations"),
+  confidence: z.number().min(0).max(1).describe("Confidence score"),
+});
+
+const stream = await agent.network("Research AI trends and summarize", {
+  structuredOutput: {
+    schema: resultSchema,
+  },
+});
+
+// Consume the stream
+for await (const chunk of stream) {
+  // Handle streaming events
+}
+
+// Get the typed result
+const result = await stream.object;
+// result is typed as { summary: string; recommendations: string[]; confidence: number }
+console.log(result?.summary);
+console.log(result?.recommendations);
+```
+
+### Streaming Partial Objects
+
+You can also stream partial objects as they're being generated:
+
+```typescript
+const stream = await agent.network("Analyze data", {
+  structuredOutput: { schema: resultSchema },
+});
+
+// Stream partial objects
+for await (const partial of stream.objectStream) {
+  console.log("Partial result:", partial);
+}
+
+// Get final result
+const final = await stream.object;
+```
+
+### Chunk Types
+
+When using structured output, additional chunk types are emitted:
+
+- `network-object`: Emitted with partial objects during streaming
+- `network-object-result`: Emitted with the final structured object

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

@@ -1,13 +1,16 @@
 ---
 title: "Reference: chatRoute() | AI SDK"
 description: API reference for chatRoute(), a function to create chat route handlers for streaming agent conversations in AI SDK-compatible format.
+packages:
+  - "@mastra/ai-sdk"
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # chatRoute()
 
-Creates a chat route handler for streaming agent conversations using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent, 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).
+Creates a chat route handler for streaming agent conversations using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent, 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/custom-api-routes).
 
 Use [`handleChatStream()`](/reference/v1/ai-sdk/handle-chat-stream) if you need a framework-agnostic handler.
 
@@ -15,7 +18,7 @@ Use [`handleChatStream()`](/reference/v1/ai-sdk/handle-chat-stream) if you need
 
 This example shows how to set up a chat route at the `/chat` endpoint that uses an agent with the ID `weatherAgent`.
 
-```typescript title="src/mastra/index.ts" copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { chatRoute } from "@mastra/ai-sdk";
 
@@ -33,7 +36,7 @@ export const mastra = new Mastra({
 
 You can also use dynamic agent routing based on an `agentId`. The URL `/chat/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
 
-```typescript title="src/mastra/index.ts" copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { chatRoute } from "@mastra/ai-sdk";
 

package/.docs/raw/reference/ai-sdk/handle-chat-stream.mdx

@@ -1,13 +1,15 @@
 ---
 title: "Reference: handleChatStream() | AI SDK"
 description: API reference for handleChatStream(), a framework-agnostic handler for streaming agent chat in AI SDK-compatible format.
+packages:
+  - "@mastra/ai-sdk"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # handleChatStream()
 
-Framework-agnostic handler for streaming agent chat in AI SDK-compatible format. Use this function directly when you need to handle chat streaming outside Hono or Mastra's own [apiRoutes](/docs/v1/server-db/custom-api-routes) feature. 
+Framework-agnostic handler for streaming agent chat in AI SDK-compatible format. Use this function directly when you need to handle chat streaming outside Hono or Mastra's own [apiRoutes](/docs/v1/server/custom-api-routes) feature. 
 
 `handleChatStream()` returns a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
 
@@ -17,7 +19,7 @@ Use [`chatRoute()`](/reference/v1/ai-sdk/chat-route) if you want to create a cha
 
 Next.js App Router example:
 
-```typescript title="app/api/chat/route.ts" copy
+```typescript title="app/api/chat/route.ts"
 import { handleChatStream } from '@mastra/ai-sdk';
 import { createUIMessageStreamResponse } from 'ai';
 import { mastra } from '@/src/mastra';

package/.docs/raw/reference/ai-sdk/handle-network-stream.mdx

@@ -1,13 +1,15 @@
 ---
 title: "Reference: handleNetworkStream() | AI SDK"
 description: API reference for handleNetworkStream(), a framework-agnostic handler for streaming network execution in AI SDK-compatible format.
+packages:
+  - "@mastra/ai-sdk"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # handleNetworkStream()
 
-Framework-agnostic handler for streaming network execution in AI SDK-compatible format. Use this function directly when you need to handle network streaming outside Hono or Mastra's own [apiRoutes](/docs/v1/server-db/custom-api-routes) feature. 
+Framework-agnostic handler for streaming network execution in AI SDK-compatible format. Use this function directly when you need to handle network streaming outside Hono or Mastra's own [apiRoutes](/docs/v1/server/custom-api-routes) feature. 
 
 `handleNetworkStream()` returns a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
 
@@ -16,7 +18,7 @@ Use [`networkRoute()`](/reference/v1/ai-sdk/network-route) if you want to create
 
 Next.js App Router example:
 
-```typescript title="app/api/network/route.ts" copy
+```typescript title="app/api/network/route.ts"
 import { handleNetworkStream } from '@mastra/ai-sdk';
 import { createUIMessageStreamResponse } from 'ai';
 import { mastra } from '@/src/mastra';

package/.docs/raw/reference/ai-sdk/handle-workflow-stream.mdx

@@ -1,13 +1,15 @@
 ---
 title: "Reference: handleWorkflowStream() | AI SDK"
 description: API reference for handleWorkflowStream(), a framework-agnostic handler for streaming workflow execution in AI SDK-compatible format.
+packages:
+  - "@mastra/ai-sdk"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # handleWorkflowStream()
 
-Framework-agnostic handler for streaming workflow execution in AI SDK-compatible format. Use this function directly when you need to handle workflow streaming outside Hono or Mastra's own [apiRoutes](/docs/v1/server-db/custom-api-routes) feature. 
+Framework-agnostic handler for streaming workflow execution in AI SDK-compatible format. Use this function directly when you need to handle workflow streaming outside Hono or Mastra's own [apiRoutes](/docs/v1/server/custom-api-routes) feature. 
 
 `handleWorkflowStream()` returns a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
 
@@ -17,7 +19,7 @@ Use [`workflowRoute()`](/reference/v1/ai-sdk/workflow-route) if you want to crea
 
 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.
+See [Workflow Streaming](/docs/v1/streaming/workflow-streaming) for more details.
 
 :::
 
@@ -25,7 +27,7 @@ See [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-t
 
 Next.js App Router example:
 
-```typescript title="app/api/workflow/route.ts" copy
+```typescript title="app/api/workflow/route.ts"
 import { handleWorkflowStream } from '@mastra/ai-sdk';
 import { createUIMessageStreamResponse } from 'ai';
 import { mastra } from '@/src/mastra';

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

@@ -1,13 +1,16 @@
 ---
 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.
+packages:
+  - "@mastra/ai-sdk"
+  - "@mastra/core"
 ---
 
 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).
+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/custom-api-routes).
 
 Use [`handleNetworkStream()`](/reference/v1/ai-sdk/handle-network-stream) if you need a framework-agnostic handler.
 
@@ -15,7 +18,7 @@ Use [`handleNetworkStream()`](/reference/v1/ai-sdk/handle-network-stream) if you
 
 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
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { networkRoute } from "@mastra/ai-sdk";
 
@@ -33,7 +36,7 @@ export const mastra = new Mastra({
 
 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
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { networkRoute } from "@mastra/ai-sdk";
 

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

@@ -1,6 +1,10 @@
 ---
 title: "Reference: toAISdkStream() | AI SDK"
 description: API reference for toAISdkStream(), a function to convert Mastra streams to AI SDK-compatible streams.
+packages:
+  - "@mastra/ai-sdk"
+  - "@mastra/client-js"
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -15,7 +19,7 @@ This is useful when building custom streaming endpoints outside Mastra's provide
 
 Next.js App Router example:
 
-```typescript title="app/api/chat/route.ts" copy
+```typescript title="app/api/chat/route.ts"
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -124,7 +128,7 @@ The second parameter is an options object:
 
 ### Converting a workflow stream
 
-```typescript title="app/api/workflow/route.ts" copy {13}
+```typescript title="app/api/workflow/route.ts" {13}
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -151,7 +155,7 @@ export async function POST(req: Request) {
 
 ### Converting a network stream
 
-```typescript title="app/api/network/route.ts" copy {12}
+```typescript title="app/api/network/route.ts" {12}
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -177,7 +181,7 @@ export async function POST(req: Request) {
 
 ### Converting an agent stream with reasoning enabled
 
-```typescript title="app/api/reasoning/route.ts" copy {8-12,17-20}
+```typescript title="app/api/reasoning/route.ts" {8-12,17-20}
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -211,7 +215,7 @@ export async function POST(req: Request) {
 
 ### Using messageMetadata
 
-```typescript title="app/api/chat-with-metadata/route.ts" copy {13-19}
+```typescript title="app/api/chat-with-metadata/route.ts" {13-19}
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -246,7 +250,7 @@ export async function POST(req: Request) {
 
 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}
+```typescript title="client-stream-to-ai-sdk.ts" {14-23,25-35}
 import { MastraClient } from "@mastra/client-js";
 import { createUIMessageStream } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";

package/.docs/raw/reference/ai-sdk/to-ai-sdk-v4-messages.mdx

@@ -0,0 +1,130 @@
+---
+title: "Reference: toAISdkV4Messages() | AI SDK"
+description: API reference for toAISdkV4Messages(), a function to convert Mastra messages to AI SDK v4 UI messages.
+packages:
+  - "@mastra/ai-sdk"
+  - "@mastra/client-js"
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# toAISdkV4Messages()
+
+Converts messages from various input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript title="app/chat/page.tsx"
+import { toAISdkV4Messages } from "@mastra/ai-sdk";
+import { useChat } from "ai/react"; // AI SDK V4
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: "1", role: "user", parts: [{ type: "text", text: "Hello" }] },
+  { id: "2", role: "assistant", parts: [{ type: "text", text: "Hi there!" }] }
+];
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV4Messages(storedMessages)
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "MessageListInput",
+      description: "Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+Returns an array of AI SDK V4 `UIMessage` objects with the following structure:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique message identifier.",
+    },
+    {
+      name: "role",
+      type: "'user' | 'assistant' | 'system'",
+      description: "The role of the message sender.",
+    },
+    {
+      name: "content",
+      type: "string",
+      description: "Text content of the message.",
+    },
+    {
+      name: "parts",
+      type: "UIMessagePart[]",
+      description: "Array of UI parts including text, tool-invocation, file, reasoning, source, and step markers.",
+    },
+    {
+      name: "createdAt",
+      type: "Date",
+      description: "Message creation timestamp.",
+    },
+    {
+      name: "toolInvocations",
+      type: "ToolInvocation[]",
+      description: "Array of tool invocations for assistant messages.",
+      isOptional: true,
+    },
+    {
+      name: "experimental_attachments",
+      type: "Attachment[]",
+      description: "File attachments on the message.",
+      isOptional: true,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description: "Custom metadata attached to the message.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV4Messages } from "@mastra/ai-sdk";
+
+const messages = toAISdkV4Messages(["Hello", "How can I help you today?"]);
+// Returns array of UIMessage objects with user role and content string
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from "@mastra/client-js";
+import { toAISdkV4Messages } from "@mastra/ai-sdk";
+
+const client = new MastraClient();
+
+const { messages } = await client.listThreadMessages("thread-id", { agentId: "myAgent" });
+const uiMessages = toAISdkV4Messages(messages);
+```