@mastra/mcp-docs-server 1.2.4 → 1.2.5-alpha.3

package/.docs/docs/agents/adding-voice.md

@@ -1,383 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Voice
-
-Mastra agents can be enhanced with voice capabilities, allowing them to speak responses and listen to user input. You can configure an agent to use either a single voice provider or combine multiple providers for different operations.
-
-## Basic usage
-
-The simplest way to add voice to an agent is to use a single provider for both speaking and listening:
-
-```typescript
-import { createReadStream } from 'fs'
-import path from 'path'
-import { Agent } from '@mastra/core/agent'
-import { OpenAIVoice } from '@mastra/voice-openai'
-
-// Initialize the voice provider with default settings
-const voice = new OpenAIVoice()
-
-// Create an agent with voice capabilities
-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-5.5',
-  voice,
-})
-
-// The agent can now use voice for interaction
-const audioStream = await agent.voice.speak("Hello, I'm your AI assistant!", {
-  filetype: 'm4a',
-})
-
-playAudio(audioStream!)
-
-try {
-  const transcription = await agent.voice.listen(audioStream)
-  console.log(transcription)
-} catch (error) {
-  console.error('Error transcribing audio:', error)
-}
-```
-
-## Working with audio streams
-
-The `speak()` and `listen()` methods work with Node.js streams. Here's how to save and load audio files:
-
-### Saving Speech Output
-
-The `speak` method returns a stream that you can pipe to a file or speaker.
-
-```typescript
-import { createWriteStream } from 'fs'
-import path from 'path'
-
-// Generate speech and save to file
-const audio = await agent.voice.speak('Hello, World!')
-const filePath = path.join(process.cwd(), 'agent.mp3')
-const writer = createWriteStream(filePath)
-
-audio.pipe(writer)
-
-await new Promise<void>((resolve, reject) => {
-  writer.on('finish', () => resolve())
-  writer.on('error', reject)
-})
-```
-
-### Transcribing Audio Input
-
-The `listen` method expects a stream of audio data from a microphone or file.
-
-```typescript
-import { createReadStream } from 'fs'
-import path from 'path'
-
-// Read audio file and transcribe
-const audioFilePath = path.join(process.cwd(), '/agent.m4a')
-const audioStream = createReadStream(audioFilePath)
-
-try {
-  console.log('Transcribing audio file...')
-  const transcription = await agent.voice.listen(audioStream, {
-    filetype: 'm4a',
-  })
-  console.log('Transcription:', transcription)
-} catch (error) {
-  console.error('Error transcribing audio:', error)
-}
-```
-
-## Speech-to-speech voice interactions
-
-For more dynamic and interactive voice experiences, you can use real-time voice providers that support speech-to-speech capabilities:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { getMicrophoneStream } from '@mastra/node-audio'
-import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
-import { search, calculate } from '../tools'
-
-// Initialize the realtime voice provider
-const voice = new OpenAIRealtimeVoice({
-  apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-5.1-realtime',
-  speaker: 'alloy',
-})
-
-// Create an agent with speech-to-speech voice capabilities
-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-5.5',
-  tools: {
-    // Tools configured on Agent are passed to voice provider
-    search,
-    calculate,
-  },
-  voice,
-})
-
-// Establish a WebSocket connection
-await agent.voice.connect()
-
-// Start a conversation
-agent.voice.speak("Hello, I'm your AI assistant!")
-
-// Stream audio from a microphone
-const microphoneStream = getMicrophoneStream()
-agent.voice.send(microphoneStream)
-
-// When done with the conversation
-agent.voice.close()
-```
-
-### Per-session voice for concurrent sessions
-
-A static `voice` instance is shared across every request. For one-shot text-to-speech this is fine, but realtime and speech-to-speech providers store one WebSocket, one set of tools, and one request context per instance. If you deploy a single agent that handles several live sessions at once, a shared instance lets one session overwrite another session's tools, instructions, and request context.
-
-To give each session its own voice, provide `voice` as a resolver. Mastra runs the resolver on every `getVoice()` call and returns a fresh, session-owned instance:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
-
-export const agent = new Agent({
-  id: 'support-line',
-  name: 'Support Line',
-  instructions: ({ requestContext }) => `Help user ${requestContext.get('user')}.`,
-  model: 'openai/gpt-5.5',
-  voice: ({ requestContext }) => new OpenAIRealtimeVoice({ apiKey: requestContext.get('apiKey') }),
-})
-
-// Each concurrent session resolves its own voice instance
-const voice = await agent.getVoice({ requestContext })
-await voice.connect()
-```
-
-When you use a resolver:
-
-- Each call to `getVoice()` returns a new instance, so concurrent sessions never share state.
-- Mastra doesn't add tools or instructions to a resolver instance. Configure those inside the resolver or on the provider.
-- You own the lifecycle of the returned instance, so call `disconnect()` or `close()` when the session ends.
-
-The `agent.voice` getter has no request context, so it throws when `voice` is a resolver. Use `agent.getVoice({ requestContext })` instead.
-
-### Event System
-
-The realtime voice provider emits several events you can listen for:
-
-```typescript
-// Listen for speech audio data sent from voice provider
-agent.voice.on('speaking', ({ audio }) => {
-  // audio contains ReadableStream or Int16Array audio data
-})
-
-// Listen for transcribed text sent from both voice provider and user
-agent.voice.on('writing', ({ text, role }) => {
-  console.log(`${role} said: ${text}`)
-})
-
-// Listen for errors
-agent.voice.on('error', error => {
-  console.error('Voice error:', error)
-})
-```
-
-## Examples
-
-### End-to-end voice interaction
-
-This example demonstrates a voice interaction between two agents. The hybrid voice agent, which uses multiple providers, speaks a question, which is saved as an audio file. The unified voice agent listens to that file, processes the question, generates a response, and speaks it back. Both audio outputs are saved to the `audio` directory.
-
-The following files are created:
-
-- **hybrid-question.mp3** – Hybrid agent's spoken question.
-- **unified-response.mp3** – Unified agent's spoken response.
-
-```typescript
-import 'dotenv/config'
-
-import path from 'path'
-import { createReadStream } from 'fs'
-import { Agent } from '@mastra/core/agent'
-import { CompositeVoice } from '@mastra/core/voice'
-import { OpenAIVoice } from '@mastra/voice-openai'
-import { Mastra } from '@mastra/core'
-
-// Saves an audio stream to a file in the audio directory, creating the directory if it doesn't exist.
-export const saveAudioToFile = async (
-  audio: NodeJS.ReadableStream,
-  filename: string,
-): Promise<void> => {
-  const audioDir = path.join(process.cwd(), 'audio')
-  const filePath = path.join(audioDir, filename)
-
-  await fs.promises.mkdir(audioDir, { recursive: true })
-
-  const writer = createWriteStream(filePath)
-  audio.pipe(writer)
-  return new Promise((resolve, reject) => {
-    writer.on('finish', resolve)
-    writer.on('error', reject)
-  })
-}
-
-// Saves an audio stream to a file in the audio directory, creating the directory if it doesn't exist.
-export const convertToText = async (input: string | NodeJS.ReadableStream): Promise<string> => {
-  if (typeof input === 'string') {
-    return input
-  }
-
-  const chunks: Buffer[] = []
-  return new Promise((resolve, reject) => {
-    inputData.on('data', chunk => chunks.push(Buffer.from(chunk)))
-    inputData.on('error', reject)
-    inputData.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')))
-  })
-}
-
-export const hybridVoiceAgent = new Agent({
-  id: 'hybrid-voice-agent',
-  name: 'Hybrid Voice Agent',
-  model: 'openai/gpt-5.5',
-  instructions: 'You can speak and listen using different providers.',
-  voice: new CompositeVoice({
-    input: new OpenAIVoice(),
-    output: new OpenAIVoice(),
-  }),
-})
-
-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-5.5',
-  voice: new OpenAIVoice(),
-})
-
-export const mastra = new Mastra({
-  agents: { hybridVoiceAgent, unifiedVoiceAgent },
-})
-
-const hybridVoiceAgent = mastra.getAgent('hybridVoiceAgent')
-const unifiedVoiceAgent = mastra.getAgent('unifiedVoiceAgent')
-
-const question = 'What is the meaning of life in one sentence?'
-
-const hybridSpoken = await hybridVoiceAgent.voice.speak(question)
-
-await saveAudioToFile(hybridSpoken!, 'hybrid-question.mp3')
-
-const audioStream = createReadStream(path.join(process.cwd(), 'audio', 'hybrid-question.mp3'))
-const unifiedHeard = await unifiedVoiceAgent.voice.listen(audioStream)
-
-const inputText = await convertToText(unifiedHeard!)
-
-const unifiedResponse = await unifiedVoiceAgent.generate(inputText)
-const unifiedSpoken = await unifiedVoiceAgent.voice.speak(unifiedResponse.text)
-
-await saveAudioToFile(unifiedSpoken!, 'unified-response.mp3')
-```
-
-### Using Multiple Providers
-
-For more flexibility, you can use different providers for speaking and listening using the CompositeVoice class:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { CompositeVoice } from '@mastra/core/voice'
-import { OpenAIVoice } from '@mastra/voice-openai'
-import { PlayAIVoice } from '@mastra/voice-playai'
-
-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-5.5',
-
-  // Create a composite voice using OpenAI for listening and PlayAI for speaking
-  voice: new CompositeVoice({
-    input: new OpenAIVoice(),
-    output: new PlayAIVoice(),
-  }),
-})
-```
-
-### Using AI SDK
-
-Mastra supports using AI SDK's transcription and speech models directly in `CompositeVoice`, giving you access to a wide range of providers through the AI SDK ecosystem:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { CompositeVoice } from '@mastra/core/voice'
-import { openai } from '@ai-sdk/openai'
-import { elevenlabs } from '@ai-sdk/elevenlabs'
-import { groq } from '@ai-sdk/groq'
-
-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.5',
-
-  // Pass AI SDK models directly to CompositeVoice
-  voice: new CompositeVoice({
-    input: openai.transcription('whisper-1'), // AI SDK transcription model
-    output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech model
-  }),
-})
-
-// Use voice capabilities as usual
-const audioStream = await agent.voice.speak('Hello!')
-const transcribedText = await agent.voice.listen(audioStream)
-```
-
-#### Mix and Match Providers
-
-You can mix AI SDK models with Mastra voice providers:
-
-```typescript
-import { CompositeVoice } from '@mastra/core/voice'
-import { PlayAIVoice } from '@mastra/voice-playai'
-import { openai } from '@ai-sdk/openai'
-
-// Use AI SDK for transcription and Mastra provider for speech
-const voice = new CompositeVoice({
-  input: openai.transcription('whisper-1'), // AI SDK
-  output: new PlayAIVoice(), // Mastra provider
-})
-```
-
-For the complete list of supported AI SDK providers and their capabilities:
-
-- [Transcription](https://ai-sdk.dev/docs/providers/openai/transcription)
-- [Speech](https://ai-sdk.dev/docs/providers/elevenlabs/speech)
-
-## Supported voice providers
-
-Mastra supports multiple voice providers for text-to-speech (TTS) and speech-to-text (STT) capabilities:
-
-| Provider        | Package                         | Features                                  | Reference                                                          |
-| --------------- | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
-| OpenAI          | `@mastra/voice-openai`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/openai)          |
-| OpenAI Realtime | `@mastra/voice-openai-realtime` | Realtime speech-to-speech                 | [Documentation](https://mastra.ai/reference/voice/openai-realtime) |
-| AWS Nova Sonic  | `@mastra/voice-aws-nova-sonic`  | Realtime speech-to-speech via AWS Bedrock | [Documentation](https://mastra.ai/reference/voice/aws-nova-sonic)  |
-| ElevenLabs      | `@mastra/voice-elevenlabs`      | High-quality TTS                          | [Documentation](https://mastra.ai/reference/voice/elevenlabs)      |
-| PlayAI          | `@mastra/voice-playai`          | TTS                                       | [Documentation](https://mastra.ai/reference/voice/playai)          |
-| Google          | `@mastra/voice-google`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/google)          |
-| Deepgram        | `@mastra/voice-deepgram`        | STT                                       | [Documentation](https://mastra.ai/reference/voice/deepgram)        |
-| Murf            | `@mastra/voice-murf`            | TTS                                       | [Documentation](https://mastra.ai/reference/voice/murf)            |
-| Speechify       | `@mastra/voice-speechify`       | TTS                                       | [Documentation](https://mastra.ai/reference/voice/speechify)       |
-| Sarvam          | `@mastra/voice-sarvam`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/sarvam)          |
-| Azure           | `@mastra/voice-azure`           | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
-| Cloudflare      | `@mastra/voice-cloudflare`      | TTS                                       | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
-
-## Next steps
-
-- [Voice API Reference](https://mastra.ai/reference/voice/mastra-voice): Detailed API documentation for voice capabilities
-- [Text to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/text-to-speech): Interactive story generator and other TTS implementations
-- [Speech to Text Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-text): Voice memo app and other STT implementations
-- [Speech to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-speech): Real-time voice conversation with call analysis

package/.docs/docs/community/contributing-templates.md

@@ -1,5 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Contributing templates
-
-The Mastra community plays a vital role in creating templates that showcase innovative application patterns. We're currently reworking our template contribution process to ensure high-quality, valuable templates for the community. For the time being, we're not accepting new template contributions. Please keep an eye on this page for updates on when contributions will reopen and the new submission process.

package/.docs/docs/community/discord.md

@@ -1,11 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Discord community
-
-The Discord server has over 1000 members and serves as the main discussion forum for Mastra. The Mastra team monitors Discord during North American and European business hours, with community members active across other time zones.
-
-[Join the Discord server](https://discord.gg/BTYqqHKUrf)
-
-## Discord MCP bot
-
-In addition to community members, we've an (experimental!) Discord bot that can also help answer questions. It uses [Model Context Protocol (MCP)](https://mastra.ai/docs/mcp/overview). You can ask it a question with `/ask` (either in public channels or DMs) and clear history (in DMs only) with `/cleardm`.

package/.docs/guides/build-your-ui/copilotkit.md

@@ -1,291 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Using CopilotKit
-
-[CopilotKit](https://www.copilotkit.ai/) provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.
-
-Visit the [CopilotKit documentation](https://docs.copilotkit.ai/) to learn more about CopilotKit concepts, components, and advanced usage patterns.
-
-> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart) guide.
-
-> **Tip:** Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
-
-## Integration guide
-
-Run Mastra as a standalone server and connect your Next.js frontend (with CopilotKit) to its API endpoints.
-
-1. Set up your directory structure. A possible directory structure could look like this:
-
-   ```bash
-   project-root
-   ├── mastra-server
-   │   ├── src
-   │   │   └── mastra
-   │   └── package.json
-   └── my-copilot-app
-       └── package.json
-   ```
-
-   Bootstrap your Mastra server:
-
-   **npm**:
-
-   ```bash
-   npx create-mastra@latest
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm dlx create-mastra@latest
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn dlx create-mastra@latest
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun x create-mastra@latest
-   ```
-
-   This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project.
-
-   Navigate to your newly created Mastra server directory:
-
-   ```bash
-   cd mastra-server # Replace with the actual directory name you provided
-   ```
-
-   You now have a basic Mastra server project ready. You should have the following files and folders:
-
-   ```bash
-   src
-   └── mastra
-       ├── agents
-       │   └── weather-agent.ts
-       ├── scorers
-       │   └── weather-scorer.ts
-       ├── tools
-       │   └── weather-tool.ts
-       ├── workflows
-       │   └── weather-workflow.ts
-       └── index.ts
-   ```
-
-   > **Note:** Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
-
-2. Create a chat route for the CopilotKit frontend by using the `registerCopilotKit()` helper from `@ag-ui/mastra`. Add it to your Mastra project (and its peer dependencies):
-
-   **npm**:
-
-   ```bash
-   npm install @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add @ag-ui/mastra @mastra/client-js @mastra/core @ag-ui/core @ag-ui/client @copilotkit/runtime
-   ```
-
-   In your `src/mastra/index.ts` file, register the chat route:
-
-   ```typescript
-   import { Mastra } from '@mastra/core/mastra'
-   import { registerCopilotKit } from '@ag-ui/mastra/copilotkit'
-   // Rest of the imports...
-
-   export const mastra = new Mastra({
-     // Rest of the configuration...
-     server: {
-       cors: {
-         origin: '*',
-         allowMethods: ['*'],
-         allowHeaders: ['*'],
-       },
-       apiRoutes: [
-         registerCopilotKit({
-           path: '/chat',
-           resourceId: 'weatherAgent',
-         }),
-       ],
-     },
-   })
-   ```
-
-   This will make the `weatherAgent` available at `/chat` in a CopilotKit-compatible format. You have to add the CORS configuration to allow the CopilotKit frontend to access the Mastra server. For production deployments, make sure to restrict the CORS origins to only your frontend domain.
-
-3. Run the Mastra server using the following command:
-
-   **npm**:
-
-   ```bash
-   npm run dev
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm run dev
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn dev
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun run dev
-   ```
-
-   By default, the Mastra server will run on `http://localhost:4111`. Keep this server running for the next steps where we'll set up the CopilotKit frontend to connect to it.
-
-4. Go up one directory to your project root.
-
-   ```bash
-   cd ..
-   ```
-
-   Create a new Next.js project with the name `my-copilot-app`:
-
-   **npm**:
-
-   ```bash
-   npx create-next-app@latest my-copilot-app
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm dlx create-next-app@latest my-copilot-app
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn dlx create-next-app@latest my-copilot-app
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun x create-next-app@latest my-copilot-app
-   ```
-
-   Navigate to your newly created Next.js project directory:
-
-   ```bash
-   cd my-copilot-app
-   ```
-
-5. Install the CopilotKit UI packages which you'll use to display a chat interface:
-
-   **npm**:
-
-   ```bash
-   npm install @copilotkit/react-ui @copilotkit/react-core
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add @copilotkit/react-ui @copilotkit/react-core
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn add @copilotkit/react-ui @copilotkit/react-core
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add @copilotkit/react-ui @copilotkit/react-core
-   ```
-
-   Open the home route of the Next.js app (usually `app/page.tsx` or `src/app/page.tsx`) and replace the existing contents with the following code to set up a basic CopilotKit chat interface:
-
-   ```typescript
-   import { CopilotChat } from '@copilotkit/react-ui'
-   import { CopilotKit } from '@copilotkit/react-core'
-   import '@copilotkit/react-ui/styles.css'
-
-   export default function Home() {
-     return (
-       <CopilotKit runtimeUrl="http://localhost:4111/chat" agent="weatherAgent">
-         <CopilotChat
-           labels={{
-             title: 'Weather Agent',
-             initial: 'Hi! 👋 Ask me about the weather, forecasts, and climate.',
-           }}
-         />
-       </CopilotKit>
-     )
-   }
-   ```
-
-6. You're ready to connect the pieces! Make sure both the Mastra server and the CopilotKit frontend are running. Start the Next.js development server:
-
-   **npm**:
-
-   ```bash
-   npm run dev
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm run dev
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn dev
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun run dev
-   ```
-
-   You should now be able to chat with your agent in the browser.
-
-Congratulations! You have successfully integrated Mastra with CopilotKit using a separate server approach. Your CopilotKit frontend now communicates with a standalone Mastra agent server.
-
-## Deployment
-
-When deploying your Mastra server with CopilotKit, you must exclude `@copilotkit/runtime` from the bundle. This package contains dependencies that aren't compatible with bundling and will cause 500 errors if included.
-
-> **Note:** This issue doesn't occur during development with `mastra dev` since it doesn't require bundling. However, anyone running `mastra build` for deployment will encounter this issue.
-
-Add the `@copilotkit/runtime` package to your bundler externals configuration:
-
-```typescript
-export const mastra = new Mastra({
-  bundler: {
-    externals: ['@copilotkit/runtime'],
-  },
-})
-```