@mastra/mcp-docs-server 1.0.0-beta.3 → 1.0.0-beta.5

package/.docs/raw/reference/voice/voice.listen.mdx

@@ -7,41 +7,6 @@ description: "Documentation for the listen() method available in all Mastra voic
 
 The `listen()` method is a core function available in all Mastra voice providers that converts speech to text. It takes an audio stream as input and returns the transcribed text.
 
-## Usage Example
-
-```typescript
-import { OpenAIVoice } from "@mastra/voice-openai";
-import { getMicrophoneStream } from "@mastra/node-audio";
-import { createReadStream } from "fs";
-import path from "path";
-
-// Initialize a voice provider
-const voice = new OpenAIVoice({
-  listeningModel: {
-    name: "whisper-1",
-    apiKey: process.env.OPENAI_API_KEY,
-  },
-});
-
-// Basic usage with a file stream
-const audioFilePath = path.join(process.cwd(), "audio.mp3");
-const audioStream = createReadStream(audioFilePath);
-const transcript = await voice.listen(audioStream, {
-  filetype: "mp3",
-});
-console.log("Transcribed text:", transcript);
-
-// Using a microphone stream
-const microphoneStream = getMicrophoneStream(); // Assume this function gets audio input
-const transcription = await voice.listen(microphoneStream);
-
-// With provider-specific options
-const transcriptWithOptions = await voice.listen(audioStream, {
-  language: "en",
-  prompt: "This is a conversation about artificial intelligence.",
-});
-```
-
 ## Parameters
 
 <PropertiesTable
@@ -143,30 +108,42 @@ Each voice provider may support additional options specific to their implementat
   ]}
 />
 
-## Realtime Voice Providers
-
-When using realtime voice providers like `OpenAIRealtimeVoice`, the `listen()` method behaves differently:
-
-- Instead of returning transcribed text, it emits 'writing' events with the transcribed text
-- You need to register an event listener to receive the transcription
+## Usage Example
 
 ```typescript
-import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+import { OpenAIVoice } from "@mastra/voice-openai";
 import { getMicrophoneStream } from "@mastra/node-audio";
+import { createReadStream } from "fs";
+import path from "path";
 
-const voice = new OpenAIRealtimeVoice();
-await voice.connect();
+// Initialize a voice provider
+const voice = new OpenAIVoice({
+  listeningModel: {
+    name: "whisper-1",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+});
 
-// Register event listener for transcription
-voice.on("writing", ({ text, role }) => {
-  console.log(`${role}: ${text}`);
+// Basic usage with a file stream
+const audioFilePath = path.join(process.cwd(), "audio.mp3");
+const audioStream = createReadStream(audioFilePath);
+const transcript = await voice.listen(audioStream, {
+  filetype: "mp3",
 });
+console.log("Transcribed text:", transcript);
 
-// This will emit 'writing' events instead of returning text
-const microphoneStream = getMicrophoneStream();
-await voice.listen(microphoneStream);
+// Using a microphone stream
+const microphoneStream = getMicrophoneStream(); // Assume this function gets audio input
+const transcription = await voice.listen(microphoneStream);
+
+// With provider-specific options
+const transcriptWithOptions = await voice.listen(audioStream, {
+  language: "en",
+  prompt: "This is a conversation about artificial intelligence.",
+});
 ```
 
+
 ## Using with CompositeVoice
 
 When using `CompositeVoice`, the `listen()` method delegates to the configured listening provider:
@@ -177,14 +154,70 @@ import { OpenAIVoice } from "@mastra/voice-openai";
 import { PlayAIVoice } from "@mastra/voice-playai";
 
 const voice = new CompositeVoice({
-  listenProvider: new OpenAIVoice(),
-  speakProvider: new PlayAIVoice(),
+  input: new OpenAIVoice(),
+  output: new PlayAIVoice(),
 });
 
 // This will use the OpenAIVoice provider
 const transcript = await voice.listen(audioStream);
 ```
 
+### Using AI SDK Model Providers
+
+You can also use AI SDK transcription models directly with `CompositeVoice`:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { openai } from "@ai-sdk/openai";
+import { groq } from "@ai-sdk/groq";
+
+// Use AI SDK transcription models
+const voice = new CompositeVoice({
+  input: openai.transcription('whisper-1'),  // AI SDK model
+  output: new PlayAIVoice(),                 // Mastra provider
+});
+
+// Works the same way
+const transcript = await voice.listen(audioStream);
+
+// Provider-specific options can be passed through
+const transcriptWithOptions = await voice.listen(audioStream, {
+  providerOptions: {
+    openai: {
+      language: 'en',
+      prompt: 'This is about AI',
+    }
+  }
+});
+```
+
+See the [CompositeVoice reference](/reference/v1/voice/composite-voice) for more details on AI SDK integration.
+
+
+## Realtime Voice Providers
+
+When using realtime voice providers like `OpenAIRealtimeVoice`, the `listen()` method behaves differently:
+
+- Instead of returning transcribed text, it emits 'writing' events with the transcribed text
+- You need to register an event listener to receive the transcription
+
+```typescript
+import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
+import { getMicrophoneStream } from "@mastra/node-audio";
+
+const voice = new OpenAIRealtimeVoice();
+await voice.connect();
+
+// Register event listener for transcription
+voice.on("writing", ({ text, role }) => {
+  console.log(`${role}: ${text}`);
+});
+
+// This will emit 'writing' events instead of returning text
+const microphoneStream = getMicrophoneStream();
+await voice.listen(microphoneStream);
+```
+
 ## Notes
 
 - Not all voice providers support speech-to-text functionality (e.g., PlayAI, Speechify)
@@ -194,6 +227,7 @@ const transcript = await voice.listen(audioStream);
 - Some providers support streaming transcription, where text is returned as it's transcribed
 - For best performance, consider closing or ending the audio stream when you're done with it
 
+
 ## Related Methods
 
 - [voice.speak()](./voice.speak) - Converts text to speech

package/.docs/raw/reference/voice/voice.off.mdx

@@ -16,7 +16,7 @@ import chalk from "chalk";
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
 });

package/.docs/raw/reference/voice/voice.on.mdx

@@ -17,7 +17,7 @@ import chalk from "chalk";
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
 });

package/.docs/raw/reference/voice/voice.send.mdx

@@ -23,7 +23,7 @@ const speaker = new Speaker({
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
 });

package/.docs/raw/reference/voice/voice.speak.mdx

@@ -7,31 +7,6 @@ description: "Documentation for the speak() method available in all Mastra voice
 
 The `speak()` method is a core function available in all Mastra voice providers that converts text to speech. It takes text input and returns an audio stream that can be played or saved.
 
-## Usage Example
-
-```typescript
-import { OpenAIVoice } from "@mastra/voice-openai";
-// Initialize a voice provider
-const voice = new OpenAIVoice({
-  speaker: "alloy", // Default voice
-});
-// Basic usage with default settings
-const audioStream = await voice.speak("Hello, world!");
-// Using a different voice for this specific request
-const audioStreamWithDifferentVoice = await voice.speak("Hello again!", {
-  speaker: "nova",
-});
-// Using provider-specific options
-const audioStreamWithOptions = await voice.speak("Hello with options!", {
-  speaker: "echo",
-  speed: 1.2, // OpenAI-specific option
-});
-// Using a text stream as input
-import { Readable } from "stream";
-const textStream = Readable.from(["Hello", " from", " a", " stream!"]);
-const audioStreamFromTextStream = await voice.speak(textStream);
-```
-
 ## Parameters
 
 <PropertiesTable
@@ -153,6 +128,81 @@ Each voice provider may support additional options specific to their implementat
   ]}
 />
 
+## Usage Example
+
+```typescript
+import { OpenAIVoice } from "@mastra/voice-openai";
+// Initialize a voice provider
+const voice = new OpenAIVoice({
+  speaker: "alloy", // Default voice
+});
+// Basic usage with default settings
+const audioStream = await voice.speak("Hello, world!");
+// Using a different voice for this specific request
+const audioStreamWithDifferentVoice = await voice.speak("Hello again!", {
+  speaker: "nova",
+});
+// Using provider-specific options
+const audioStreamWithOptions = await voice.speak("Hello with options!", {
+  speaker: "echo",
+  speed: 1.2, // OpenAI-specific option
+});
+// Using a text stream as input
+import { Readable } from "stream";
+const textStream = Readable.from(["Hello", " from", " a", " stream!"]);
+const audioStreamFromTextStream = await voice.speak(textStream);
+```
+
+## Using with CompositeVoice
+
+When using `CompositeVoice`, the `speak()` method delegates to the configured speaking provider:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { OpenAIVoice } from "@mastra/voice-openai";
+import { PlayAIVoice } from "@mastra/voice-playai";
+
+const voice = new CompositeVoice({
+  output: new PlayAIVoice(),
+  input: new OpenAIVoice(),
+});
+
+// This will use the PlayAIVoice provider
+const audioStream = await voice.speak("Hello, world!");
+```
+
+### Using AI SDK Model Providers
+
+You can also use AI SDK speech models directly with `CompositeVoice`:
+
+```typescript
+import { CompositeVoice } from "@mastra/core/voice";
+import { openai } from "@ai-sdk/openai";
+import { elevenlabs } from "@ai-sdk/elevenlabs";
+
+// Use AI SDK speech models
+const voice = new CompositeVoice({
+  output: elevenlabs.speech('eleven_turbo_v2'),  // AI SDK model
+  input: openai.transcription('whisper-1'),      // AI SDK model
+});
+
+// Works the same way
+const audioStream = await voice.speak("Hello from AI SDK!");
+
+// Provider-specific options can be passed through
+const audioWithOptions = await voice.speak("Hello with options!", {
+  speaker: 'Rachel',  // ElevenLabs voice
+  providerOptions: {
+    elevenlabs: {
+      stability: 0.5,
+      similarity_boost: 0.75,
+    }
+  }
+});
+```
+
+See the [CompositeVoice reference](/reference/v1/voice/composite-voice) for more details on AI SDK integration.
+
 ## Realtime Voice Providers
 
 When using realtime voice providers like `OpenAIRealtimeVoice`, the `speak()` method behaves differently:
@@ -181,21 +231,6 @@ voice.on("speaker", (stream) => {
 await voice.speak("Hello, this is realtime speech!");
 ```
 
-## Using with CompositeVoice
-
-When using `CompositeVoice`, the `speak()` method delegates to the configured speaking provider:
-
-```typescript
-import { CompositeVoice } from "@mastra/core/voice";
-import { OpenAIVoice } from "@mastra/voice-openai";
-import { PlayAIVoice } from "@mastra/voice-playai";
-const voice = new CompositeVoice({
-  speakProvider: new PlayAIVoice(),
-  listenProvider: new OpenAIVoice(),
-});
-// This will use the PlayAIVoice provider
-const audioStream = await voice.speak("Hello, world!");
-```
 
 ## Notes
 

package/.docs/raw/reference/voice/voice.updateConfig.mdx

@@ -15,7 +15,7 @@ import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
 // Initialize a real-time voice provider
 const voice = new OpenAIRealtimeVoice({
   realtimeConfig: {
-    model: "gpt-4o-mini-realtime",
+    model: "gpt-5.1-realtime",
     apiKey: process.env.OPENAI_API_KEY,
   },
   speaker: "alloy",

package/.docs/raw/server-db/mastra-client.mdx

@@ -240,7 +240,6 @@ const handleClientTool = async () => {
 This is a standard Mastra [agent](../agents/overview#setting-up-agents) configured to return hex color codes, intended to work with the browser-based client tool defined above.
 
 ```typescript title="src/mastra/agents/color-agent" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const colorAgent = new Agent({
@@ -249,7 +248,7 @@ export const colorAgent = new Agent({
   instructions: `You are a helpful CSS assistant.
   You can change the background color of web pages.
   Respond with a hex reference for the color requested by the user`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 ```
 

package/.docs/raw/streaming/overview.mdx

@@ -60,19 +60,30 @@ An agent stream provides access to various response properties:
 
 AI SDK v5 uses `LanguageModelV2` for the model providers. If you are getting an error that you are using an AI SDK v4 model you will need to upgrade your model package to the next major version.
 
-For integration with AI SDK v5, use `format` 'aisdk' to get an `AISDKV5OutputStream`:
+For integration with AI SDK v5, use the `toAISdkV5Stream()` utility from `@mastra/ai-sdk` to convert Mastra streams to AI SDK-compatible format:
+
+```typescript {2,9-12} showLineNumbers copy
+import { toAISdkV5Stream } from "@mastra/ai-sdk";
 
-```typescript {5} showLineNumbers copy
 const testAgent = mastra.getAgent("testAgent");
 
-const stream = await testAgent.stream(
-  [{ role: "user", content: "Help me organize my day" }],
-  { format: "aisdk" },
-);
+const stream = await testAgent.stream([
+  { role: "user", content: "Help me organize my day" },
+]);
 
-for await (const chunk of stream.textStream) {
-  process.stdout.write(chunk);
-}
+// Convert to AI SDK v5 compatible stream
+const aiSDKStream = toAISdkV5Stream(stream, { from: "agent" });
+
+// Use with AI SDK v5 methods
+```
+
+For converting messages to AI SDK v5 format, use the `toAISdkV5Messages()` utility from `@mastra/ai-sdk/ui`:
+
+```typescript {1,4} showLineNumbers copy
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+
+const messages = [{ role: "user", content: "Hello" }];
+const aiSDKMessages = toAISdkV5Messages(messages);
 ```
 
 ### Using `Agent.network()`

package/.docs/raw/streaming/tool-streaming.mdx

@@ -18,8 +18,7 @@ By combining writable tool streams with agent streaming, you gain fine grained c
 
 Agent streaming can be combined with tool calls, allowing tool outputs to be written directly into the agent’s streaming response. This makes it possible to surface tool activity as part of the overall interaction.
 
-```typescript {4,10} showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {3,9} showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 
 import { testTool } from "../tools/test-tool";
@@ -28,7 +27,7 @@ export const testAgent = new Agent({
   id: "test-agent",
   name: "Test Agent",
   instructions: "You are a weather agent.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: { testTool },
 });
 ```
@@ -117,9 +116,53 @@ for await (const chunk of stream) {
 }
 ```
 
+## Tool Lifecycle Hooks
+
+Tools support lifecycle hooks that allow you to monitor different stages of tool execution during streaming. These hooks are particularly useful for logging or analytics.
+
+### Example: Using onInputAvailable and onOutput
+
+```typescript showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "weather-tool",
+  description: "Get weather information",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  // Called when the complete input is available
+  onInputAvailable: ({ input, toolCallId }) => {
+    console.log(`Weather requested for: ${input.city}`);
+  },
+  execute: async (input) => {
+    const weather = await fetchWeather(input.city);
+    return weather;
+  },
+  // Called after successful execution
+  onOutput: ({ output, toolName }) => {
+    console.log(`${toolName} result: ${output.temperature}°F, ${output.conditions}`);
+  },
+});
+```
+
+### Available Hooks
+
+- **onInputStart**: Called when tool call input streaming begins
+- **onInputDelta**: Called for each chunk of input as it streams in
+- **onInputAvailable**: Called when complete input is parsed and validated
+- **onOutput**: Called after the tool successfully executes with the output
+
+For detailed documentation on all lifecycle hooks, see the [createTool() reference](/reference/v1/tools/create-tool#tool-lifecycle-hooks).
+
 ## Tool using an agent
 
-Pipe an agent’s `textStream` to the tool’s `writer`. This streams partial output, and Mastra automatically aggregates the agent’s usage into the tool run.
+Pipe an agent's `textStream` to the tool's `writer`. This streams partial output, and Mastra automatically aggregates the agent's usage into the tool run.
 
 ```typescript showLineNumbers copy
 import { createTool } from "@mastra/core/tools";

package/.docs/raw/tools-mcp/advanced-usage.mdx

@@ -110,7 +110,6 @@ You can then add this tool to your Mastra agent just like any other tool:
 
 ```typescript title="src/mastra/agents/mixedToolsAgent.ts"
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { vercelWeatherTool } from "../tools/vercelWeatherTool"; // Vercel AI SDK tool
 import { mastraTool } from "../tools/mastraTool"; // Mastra createTool tool
 
@@ -118,7 +117,7 @@ export const mixedToolsAgent = new Agent({
   id: "mixed-tools-agent",
   name: "Mixed Tools Agent",
   instructions: "You can use tools defined in different formats.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: {
     weatherVercel: vercelWeatherTool,
     someMastraTool: mastraTool,

package/.docs/raw/tools-mcp/mcp-overview.mdx

@@ -54,8 +54,7 @@ export const testMcpClient = new MCPClient({
 
 To use tools from an MCP server in an agent, import your `MCPClient` and call `.listTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
 
-```typescript {4,16} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {3,15} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
@@ -70,7 +69,7 @@ export const testAgent = new Agent({
       - US National Weather Service
 
       Answer questions using the information you find using the MCP Servers.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: await testMcpClient.listTools(),
 });
 ```
@@ -144,8 +143,7 @@ Use the `.listTools()` method to fetch tools from all configured MCP servers. Th
 
 > See [listTools()](/reference/v1/tools/mcp-client#listtools) for more information.
 
-```typescript {8} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {7} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";