@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

package/.docs/organized/code-examples/agent-v6.md

@@ -0,0 +1,151 @@
+### package.json
+```json
+{
+  "name": "examples-agent",
+  "dependencies": {
+    "zod": "^3",
+    "typescript": "^5.8.3",
+    "@ai-sdk/openai": "3.0.0-beta.96",
+    "@ai-sdk/provider": "3.0.0-beta.26",
+    "ai": "^6.0.0-beta.149",
+    "@mastra/client-js": "beta",
+    "@mastra/core": "beta",
+    "@mastra/evals": "beta",
+    "@mastra/libsql": "beta",
+    "@mastra/loggers": "beta",
+    "@mastra/mcp": "beta",
+    "@mastra/memory": "beta",
+    "@mastra/observability": "beta",
+    "@mastra/voice-openai": "beta"
+  },
+  "devDependencies": {
+    "mastra": "beta",
+    "msw": "^2.12.2"
+  }
+}
+```
+
+### js-client-structured-output-example.ts
+```typescript
+import z from 'zod';
+import { MastraClient } from '@mastra/client-js';
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+});
+
+const agent = client.getAgent('weather-agent');
+
+const result = await agent.generate('weather in new york', {
+  structuredOutput: {
+    schema: z.object({
+      weather: z.string(),
+      temperature: z.number(),
+      humidity: z.number(),
+    }),
+  },
+});
+
+console.log(result.object);
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { Memory } from '@mastra/memory';
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+import { weatherInfo } from '../tools';
+
+const memory = new Memory();
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent v6',
+  instructions: `Your goal is to provide weather information for cities when requested`,
+  description: `An agent that can help you get weather information for a given city`,
+  model: openai('gpt-4o-mini'),
+  tools: { weatherInfo },
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { PinoLogger } from '@mastra/loggers';
+import { LibSQLStore } from '@mastra/libsql';
+import { Observability } from '@mastra/observability';
+
+import { weatherAgent } from './agents';
+
+const storage = new LibSQLStore({
+  id: 'mastra-storage',
+  url: 'file:./mastra.db',
+});
+
+export const mastra = new Mastra({
+  storage,
+  agents: {
+    weatherAgent,
+  },
+  bundler: {
+    sourcemap: true,
+  },
+  server: {
+    build: {
+      swaggerUI: true,
+    },
+  },
+  logger: new PinoLogger({ name: 'Chef', level: 'debug' }),
+  observability: new Observability({
+    default: { enabled: true },
+  }),
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export const weatherInfo = createTool({
+  id: 'weather-info',
+  description: 'Fetches the current weather information for a given city',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return {
+      city,
+      weather: 'sunny',
+      temperature_celsius: 19,
+      temperature_fahrenheit: 66,
+      humidity: 50,
+      wind: '10 mph',
+    };
+  },
+});
+
+```
+
+### structured-output-example.ts
+```typescript
+import z from 'zod';
+import { weatherAgent } from './mastra/agents';
+
+const result = await weatherAgent.generate('weather in new york', {
+  structuredOutput: {
+    schema: z.object({
+      weather: z.string(),
+      temperature: z.number(),
+      humidity: z.number(),
+    }),
+  },
+});
+
+console.log(result.object);
+
+```

package/.docs/organized/code-examples/ai-elements.md

@@ -21,7 +21,7 @@
     "embla-carousel-react": "^8.6.0",
     "lucide-react": "^0.544.0",
     "nanoid": "^5.1.6",
-    "next": "15.5.7",
+    "next": "15.5.9",
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "react-syntax-highlighter": "^15.6.6",

package/.docs/organized/code-examples/quick-start.md

@@ -75,14 +75,10 @@ export const catOne = new Agent({
 import { Mastra } from '@mastra/core/mastra';
 import { PinoLogger } from '@mastra/loggers';
 import { catOne } from './agents/agent';
-import { logCatWorkflow as legacy_catWorkflow } from './legacy-workflows';
 import { logCatWorkflow } from './workflows';
 
 export const mastra = new Mastra({
   agents: { catOne },
-  legacy_workflows: {
-    legacy_catWorkflow,
-  },
   workflows: {
     logCatWorkflow,
   },

package/.docs/organized/code-examples/stock-price-tool.md

@@ -70,7 +70,26 @@ import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
 
 export const getStockPrice = async (symbol: string) => {
-  const data = await fetch(`https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`).then(r => r.json());
+  const response = await fetch(`https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`);
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Failed to fetch stock price for ${symbol}: ${response.status} ${errorText}`);
+  }
+
+  let data;
+  try {
+    data = await response.json();
+  } catch (error) {
+    throw new Error(
+      `Failed to parse JSON response for ${symbol}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (!data.prices || !data.prices['4. close']) {
+    throw new Error(`Invalid response format for symbol ${symbol}: ${JSON.stringify(data)}`);
+  }
+
   return data.prices['4. close'];
 };
 
@@ -80,7 +99,7 @@ export const stockPrices = createTool({
     symbol: z.string(),
   }),
   description: `Fetches the last day's closing stock price for a given symbol`,
-  execute: async input => {
+  execute: async (inputData, context) => {
     console.log('Using tool to fetch stock price for', inputData.symbol);
     return {
       symbol: inputData.symbol,

package/.docs/raw/agents/adding-voice.mdx

@@ -168,7 +168,7 @@ The following files are created:
 - **hybrid-question.mp3** – Hybrid agent's spoken question.
 - **unified-response.mp3** – Unified agent's spoken response.
 
-```typescript title="src/test-voice-agents.ts" showLineNumbers copy
+```typescript title="src/test-voice-agents.ts"
 import "dotenv/config";
 
 import path from "path";
@@ -232,7 +232,6 @@ export const unifiedVoiceAgent = new Agent({
 });
 
 export const mastra = new Mastra({
-  // ...
   agents: { hybridVoiceAgent, unifiedVoiceAgent },
 });
 
@@ -297,7 +296,7 @@ export const agent = new Agent({
   id: "aisdk-voice-agent",
   name: "AI SDK Voice Agent",
   instructions: `You are a helpful assistant with voice capabilities.`,
-  model: openai("gpt-5.1"),
+  model: "openai/gpt-5.1",
 
   // Pass AI SDK models directly to CompositeVoice
   voice: new CompositeVoice({

package/.docs/raw/agents/agent-approval.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Agent Approval | Agents"
-description: Learn how to require approvals and suspend tool execution while keeping humans in control of agent workflows.
+description: Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
 ---
 
 # Agent Approval
@@ -20,7 +20,6 @@ import { Mastra } from "@mastra/core/mastra";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
-  // ...
   storage: new LibSQLStore({
     id: "mastra-storage",
     url: ":memory:"
@@ -33,7 +32,7 @@ export const mastra = new Mastra({
 
 When calling an agent using `.stream()` set `requireToolApproval` to `true` which will prevent the agent from calling any of the tools defined in its configuration.
 
-```typescript showLineNumbers
+```typescript
 const stream = await agent.stream("What's the weather in London?", {
   requireToolApproval: true
 });
@@ -43,7 +42,7 @@ const stream = await agent.stream("What's the weather in London?", {
 
 To approve a tool call, access `approveToolCall` from the `agent`, passing in the `runId` of the stream. This will let the agent know its now OK to call its tools.
 
-```typescript showLineNumbers
+```typescript
 const handleApproval = async () => {
   const approvedStream = await agent.approveToolCall({ runId: stream.runId });
 
@@ -58,7 +57,7 @@ const handleApproval = async () => {
 
 To decline a tool call, access the `declineToolCall` from the `agent`. You will see the streamed response from the agent, but it won't call its tools.
 
-```typescript showLineNumbers
+```typescript
 const handleDecline = async () => {
   const declinedStream = await agent.declineToolCall({ runId: stream.runId });
 
@@ -180,10 +179,144 @@ const handleResume = async () => {
 
 ```
 
+## Automatic tool resumption
+
+When using tools that call `suspend()`, you can enable automatic resumption so the agent resumes suspended tools based on the user's next message. This creates a conversational flow where users provide the required information naturally, without your application needing to call `resumeStream()` explicitly.
+
+### Enabling auto-resume
+
+Set `autoResumeSuspendedTools` to `true` in the agent's default options or when calling `stream()`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+// Option 1: In agent configuration
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o-mini",
+  tools: { weatherTool },
+  memory: new Memory(),
+  defaultOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+// Option 2: Per-request
+const stream = await agent.stream("What's the weather?", {
+  autoResumeSuspendedTools: true,
+});
+```
+
+### How it works
+
+When `autoResumeSuspendedTools` is enabled:
+
+1. A tool suspends execution by calling `suspend()` with a payload (e.g., requesting more information)
+2. The suspension is persisted to memory along with the conversation
+3. When the user sends their next message on the same thread, the agent:
+   - Detects the suspended tool from message history
+   - Extracts `resumeData` from the user's message based on the tool's `resumeSchema`
+   - Automatically resumes the tool with the extracted data
+
+### Example
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "weather-info",
+  description: "Fetches weather information for a city",
+  suspendSchema: z.object({
+    message: z.string(),
+  }),
+  resumeSchema: z.object({
+    city: z.string(),
+  }),
+  execute: async (_inputData, context) => {
+    // Check if this is a resume with data
+    if (!context?.agent?.resumeData) {
+      // First call - suspend and ask for the city
+      return context?.agent?.suspend({
+        message: "What city do you want to know the weather for?",
+      });
+    }
+
+    // Resume call - city was extracted from user's message
+    const { city } = context.agent.resumeData;
+    const response = await fetch(`https://wttr.in/${city}?format=3`);
+    const weather = await response.text();
+
+    return { city, weather };
+  },
+});
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o-mini",
+  tools: { weatherTool },
+  memory: new Memory(),
+  defaultOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+const stream = await agent.stream("What's the weather like?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-suspended") {
+    console.log(chunk.payload.suspendPayload);
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.stream("San Francisco");
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+**Conversation flow:**
+
+```
+User: "What's the weather like?"
+Agent: "What city do you want to know the weather for?"
+
+User: "San Francisco"
+Agent: "The weather in San Francisco is: San Francisco: ☀️ +72°F"
+```
+
+The second message automatically resumes the suspended tool - the agent extracts `{ city: "San Francisco" }` from the user's message and passes it as `resumeData`.
+
+### Requirements
+
+For automatic tool resumption to work:
+
+- **Memory configured**: The agent needs memory to track suspended tools across messages
+- **Same thread**: The follow-up message must use the same memory thread and resource identifiers
+- **`resumeSchema` defined**: The tool must define a `resumeSchema` so the agent knows what data structure to extract from the user's message
+
+### Manual vs automatic resumption
+
+| Approach | Use case |
+|----------|----------|
+| Manual (`resumeStream()`) | Programmatic control, webhooks, button clicks, external triggers |
+| Automatic (`autoResumeSuspendedTools`) | Conversational flows where users provide resume data in natural language |
+
+Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
+
 ## Related
 
 - [Using Tools](./using-tools)
 - [Agent Overview](./overview)
 - [Tools Overview](../mcp/overview)
 - [Agent Memory](./agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/agents/agent-memory.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Agent Memory | Agents"
-description: Learn how to add memory to agents to store conversation history and maintain context across interactions.
+description: Learn how to add memory to agents to store message history and maintain context across interactions.
 ---
 
 import Steps from "@site/src/components/Steps";
@@ -8,9 +8,9 @@ import StepItem from "@site/src/components/StepItem";
 
 # Agent memory
 
-Agents use memory to maintain context across interactions. LLMs are stateless and don't retain information between calls, so agents need memory to track conversation history and recall relevant information.
+Agents use memory to maintain context across interactions. LLMs are stateless and don't retain information between calls, so agents need memory to track message history and recall relevant information.
 
-Mastra agents can be configured to store conversation history, with optional [working memory](../memory/working-memory) to maintain recent context or [semantic recall](../memory/semantic-recall) to retrieve past messages based on meaning.
+Mastra agents can be configured to store message history, with optional [working memory](../memory/working-memory) to maintain recent context or [semantic recall](../memory/semantic-recall) to retrieve past messages based on meaning.
 
 ## When to use memory
 
@@ -20,13 +20,13 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 To enable memory in Mastra, install the `@mastra/memory` package along with a storage provider.
 
-```bash npm2yarn copy
+```bash npm2yarn
 npm install @mastra/memory@beta @mastra/libsql@beta
 ```
 
 ## Storage providers
 
-Memory requires a storage provider to persist conversation history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](/docs/v1/server-db/storage) documentation.
+Memory requires a storage provider to persist message history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](/docs/v1/memory/storage) documentation.
 
 ## Configuring memory
 
@@ -35,14 +35,13 @@ Memory requires a storage provider to persist conversation history, including us
 
 Enable memory by creating a `Memory` instance and passing it to the agent’s `memory` option.
 
-```typescript {6-9} title="src/mastra/agents/memory-agent.ts" copy
+```typescript {7-11} title="src/mastra/agents/memory-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 
 export const memoryAgent = new Agent({
   id: 'memory-agent',
   name: 'Memory Agent',
-  // ...
   memory: new Memory({
     options: {
       lastMessages: 20,
@@ -51,9 +50,9 @@ export const memoryAgent = new Agent({
 });
 ```
 
-:::note
+:::info
 
-See the [Memory Class](/reference/v1/memory/memory-class) docs for a full list of configuration options.
+Visit [Memory Class](/reference/v1/memory/memory-class) for a full list of configuration options.
 
 :::
 
@@ -63,12 +62,11 @@ See the [Memory Class](/reference/v1/memory/memory-class) docs for a full list o
 
 Add a storage provider to your main Mastra instance to enable memory across all configured agents.
 
-```typescript {6-8} title="src/mastra/index.ts" copy
+```typescript {5-8} title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
-  // ..
   storage: new LibSQLStore({
     id: 'mastra-storage',
     url: ":memory:",
@@ -76,9 +74,9 @@ export const mastra = new Mastra({
 });
 ```
 
-:::note
+:::info
 
-See the [LibSQL Storage](/reference/v1/storage/libsql) docs for a full list of configuration options.
+Visit [libSQL Storage](/reference/v1/storage/libsql) for a full list of configuration options.
 
 :::
 
@@ -87,7 +85,7 @@ See the [LibSQL Storage](/reference/v1/storage/libsql) docs for a full list of c
 
 Alternatively, add storage directly to an agent’s memory to keep data separate or use different providers per agent.
 
-```typescript {7-10} title="src/mastra/agents/memory-agent.ts" copy
+```typescript {9-12} title="src/mastra/agents/memory-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -95,7 +93,6 @@ import { LibSQLStore } from "@mastra/libsql";
 export const memoryAgent = new Agent({
   id: 'memory-agent',
   name: 'Memory Agent',
-  // ...
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'mastra-storage',
@@ -105,16 +102,16 @@ export const memoryAgent = new Agent({
 });
 ```
 
-## Conversation history
+## Message history
 
-Include a `memory` object with both `resource` and `thread` to track conversation history during agent calls.
+Include a `memory` object with both `resource` and `thread` to track message history during agent calls.
 
 - `resource`: A stable identifier for the user or entity.
 - `thread`: An ID that isolates a specific conversation or session.
 
 These fields tell the agent where to store and retrieve context, enabling persistent, thread-aware memory across a conversation.
 
-```typescript {5-6}
+```typescript {4-7}
 const response = await memoryAgent.generate(
   "Remember my favorite color is blue.",
   {
@@ -128,7 +125,7 @@ const response = await memoryAgent.generate(
 
 To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original conversation.
 
-```typescript {3-4}
+```typescript {2-5}
 const response = await memoryAgent.generate("What's my favorite color?", {
   memory: {
     resource: "user-123",
@@ -141,25 +138,20 @@ To learn more about memory see the [Memory](../memory/overview) documentation.
 
 ## Using `RequestContext`
 
-Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
+Use [RequestContext](/docs/v1/server/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
 
-```typescript title="src/mastra/agents/memory-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/memory-agent.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
 
-const premiumMemory = new Memory({
-  // ...
-});
+const premiumMemory = new Memory();
 
-const standardMemory = new Memory({
-  // ...
-});
+const standardMemory = new Memory();
 
 export const memoryAgent = new Agent({
   id: 'memory-agent',
   name: 'Memory Agent',
-  // ...
   memory: ({ requestContext }) => {
     const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
@@ -168,9 +160,9 @@ export const memoryAgent = new Agent({
 });
 ```
 
-:::note
+:::info
 
-See [Request Context](/docs/v1/server-db/request-context) docs for more information.
+Visit [Request Context](/docs/v1/server/request-context) for more information.
 
 :::
 
@@ -178,5 +170,5 @@ See [Request Context](/docs/v1/server-db/request-context) docs for more informat
 
 - [Working Memory](../memory/working-memory)
 - [Semantic Recall](../memory/semantic-recall)
-- [Threads and Resources](../memory/threads-and-resources)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Storage](../memory/storage)
+- [Request Context](/docs/v1/server/request-context)