@mastra/mcp-docs-server 0.13.40-alpha.0 → 0.13.41-alpha.0

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

@@ -8,6 +8,8 @@ description: "Documentation for the AzureVoice class, providing text-to-speech a
 The AzureVoice class in Mastra provides text-to-speech and speech-to-text capabilities using Microsoft Azure Cognitive Services.
 
 ## Usage Example
+This requires Azure Speech Services credentials that can be provided through environment variables or directly in the configuration:
+
 
 ```typescript
 import { AzureVoice } from "@mastra/voice-azure";
@@ -15,29 +17,25 @@ import { AzureVoice } from "@mastra/voice-azure";
 // Initialize with configuration
 const voice = new AzureVoice({
   speechModel: {
-    name: "neural",
-    apiKey: "your-azure-speech-api-key",
-    region: "eastus",
+    apiKey: "your-azure-speech-api-key", // Or use AZURE_API_KEY env var
+    region: "eastus", // Or use AZURE_REGION env var
+    voiceName: "en-US-AriaNeural", // Optional: specific voice for TTS
   },
   listeningModel: {
-    name: "whisper",
-    apiKey: "your-azure-speech-api-key",
-    region: "eastus",
+    apiKey: "your-azure-speech-api-key", // Or use AZURE_API_KEY env var
+    region: "eastus", // Or use AZURE_REGION env var
+    language: "en-US", // Optional: recognition language for STT
   },
-  speaker: "en-US-JennyNeural", // Default voice
+  speaker: "en-US-JennyNeural", // Optional: default voice
 });
 
 // Convert text to speech
 const audioStream = await voice.speak("Hello, how can I help you?", {
-  speaker: "en-US-GuyNeural", // Override default voice
-  style: "cheerful", // Voice style
+  speaker: "en-US-GuyNeural", // Optional: override default voice
 });
 
 // Convert speech to text
-const text = await voice.listen(audioStream, {
-  filetype: "wav",
-  language: "en-US",
-});
+const text = await voice.listen(audioStream);
 ```
 
 ## Configuration
@@ -69,26 +67,36 @@ const text = await voice.listen(audioStream, {
 
 ### AzureSpeechConfig
 
+Configuration object for speech synthesis (`speechModel`) and recognition (`listeningModel`).
+
 <PropertiesTable
   content={[
     {
-      name: "name",
-      type: "'neural' | 'standard' | 'whisper'",
-      description: "Model type to use. 'neural' for TTS, 'whisper' for STT.",
+      name: "apiKey",
+      type: "string",
+      description:
+        "Azure Speech Services API key (NOT Azure OpenAI key). Falls back to AZURE_API_KEY environment variable.",
       isOptional: true,
     },
     {
-      name: "apiKey",
+      name: "region",
       type: "string",
       description:
-        "Azure Speech Services API key. Falls back to AZURE_SPEECH_KEY environment variable.",
+        "Azure region (e.g., 'eastus', 'westeurope'). Falls back to AZURE_REGION environment variable.",
       isOptional: true,
     },
     {
-      name: "region",
+      name: "voiceName",
+      type: "string",
+      description:
+        "Voice ID for speech synthesis (e.g., 'en-US-AriaNeural', 'en-US-JennyNeural'). Only used in speechModel. See voice list below.",
+      isOptional: true,
+    },
+    {
+      name: "language",
       type: "string",
       description:
-        "Azure region (e.g., 'eastus', 'westeurope'). Falls back to AZURE_SPEECH_REGION environment variable.",
+        "Recognition language code (e.g., 'en-US', 'fr-FR'). Only used in listeningModel.",
       isOptional: true,
     },
   ]}
@@ -111,32 +119,14 @@ Converts text to speech using Azure's neural text-to-speech service.
     {
       name: "options.speaker",
       type: "string",
-      description: "Voice ID to use for speech synthesis.",
+      description: "Voice ID to use for speech synthesis (e.g., 'en-US-JennyNeural'). Overrides the default voice.",
       isOptional: true,
       defaultValue: "Constructor's speaker value",
     },
-    {
-      name: "options.style",
-      type: "string",
-      description: "Speaking style (e.g., 'cheerful', 'sad', 'angry').",
-      isOptional: true,
-    },
-    {
-      name: "options.rate",
-      type: "string",
-      description: "Speaking rate (e.g., 'slow', 'medium', 'fast').",
-      isOptional: true,
-    },
-    {
-      name: "options.pitch",
-      type: "string",
-      description: "Voice pitch (e.g., 'low', 'medium', 'high').",
-      isOptional: true,
-    },
   ]}
 />
 
-Returns: `Promise<NodeJS.ReadableStream>`
+Returns: `Promise<NodeJS.ReadableStream>` - Audio stream in WAV format
 
 ### listen()
 
@@ -147,31 +137,19 @@ Transcribes audio using Azure's speech-to-text service.
     {
       name: "audioStream",
       type: "NodeJS.ReadableStream",
-      description: "Audio stream to transcribe.",
+      description: "Audio stream to transcribe. Must be in WAV format.",
       isOptional: false,
     },
-    {
-      name: "options.filetype",
-      type: "string",
-      description: "Audio format of the input stream.",
-      isOptional: true,
-      defaultValue: "'wav'",
-    },
-    {
-      name: "options.language",
-      type: "string",
-      description: "Language code for transcription.",
-      isOptional: true,
-      defaultValue: "'en-US'",
-    },
   ]}
 />
 
-Returns: `Promise<string>`
+Returns: `Promise<string>` - The recognized text from the audio
+
+**Note:** Language and recognition settings are configured in the `listeningModel` configuration during initialization, not passed as options to this method.
 
 ### getSpeakers()
 
-Returns an array of available voice options, where each node contains:
+Returns an array of available voice options (200+ voices), where each node contains:
 
 <PropertiesTable
   content={[
@@ -179,40 +157,77 @@ Returns an array of available voice options, where each node contains:
       name: "voiceId",
       type: "string",
       description:
-        "Unique identifier for the voice (e.g., 'en-US-JennyNeural')",
-      isOptional: false,
-    },
-    {
-      name: "name",
-      type: "string",
-      description: "Human-readable name of the voice",
+        "Unique identifier for the voice (e.g., 'en-US-JennyNeural', 'fr-FR-DeniseNeural')",
       isOptional: false,
     },
     {
-      name: "locale",
+      name: "language",
       type: "string",
-      description: "Language locale of the voice (e.g., 'en-US')",
+      description: "Language code extracted from voice ID (e.g., 'en', 'fr')",
       isOptional: false,
     },
     {
-      name: "gender",
+      name: "region",
       type: "string",
-      description: "Gender of the voice ('Male' or 'Female')",
+      description: "Region code extracted from voice ID (e.g., 'US', 'GB', 'FR')",
       isOptional: false,
     },
-    {
-      name: "styles",
-      type: "string[]",
-      description: "Available speaking styles for the voice",
-      isOptional: true,
-    },
   ]}
 />
 
-## Notes
+Returns: `Promise<Array<{ voiceId: string; language: string; region: string; }>>`
+
+## Important Notes
+
+### Azure Speech Services vs Azure OpenAI
+
+**⚠️ Critical:** This package uses **Azure Speech Services**, which is different from **Azure OpenAI Services**.
+
+- **DO NOT** use your `AZURE_OPENAI_API_KEY` for this package
+- **DO** use an Azure Speech Services subscription key (obtain from Azure Portal under "Speech Services")
+- These are separate Azure resources with different API keys and endpoints
+
+### Environment Variables
+
+API keys and regions can be provided via constructor options or environment variables:
+
+- `AZURE_API_KEY` - Your Azure Speech Services subscription key
+- `AZURE_REGION` - Your Azure region (e.g., 'eastus', 'westeurope')
+
+### Voice Capabilities
+
+- Azure offers 200+ neural voices across 50+ languages
+- Each voice ID follows the format: `{language}-{region}-{name}Neural` (e.g., 'en-US-JennyNeural')
+- Some voices include multilingual support or HD quality variants
+- Audio output is in WAV format
+- Audio input for recognition must be in WAV format
+
+## Available Voices
+
+Azure provides 200+ neural voices across many languages. Some popular English voices include:
+
+- **US English:**
+  - `en-US-AriaNeural` (Female, default)
+  - `en-US-JennyNeural` (Female)
+  - `en-US-GuyNeural` (Male)
+  - `en-US-DavisNeural` (Male)
+  - `en-US-AvaNeural` (Female)
+  - `en-US-AndrewNeural` (Male)
+
+- **British English:**
+  - `en-GB-SoniaNeural` (Female)
+  - `en-GB-RyanNeural` (Male)
+  - `en-GB-LibbyNeural` (Female)
+
+- **Australian English:**
+  - `en-AU-NatashaNeural` (Female)
+  - `en-AU-WilliamNeural` (Male)
+
+To get a complete list of all 200+ voices:
+
+```typescript
+const voices = await voice.getSpeakers();
+console.log(voices); // Array of { voiceId, language, region }
+```
 
-- API keys can be provided via constructor options or environment variables (AZURE_SPEECH_KEY and AZURE_SPEECH_REGION)
-- Azure offers a wide range of neural voices across many languages
-- Some voices support speaking styles like cheerful, sad, angry, etc.
-- Speech recognition supports multiple audio formats and languages
-- Azure's speech services provide high-quality neural voices with natural-sounding speech
+For more information, see the [Azure Neural TTS documentation](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=tts).

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/mcp-docs-server
 
+## 0.13.41-alpha.0
+
+### Patch Changes
+
+- Add migration tool to mcp docs server for stable branch that will let users know to upgrade mcp docs server @latest to @beta to get the proper migration tool. ([#10200](https://github.com/mastra-ai/mastra/pull/10200))
+
+- Updated dependencies [[`f21ed89`](https://github.com/mastra-ai/mastra/commit/f21ed89577cfa00d616f10eaf10d8feb096f283e), [`eebb7bb`](https://github.com/mastra-ai/mastra/commit/eebb7bb407c57342a3be3a2efbe68c696589feeb), [`c6e6d07`](https://github.com/mastra-ai/mastra/commit/c6e6d071ecf346a80dceab410af2c567c7e66a57), [`0e6df8f`](https://github.com/mastra-ai/mastra/commit/0e6df8f66340992cb1b319834657deb17368de52), [`6295fd7`](https://github.com/mastra-ai/mastra/commit/6295fd783d49075d5bf2c18ff9486e94d36aaa56), [`d813cf7`](https://github.com/mastra-ai/mastra/commit/d813cf7251695d85cc60469058384ffa74974484)]:
+  - @mastra/mcp@0.14.3-alpha.0
+  - @mastra/core@0.24.2-alpha.0
+
+## 0.13.40
+
+### Patch Changes
+
+- Updated dependencies [[`0a0aa87`](https://github.com/mastra-ai/mastra/commit/0a0aa87910dd9234ae11e8146fbf54d71f0b1516), [`56bbbd0`](https://github.com/mastra-ai/mastra/commit/56bbbd0eb4510455ff03d6bf2827fdbd307938be), [`d576fd8`](https://github.com/mastra-ai/mastra/commit/d576fd8f2a3c61bcf2f7d5d2bdfb496d442c46c2), [`5e48406`](https://github.com/mastra-ai/mastra/commit/5e48406766fa94e2b7c56b70fb7d6068cf7f3989), [`7fcce62`](https://github.com/mastra-ai/mastra/commit/7fcce62880c3525fbf752d59c0ac2c478cffe024), [`16a324f`](https://github.com/mastra-ai/mastra/commit/16a324f8c30a07d0d899bc2e4e7998c6b40a4cb6), [`26aee16`](https://github.com/mastra-ai/mastra/commit/26aee160149e7acb84a533bf45631aaed6dd7077), [`b063a81`](https://github.com/mastra-ai/mastra/commit/b063a8144176915a766ea15888e1e8a06a020776), [`5ff9462`](https://github.com/mastra-ai/mastra/commit/5ff9462691c80a6841b014bcc68f6a85c3fd3fbf)]:
+  - @mastra/core@0.24.1
+
 ## 0.13.40-alpha.0
 
 ### Patch Changes

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAiBxC,QAAA,IAAI,MAAM,EAAE,SAAS,CAAC;AA+BtB,iBAAe,SAAS,kBAQvB;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAmBxC,QAAA,IAAI,MAAM,EAAE,SAAS,CAAC;AAiCtB,iBAAe,SAAS,kBAQvB;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC"}

package/dist/prompts/migration.d.ts

@@ -0,0 +1,3 @@
+import type { MCPServerPrompts } from '@mastra/mcp';
+export declare const migrationPromptMessages: MCPServerPrompts;
+//# sourceMappingURL=migration.d.ts.map

package/dist/prompts/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/prompts/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAiDpD,eAAO,MAAM,uBAAuB,EAAE,gBAcrC,CAAC"}

package/dist/stdio.js

@@ -102,6 +102,64 @@ function createLogger(server2) {
   };
 }
 var logger = createLogger();
+
+// src/prompts/migration.ts
+var UPGRADE_MESSAGE = `# Migration Guide Upgrade Required
+
+To access migration guides for upgrading to Mastra v1.0-beta, you need to upgrade your mcp-docs-server to the beta version.
+
+## How to Upgrade
+
+The migration tool and prompts are only available in the beta version of the mcp-docs-server.
+
+Visit the installation guide for detailed instructions on how to upgrade to the beta version:
+
+https://mastra.ai/docs/v1/getting-started/mcp-docs-server#installation
+
+Once upgraded, you'll be able to:
+- Browse migration guides with the \`mastraMigration\` tool
+- Use migration prompts like \`upgrade-to-v1\` and \`migration-checklist\`
+- Get step-by-step migration instructions for each breaking change
+- Use automated codemods to handle many migrations automatically
+
+## Why Beta?
+
+The migration guides are specific to the v1.0-beta release and are actively being updated as the beta evolves. The stable (0.x) documentation server doesn't include these guides as they're not relevant to users on the stable version.
+
+---
+
+**Note:** This message is shown because you're currently using the stable (@latest) version of @mastra/mcp-docs-server. Upgrade to @beta to access migration guides and prompts.`;
+var migrationPrompts = [
+  {
+    name: "upgrade-to-v1",
+    description: 'Get a guided migration plan for upgrading from Mastra v0.x to v1.0-beta. Optionally specify an area (e.g., "agent", "workflow") to focus on.',
+    arguments: [
+      {
+        name: "area",
+        description: 'Optional: A specific area to focus the migration guide on (e.g., "agent", "workflow", "tools")',
+        required: false
+      }
+    ]
+  },
+  {
+    name: "migration-checklist",
+    description: "Get a comprehensive checklist for migrating to Mastra v1.0-beta. Lists all breaking changes organized by area."
+  }
+];
+var migrationPromptMessages = {
+  listPrompts: async () => migrationPrompts,
+  getPromptMessages: async () => {
+    return [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: UPGRADE_MESSAGE
+        }
+      }
+    ];
+  }
+};
 var BLOG_BASE_URL = process.env.BLOG_URL || "https://mastra.ai";
 async function fetchBlogPosts() {
   void logger.debug("Fetching list of blog posts");
@@ -1090,6 +1148,93 @@ var examplesTool = {
     }
   }
 };
+var migrationInputSchema = z.object({
+  path: z.string().optional().describe(
+    'Path to the migration guide (e.g., "upgrade-to-v1/agent", "agentnetwork"). If not provided, lists all available migrations.\n\nExample migration paths:\n- agentnetwork\n- upgrade-to-v1/agent\n- upgrade-to-v1/cli\n- upgrade-to-v1/client\n- upgrade-to-v1/evals\n...'
+  ),
+  listSections: z.boolean().optional().describe("Set to true to list all section headers in a migration guide without fetching full content."),
+  sections: z.array(z.string()).optional().describe(
+    "Specific section titles to fetch from the migration guide. If not provided, returns the entire guide. Use this after exploring section headers."
+  ),
+  queryKeywords: z.array(z.string()).optional().describe("Keywords to search across all migration guides. Use this to find guides related to specific topics.")
+});
+var UPGRADE_MESSAGE2 = `# Migration Guide Upgrade Required
+
+To access migration guides for upgrading to Mastra v1.0-beta, you need to upgrade your mcp-docs-server to the beta version.
+
+## How to Upgrade
+
+The migration tool is only available in the beta version of the mcp-docs-server.
+
+1. **Update your MCP server configuration** to use the beta version. Visit the installation guide for detailed instructions:
+
+   https://mastra.ai/docs/v1/getting-started/mcp-docs-server#installation
+
+2. **Restart your MCP server** after updating to pick up the beta version
+
+3. **Access migration guides** - Once upgraded, you'll be able to:
+   - Browse migration guides with the \`mastraMigration\` tool
+   - Get step-by-step migration instructions for each breaking change
+   - Use automated codemods to handle many migrations automatically
+
+## Why Beta?
+
+The migration guides are specific to the v1.0-beta release and are actively being updated as the beta evolves. The stable (0.x) documentation server doesn't include these guides as they're not relevant to users on the stable version.
+
+## Need Help?
+
+If you have questions about upgrading:
+- Check the Mastra documentation at https://mastra.ai/docs
+- Visit the GitHub repository for issues and discussions
+- Join the Mastra community for support
+
+---
+
+**Note:** This message is shown because you're currently using the stable (@latest) version of @mastra/mcp-docs-server. Upgrade to @beta to access migration guides.`;
+var migrationTool = {
+  name: "mastraMigration",
+  description: `Get migration guidance for Mastra version upgrades and breaking changes.
+
+This tool works like a file browser - navigate through directories to find migration guides:
+
+**Step 1: List top-level migrations**
+- Call with no parameters: \`{}\`
+- Shows all top-level migration guides and directories
+
+**Step 2: Navigate into a directory**
+- Add trailing slash to explore: \`{ path: "upgrade-to-v1/" }\`
+- Lists all migration guides in that directory
+
+**Step 3: View a migration guide**
+- Without trailing slash: \`{ path: "upgrade-to-v1/agent" }\`
+- Returns the full migration guide content
+
+**Step 4: Explore guide sections (optional)**
+- List sections: \`{ path: "upgrade-to-v1/agent", listSections: true }\`
+- Get specific sections: \`{ path: "upgrade-to-v1/agent", sections: ["Voice methods"] }\`
+
+**Alternative: Search by keywords**
+- \`{ queryKeywords: ["RuntimeContext", "pagination"] }\`
+
+**Examples:**
+1. List top-level: \`{}\`
+2. Navigate to upgrade-to-v1: \`{ path: "upgrade-to-v1/" }\`
+3. Get agent guide: \`{ path: "upgrade-to-v1/agent" }\`
+4. List guide sections: \`{ path: "upgrade-to-v1/agent", listSections: true }\`
+5. Search: \`{ queryKeywords: ["RuntimeContext"] }\`
+
+**Tip:** Paths ending with \`/\` list directory contents. Paths without \`/\` fetch the migration guide.`,
+  parameters: migrationInputSchema,
+  execute: async (args) => {
+    void logger.debug("Executing mastraMigration tool (stub version)", { args });
+    try {
+      return UPGRADE_MESSAGE2;
+    } catch (error) {
+      void logger.error("Failed to execute mastraMigration tool", error);
+      throw error;
+    }
+  }
+};
 
 // src/index.ts
 var server;
@@ -1110,12 +1255,14 @@ server = new MCPServer({
     mastraDocs: docsTool,
     mastraExamples: examplesTool,
     mastraChanges: changesTool,
+    mastraMigration: migrationTool,
     startMastraCourse,
     getMastraCourseStatus,
     startMastraCourseLesson,
     nextMastraCourseStep,
     clearMastraCourseHistory
-  }
+  },
+  prompts: migrationPromptMessages
 });
 Object.assign(logger, createLogger(server));
 async function runServer() {

package/dist/tools/migration.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const migrationInputSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    listSections: z.ZodOptional<z.ZodBoolean>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    queryKeywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+    queryKeywords?: string[] | undefined;
+    listSections?: boolean | undefined;
+    sections?: string[] | undefined;
+}, {
+    path?: string | undefined;
+    queryKeywords?: string[] | undefined;
+    listSections?: boolean | undefined;
+    sections?: string[] | undefined;
+}>;
+export type MigrationInput = z.infer<typeof migrationInputSchema>;
+export declare const migrationTool: {
+    name: string;
+    description: string;
+    parameters: z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        listSections: z.ZodOptional<z.ZodBoolean>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        queryKeywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        path?: string | undefined;
+        queryKeywords?: string[] | undefined;
+        listSections?: boolean | undefined;
+        sections?: string[] | undefined;
+    }, {
+        path?: string | undefined;
+        queryKeywords?: string[] | undefined;
+        listSections?: boolean | undefined;
+        sections?: string[] | undefined;
+    }>;
+    execute: (args: MigrationInput) => Promise<string>;
+};
+//# sourceMappingURL=migration.d.ts.map

package/dist/tools/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/tools/migration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;EAqB/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAoClE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;oBAkCF,cAAc;CAUrC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.40-alpha.0",
+  "version": "0.13.41-alpha.0",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,8 +33,8 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@mastra/mcp": "^0.14.2",
-    "@mastra/core": "0.24.1-alpha.0"
+    "@mastra/core": "0.24.2-alpha.0",
+    "@mastra/mcp": "^0.14.3-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.5",
@@ -49,8 +49,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.58",
-    "@mastra/core": "0.24.1-alpha.0"
+    "@internal/lint": "0.0.59",
+    "@mastra/core": "0.24.2-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {