@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/organized/code-examples/memory-with-processors.md

@@ -68,7 +68,7 @@ const agent = new Agent({
   id: 'forgetful-job-interviewer',
   name: 'Forgetful Job Interviewer',
   instructions:
-    "You are a professional job interviewer for a technology company. Conduct insightful interviews by asking relevant questions about skills, experience, and problem-solving abilities. Respond to candidate answers and ask follow-up questions. Keep the interview professional and engaging. Remember details the candidate shares earlier in the conversation. Sometimes you forget things by accident. The system will show you if you forgot. Don't be embarassed, you can admit when you forget something, you'll know when you do because there will be a message wrapped in <forgetten> tags. Don't refer to the user by their name, it comes across as too eager",
+    "You are a professional job interviewer for a technology company. Conduct insightful interviews by asking relevant questions about skills, experience, and problem-solving abilities. Respond to candidate answers and ask follow-up questions. Keep the interview professional and engaging. Remember details the candidate shares earlier in the conversation. Sometimes you forget things by accident. The system will show you if you forgot. Don't be embarrassed, you can admit when you forget something, you'll know when you do because there will be a message wrapped in <forgetten> tags. Don't refer to the user by their name, it comes across as too eager",
   model: openai('gpt-4o'),
   memory: new Memory({
     processors: [

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

@@ -64,7 +64,7 @@ export const catOne = new Agent({
   id: 'cat-one',
   name: 'Cat One',
   instructions:
-    'You are a feline expert with comprehensive knowledge of all cat species, from domestic breeds to wild big cats. As a lifelong cat specialist, you understand their behavior, biology, social structures, and evolutionary history in great depth. If you are asked for a specie name, do not return a paragraph, a succint two or three letter name of the species will suffice.',
+    'You are a feline expert with comprehensive knowledge of all cat species, from domestic breeds to wild big cats. As a lifelong cat specialist, you understand their behavior, biology, social structures, and evolutionary history in great depth. If you are asked for a specie name, do not return a paragraph, a succinct two or three letter name of the species will suffice.',
   model: openai('gpt-4o'),
 });
 

package/.docs/organized/code-examples/server-app-access.md

@@ -0,0 +1,342 @@
+### package.json
+```json
+{
+  "name": "examples-server-app-access",
+  "dependencies": {
+    "@mastra/core": "latest",
+    "@mastra/hono": "latest",
+    "hono": "^4.10.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}
+```
+
+### demo-cli-batch.ts
+```typescript
+/**
+ * Demo: Direct Server App Access
+ *
+ * This demonstrates how to use mastra.getServerApp() to call routes
+ * directly without running an HTTP server.
+ *
+ * Use case: CLI scripts, batch processing, testing, background jobs
+ *
+ * NOTE: The base URL (http://internal) is just a placeholder - Hono's app.fetch()
+ * processes requests in-memory and only uses the path. The hostname is ignored.
+ */
+
+import { MastraServer } from '@mastra/hono';
+import { Hono } from 'hono';
+import type { Hono as HonoType } from 'hono';
+
+import { mastra } from './mastra';
+
+// Base URL is a placeholder - only the path matters for in-memory routing
+const BASE_URL = 'http://internal';
+
+async function main() {
+  // Create and initialize server (no port binding)
+  const app = new Hono();
+  const adapter = new MastraServer({ app: app as any, mastra });
+  await adapter.init();
+
+  // Get the server app - works because MastraServer auto-registers with mastra
+  const serverApp = mastra.getServerApp<HonoType>();
+  if (!serverApp) throw new Error('Server app not initialized');
+
+  // List tools
+  console.log('--- List Tools ---');
+  const toolsResponse = await serverApp.fetch(new Request(`${BASE_URL}/api/tools`));
+  const tools = (await toolsResponse.json()) as Record<string, unknown>;
+  console.log(`Tools: ${Object.keys(tools).join(', ') || '(none registered by key)'}`);
+
+  // Execute a tool
+  console.log('\n--- Execute Tool ---');
+  const calcResponse = await serverApp.fetch(
+    new Request(`${BASE_URL}/api/tools/calculator/execute`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ data: { operation: 'multiply', a: 7, b: 6 } }),
+    }),
+  );
+  console.log(`Result: ${JSON.stringify(await calcResponse.json())}`);
+
+  // List workflows
+  console.log('\n--- List Workflows ---');
+  const workflowsResponse = await serverApp.fetch(new Request(`${BASE_URL}/api/workflows`));
+  const workflows = (await workflowsResponse.json()) as Record<string, unknown>;
+  console.log(`Workflows: ${Object.keys(workflows).join(', ')}`);
+}
+
+main().catch(console.error);
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { calculatorTool, timestampTool } from './tools';
+import { dailyReportWorkflow, paymentProcessorWorkflow, processMessageWorkflow } from './workflows';
+
+/**
+ * Main Mastra instance configured with tools and workflows
+ * for demonstrating server app access patterns.
+ */
+export const mastra = new Mastra({
+  tools: {
+    calculatorTool,
+    timestampTool,
+  },
+  workflows: {
+    processMessageWorkflow,
+    dailyReportWorkflow,
+    paymentProcessorWorkflow,
+  },
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+/**
+ * Calculator tool - performs basic arithmetic operations
+ */
+export const calculatorTool = createTool({
+  id: 'calculator',
+  description: 'Performs basic arithmetic operations',
+  inputSchema: z.object({
+    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+    a: z.number(),
+    b: z.number(),
+  }),
+  execute: async ({ operation, a, b }) => {
+    if (operation === 'divide' && b === 0) {
+      throw new Error('Cannot divide by zero');
+    }
+
+    let result: number;
+    switch (operation) {
+      case 'add':
+        result = a + b;
+        break;
+      case 'subtract':
+        result = a - b;
+        break;
+      case 'multiply':
+        result = a * b;
+        break;
+      case 'divide':
+        result = a / b;
+        break;
+      default:
+        throw new Error(`Unsupported operation: ${operation}`);
+    }
+
+    return { result, operation, operands: { a, b } };
+  },
+});
+
+/**
+ * Timestamp tool - returns current timestamp in various formats
+ */
+export const timestampTool = createTool({
+  id: 'timestamp',
+  description: 'Returns the current timestamp in various formats',
+  inputSchema: z.object({
+    format: z.enum(['iso', 'unix', 'readable']).default('iso'),
+  }),
+  execute: async ({ format }) => {
+    const now = new Date();
+
+    let timestamp: string;
+    switch (format) {
+      case 'unix':
+        timestamp = Math.floor(now.getTime() / 1000).toString();
+        break;
+      case 'readable':
+        timestamp = now.toLocaleString();
+        break;
+      case 'iso':
+      default:
+        timestamp = now.toISOString();
+        break;
+    }
+
+    return { timestamp, format };
+  },
+});
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { createStep, createWorkflow } from '@mastra/core/workflows';
+import { z } from 'zod';
+
+// --- Process Message Workflow ---
+
+const validateStep = createStep({
+  id: 'validate',
+  description: 'Validates the incoming message',
+  inputSchema: z.object({
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  outputSchema: z.object({
+    valid: z.boolean(),
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']),
+  }),
+  execute: async ({ inputData }) => {
+    const valid = inputData.message.length > 0 && inputData.message.length < 1000;
+    return {
+      valid,
+      message: inputData.message,
+      priority: inputData.priority,
+    };
+  },
+});
+
+const processStep = createStep({
+  id: 'process',
+  description: 'Processes the validated message',
+  inputSchema: z.object({
+    valid: z.boolean(),
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']),
+  }),
+  outputSchema: z.object({
+    processed: z.boolean(),
+    result: z.string(),
+    timestamp: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    if (!inputData.valid) {
+      return {
+        processed: false,
+        result: 'Invalid message',
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    const result = `Processed [${inputData.priority}]: ${inputData.message.substring(0, 50)}...`;
+
+    return {
+      processed: true,
+      result,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+
+export const processMessageWorkflow = createWorkflow({
+  id: 'process-message',
+  description: 'Validates and processes a message',
+  inputSchema: z.object({
+    message: z.string(),
+    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  outputSchema: z.object({
+    processed: z.boolean(),
+    result: z.string(),
+    timestamp: z.string(),
+  }),
+})
+  .then(validateStep)
+  .then(processStep)
+  .commit();
+
+// --- Daily Report Workflow ---
+
+const generateReportStep = createStep({
+  id: 'generate-report',
+  description: 'Generates a daily report',
+  inputSchema: z.object({
+    date: z.string(),
+    reportType: z.enum(['summary', 'detailed']).default('summary'),
+  }),
+  outputSchema: z.object({
+    reportId: z.string(),
+    status: z.string(),
+    generatedAt: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const reportId = `RPT-${Date.now()}`;
+
+    return {
+      reportId,
+      status: `Generated ${inputData.reportType} report for ${inputData.date}`,
+      generatedAt: new Date().toISOString(),
+    };
+  },
+});
+
+export const dailyReportWorkflow = createWorkflow({
+  id: 'daily-report',
+  description: 'Generates daily reports',
+  inputSchema: z.object({
+    date: z.string(),
+    reportType: z.enum(['summary', 'detailed']).default('summary'),
+  }),
+  outputSchema: z.object({
+    reportId: z.string(),
+    status: z.string(),
+    generatedAt: z.string(),
+  }),
+})
+  .then(generateReportStep)
+  .commit();
+
+// --- Payment Processor Workflow ---
+
+const processPaymentStep = createStep({
+  id: 'process-payment',
+  description: 'Processes a payment transaction',
+  inputSchema: z.object({
+    amount: z.number(),
+    currency: z.string(),
+    customerId: z.string(),
+  }),
+  outputSchema: z.object({
+    transactionId: z.string(),
+    status: z.string(),
+    processedAt: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const transactionId = `TXN-${Date.now()}`;
+
+    return {
+      transactionId,
+      status: `Processed ${inputData.currency} ${inputData.amount} for customer ${inputData.customerId}`,
+      processedAt: new Date().toISOString(),
+    };
+  },
+});
+
+export const paymentProcessorWorkflow = createWorkflow({
+  id: 'payment-processor',
+  description: 'Processes payment transactions',
+  inputSchema: z.object({
+    amount: z.number(),
+    currency: z.string(),
+    customerId: z.string(),
+  }),
+  outputSchema: z.object({
+    transactionId: z.string(),
+    status: z.string(),
+    processedAt: z.string(),
+  }),
+})
+  .then(processPaymentStep)
+  .commit();
+
+```

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

@@ -15,7 +15,6 @@ import { createReadStream } from "fs";
 import path from "path";
 import { Agent } from "@mastra/core/agent";
 import { OpenAIVoice } from "@mastra/voice-openai";
-import { openai } from "@ai-sdk/openai";
 
 // Initialize the voice provider with default settings
 const voice = new OpenAIVoice();
@@ -25,7 +24,7 @@ export const agent = new Agent({
   id: "voice-agent",
   name: "Voice Agent",
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   voice,
 });
 
@@ -105,7 +104,7 @@ import { search, calculate } from "../tools";
 // Initialize the realtime voice provider
 const voice = new OpenAIRealtimeVoice({
   apiKey: process.env.OPENAI_API_KEY,
-  model: "gpt-4o-mini-realtime",
+  model: "gpt-5.1-realtime",
   speaker: "alloy",
 });
 
@@ -114,7 +113,7 @@ export const agent = new Agent({
   id: "speech-to-speech-agent",
   name: "Speech-to-Speech Agent",
   instructions: `You are a helpful assistant with speech-to-speech capabilities.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   tools: {
     // Tools configured on Agent are passed to voice provider
     search,
@@ -178,7 +177,6 @@ import { Agent } from "@mastra/core/agent";
 import { CompositeVoice } from "@mastra/core/voice";
 import { OpenAIVoice } from "@mastra/voice-openai";
 import { Mastra } from "@mastra/core";
-import { openai } from "@ai-sdk/openai";
 
 // Saves an audio stream to a file in the audio directory, creating the directory if it doesn't exist.
 export const saveAudioToFile = async (
@@ -217,7 +215,7 @@ export const convertToText = async (
 export const hybridVoiceAgent = new Agent({
   id: "hybrid-voice-agent",
   name: "Hybrid Voice Agent",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   instructions: "You can speak and listen using different providers.",
   voice: new CompositeVoice({
     input: new OpenAIVoice(),
@@ -229,7 +227,7 @@ export const unifiedVoiceAgent = new Agent({
   id: "unified-voice-agent",
   name: "Unified Voice Agent",
   instructions: "You are an agent with both STT and TTS capabilities.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   voice: new OpenAIVoice(),
 });
 
@@ -269,13 +267,12 @@ import { Agent } from "@mastra/core/agent";
 import { CompositeVoice } from "@mastra/core/voice";
 import { OpenAIVoice } from "@mastra/voice-openai";
 import { PlayAIVoice } from "@mastra/voice-playai";
-import { openai } from "@ai-sdk/openai";
 
 export const agent = new Agent({
   id: "voice-agent",
   name: "Voice Agent",
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 
   // Create a composite voice using OpenAI for listening and PlayAI for speaking
   voice: new CompositeVoice({
@@ -300,7 +297,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-4o"),
+  model: openai("gpt-5.1"),
 
   // Pass AI SDK models directly to CompositeVoice
   voice: new CompositeVoice({

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

@@ -0,0 +1,189 @@
+---
+title: "Agent Approval | Agents"
+description: Learn how to require approvals and suspend tool execution while keeping humans in control of agent workflows.
+---
+
+# Agent Approval
+
+Agents sometimes require the same [human-in-the-loop](/docs/v1/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or performing running long processes. With agent approval you can suspend a tool call and provide feedback to the user, or approve or decline a tool call based on targeted application conditions.
+
+## Tool call approval
+
+Tool call approval can be enabled at the agent level and apply to every tool the agent uses, or at the tool level providing more granular control over individual tool calls.
+
+### Storage
+
+Agent approval uses a snapshot to capture the state of the request. Ensure you've enabled a storage provider in your main Mastra instance. If storage isn't enabled you'll see an error relating to snapshot not found.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core/mastra";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  // ...
+  storage: new LibSQLStore({
+    id: "mastra-storage",
+    url: ":memory:"
+  })
+});
+```
+
+
+## Agent-level approval
+
+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
+const stream = await agent.stream("What's the weather in London?", {
+  requireToolApproval: true
+});
+```
+
+### Approving tool calls
+
+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
+const handleApproval = async () => {
+  const approvedStream = await agent.approveToolCall({ runId: stream.runId });
+
+  for await (const chunk of approvedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+### Declining tool calls
+
+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
+const handleDecline = async () => {
+  const declinedStream = await agent.declineToolCall({ runId: stream.runId });
+
+  for await (const chunk of declinedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+## Tool-level approval
+
+There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.
+
+### Tool approval using `requireToolApproval`
+
+In this approach, `requireApproval` is configured on the tool definition (shown below) rather than on the agent.
+
+```typescript
+export const testTool = createTool({
+  id: "test-tool",
+  description: "Fetches weather for a location",
+  inputSchema: z.object({
+    location: z.string()
+  }),
+  outputSchema: z.object({
+    weather: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  execute: async ({ location }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const weather = await response.text();
+
+    return { weather };
+  },
+  requireApproval: true
+});
+```
+
+When `requireApproval` is true for a tool, the stream will include chunks of type `tool-call-approval` to indicate that the call is paused. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+
+```typescript
+const stream = await agent.stream("What's the weather in London?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-approval") {
+    console.log("Approval required.");
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.resumeStream({ approved: true }, { runId: stream.runId });
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+
+### Tool approval using `suspend`
+
+With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool implementation calls `suspend` to pause execution and return context or confirmation prompts to the user.
+
+```typescript
+
+export const testToolB = createTool({
+  id: "test-tool-b",
+  description: "Fetches weather for a location",
+  inputSchema: z.object({
+    location: z.string()
+  }),
+  outputSchema: z.object({
+    weather: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string()
+  }),
+  execute: async ({ location }, { agent } = {}) => {
+    const { resumeData: { approved } = {}, suspend } = agent ?? {};
+
+    if (!approved) {
+      return suspend?.({ reason: "Approval required." });
+    }
+
+    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const weather = await response.text();
+
+    return { weather };
+  }
+});
+```
+
+With this approach the stream will include a `tool-call-suspended` chunk, and the `suspendPayload` will contain the `reason` defined by the tool's `suspendSchema`. To continue the call, invoke `resumeStream` with the required `resumeSchema` and the `runId`.
+
+```typescript
+const stream = await agent.stream("What's the weather in London?");
+
+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.resumeStream({ approved: true }, { runId: stream.runId });
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+
+```
+
+## Related
+
+- [Using Tools](./using-tools)
+- [Agent Overview](./overview)
+- [Tools Overview](../mcp/overview)
+- [Agent Memory](./agent-memory)
+- [Request Context](/docs/v1/server-db/request-context)