feature: Add Azure.Mcp.Tools.Speech tool azmcp_speech_tts_synthesize #902

ms-feizhao · 2025-10-21T10:18:24Z

What does this PR do?

Add Azure.Mcp.Tools.Speech tool azmcp_speech_tts_synthesize

https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech

GitHub issue number?

#852

Pre-merge Checklist

Copilot

Pull Request Overview

This PR introduces a new Azure MCP tool azmcp_speech_tts_synthesize that enables text-to-speech synthesis using Azure AI Services Speech. The tool converts text to audio files with configurable language, voice, format, and custom voice model support.

Key Changes

Added TTS synthesis command with comprehensive parameter validation
Implemented streaming-based audio synthesis for efficient memory management
Added extensive unit and live tests for various synthesis scenarios

Reviewed Changes

Copilot reviewed 14 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/Azure.Mcp.Tools.Speech/src/Commands/Tts/TtsSynthesizeCommand.cs	New command implementation for TTS synthesis with validation and error handling
tools/Azure.Mcp.Tools.Speech/src/Services/SpeechService.cs	Core TTS synthesis logic with streaming support and error handling
tools/Azure.Mcp.Tools.Speech/src/Services/ISpeechService.cs	Interface extension for TTS synthesis method
tools/Azure.Mcp.Tools.Speech/src/Options/Tts/TtsSynthesizeOptions.cs	Options class for TTS synthesis parameters
tools/Azure.Mcp.Tools.Speech/src/Options/SpeechOptionDefinitions.cs	Command-line option definitions for TTS parameters
tools/Azure.Mcp.Tools.Speech/src/Models/SynthesisResult.cs	Result model for TTS synthesis output
tools/Azure.Mcp.Tools.Speech/src/Commands/SpeechJsonContext.cs	JSON serialization context updates
tools/Azure.Mcp.Tools.Speech/src/SpeechSetup.cs	Registration of TTS command group
tools/Azure.Mcp.Tools.Speech/tests/Azure.Mcp.Tools.Speech.UnitTests/Tts/TtsSynthesizeCommandTests.cs	Comprehensive unit tests for TTS command
tools/Azure.Mcp.Tools.Speech/tests/Azure.Mcp.Tools.Speech.LiveTests/SpeechCommandTests.cs	Live integration tests for TTS functionality
servers/Azure.Mcp.Server/docs/azmcp-commands.md	Documentation for TTS command usage
servers/Azure.Mcp.Server/docs/e2eTestPrompts.md	E2E test prompts for TTS scenarios
servers/Azure.Mcp.Server/README.md	README updates describing TTS capabilities
eng/tools/ToolDescriptionEvaluator/prompts.json	Test prompts for tool description evaluation

tools/Azure.Mcp.Tools.Speech/src/Services/SpeechService.cs

tools/Azure.Mcp.Tools.Speech/tests/Azure.Mcp.Tools.Speech.LiveTests/SpeechCommandTests.cs

joshfree · 2025-10-21T16:08:55Z

Do Not Merge - we're holding new features until after October 28th when the branch opens for new 2.0-beta.x work.

dilin-MS2 · 2025-10-21T16:39:30Z

Hi @joshfree , this PR is for Ignite. We can hold it until October 28th to merge it. But it would be the best if you can start reviewing the PR so we can merge it after Oct 28th. Thanks!

ms-feizhao · 2025-10-24T07:05:25Z

Hi @joshfree @alzimmermsft , could you help review the PR? we'd like to publish before Ignite if possible. Thanks!

ms-feizhao · 2025-11-04T11:06:28Z

Hi @joshfree , the PR is updated to fix conflicts, could you help review?

Thanks.

ms-feizhao · 2025-11-06T09:40:51Z

Hi @joshfree @alzimmermsft , could you help review the PR? Thanks.

joshfree · 2025-11-07T02:21:54Z

@dilin-MS2 please review your team mates PR. Thanks

joshfree · 2025-11-07T02:23:17Z

This PR doesn't look like it is rebased from main correctly. It shows many unrelated edits for AI Foundry tools

joshfree

Left some comments.

Please double check you're not including unrelated edits

joshfree · 2025-11-07T02:24:27Z

eng/tools/ToolDescriptionEvaluator/tools.json

+      ]
+    },
+    {
+      "name": "list",


Why is this included in the PR if you're adding 1 new speech tool?

this is changed by the ToolDescriptionEvaluator tool after my local running.

joshfree · 2025-11-07T02:26:36Z

servers/Azure.Mcp.Server/docs/azmcp-commands.md

+```bash
+# Synthesize speech from text and save to an audio file using Azure AI Services Speech
+# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ✅ LocalRequired
+azmcp speech tts synthesize --endpoint <endpoint> \


@xiangyan99 please review. This doesn't look like the file was generated, it instead looks hand-edited and I'm assuming this will break the next time the file is generated?

These are auto-generated.

joshfree · 2025-11-07T02:27:56Z

tools/Azure.Mcp.Tools.Speech/src/Commands/Tts/TtsSynthesizeCommand.cs

+        """
+        Convert text to speech using Azure AI Services Speech. This command takes text input and generates an audio file using advanced neural text-to-speech capabilities.
+        You must provide an Azure AI Services endpoint (e.g., https://your-service.cognitiveservices.azure.com/), the text to convert, and an output file path.
+        Optional parameters include language specification (default: en-US), voice selection, audio output format (default: Riff24Khz16BitMonoPcm), and custom voice endpoint ID.


Have you tested with other tool descriptions which teach the LLM the rest of the optional parameters? Eg more locale examples more encoding examples

yes, tested with different locales and formats.

alzimmermsft · 2025-11-07T16:28:18Z

tools/Azure.Mcp.Tools.Speech/src/Commands/Tts/TtsSynthesizeCommand.cs

+                var supportedExtensions = new HashSet<string>
+                {
+                    ".wav", ".mp3", ".ogg", ".raw"
+                };


Turn this into a static field

alzimmermsft · 2025-11-07T16:29:20Z

tools/Azure.Mcp.Tools.Speech/src/Commands/Tts/TtsSynthesizeCommand.cs

+            // Validate output file path
+            if (string.IsNullOrWhiteSpace(fileValue))
+            {
+                commandResult.AddError("Output file path cannot be empty.");


Should there also be a check for the file already existing? I don't want to support the ability to overwrite local files at this time.

Also based on destructive=false in metadata overwriting a local file would require that being true. Which again, I don't really want to support yet.

alzimmermsft · 2025-11-07T16:31:10Z

tools/Azure.Mcp.Tools.Speech/src/Commands/Tts/TtsSynthesizeCommand.cs

+            context.Response.Status = HttpStatusCode.OK;
+            context.Response.Message = "Speech synthesis completed successfully.";
+            context.Response.Results = ResponseResult.Create(
+                new TtsSynthesizeCommandResult(result),


Suggested change

new TtsSynthesizeCommandResult(result),

new(result),

alzimmermsft · 2025-11-07T16:36:54Z

tools/Azure.Mcp.Tools.Speech/tests/Azure.Mcp.Tools.Speech.LiveTests/SpeechCommandTests.cs

+            // Parse and validate the JSON result
+            var jsonResult = JsonDocument.Parse(resultText);
+            var resultObject = jsonResult.RootElement;
+            Assert.True(resultObject.TryGetProperty("result", out var resultProperty));


When requiring a JSON property use AssertProperty

Suggested change

Assert.True(resultObject.TryGetProperty("result", out var resultProperty));

var resultProperty = resultObject.AssertProperty("result");

This will provide better debugging information if property retrieval fails.

alzimmermsft · 2025-11-07T16:37:54Z

...ure.Mcp.Tools.Speech/tests/Azure.Mcp.Tools.Speech.UnitTests/Tts/TtsSynthesizeCommandTests.cs

+    [Fact]
+    public void Constructor_WithValidLogger_ShouldCreateInstance()
+    {
+        var command = new TtsSynthesizeCommand(_logger);
+        Assert.NotNull(command);
+        Assert.Equal("synthesize", command.Name);
+    }
+
+    [Fact]
+    public void Properties_ShouldHaveExpectedValues()
+    {
+        Assert.Equal("synthesize", _command.Name);
+        Assert.Equal("Synthesize Speech from Text", _command.Title);
+        Assert.NotEmpty(_command.Description);
+        Assert.False(_command.Metadata.Destructive);
+        Assert.True(_command.Metadata.Idempotent);
+        Assert.False(_command.Metadata.OpenWorld);
+        Assert.False(_command.Metadata.ReadOnly);
+        Assert.True(_command.Metadata.LocalRequired);
+        Assert.False(_command.Metadata.Secret);
+    }


Remove these tests, they aren't very useful and will make maintenance more painful.

ms-feizhao requested a review from a team as a code owner October 21, 2025 10:18

Copilot AI review requested due to automatic review settings October 21, 2025 10:18

ms-feizhao requested a review from a team as a code owner October 21, 2025 10:18

ms-feizhao requested review from chidozieononiwu, conniey, g2vinay, hallipr, jairmyree, joshfree and msalaman October 21, 2025 10:18

github-project-automation bot added this to Azure MCP Server Oct 21, 2025

github-project-automation bot moved this to Untriaged in Azure MCP Server Oct 21, 2025

Copilot AI reviewed Oct 21, 2025

View reviewed changes

tools/Azure.Mcp.Tools.Speech/src/Services/SpeechService.cs Outdated Show resolved Hide resolved

tools/Azure.Mcp.Tools.Speech/tests/Azure.Mcp.Tools.Speech.LiveTests/SpeechCommandTests.cs Show resolved Hide resolved

joshfree assigned ms-feizhao Oct 21, 2025

joshfree added server-Azure.Mcp Azure.Mcp.Server tools-Speech Do Not Merge Do Not Merge / WIP PRs labels Oct 21, 2025

joshfree moved this from Untriaged to In Progress in Azure MCP Server Oct 21, 2025

joshfree added this to the 2025-11 milestone Oct 21, 2025

joshfree removed the Do Not Merge Do Not Merge / WIP PRs label Oct 30, 2025

ms-feizhao force-pushed the feizhao/tts_mcp branch from 3284bfd to 8dcf2e1 Compare November 4, 2025 07:48

ms-feizhao requested a review from a team as a code owner November 4, 2025 07:48

ms-feizhao enabled auto-merge (squash) November 5, 2025 02:58

ms-feizhao added 3 commits November 6, 2025 14:54

initial runnable version

ad23692

fix and add live tests

905e826

update parameter name

d8d7f30

ms-feizhao added 7 commits November 6, 2025 14:54

update response

b9e9664

update prompts and tool description evaluator

58ab858

fix comment in live tests

59a4c72

fix dotnet format errors

14acd55

fix command id

2106605

fix azmcp-commands.md

360f1b8

refactor tts mcp tool

e2fd2ea

ms-feizhao force-pushed the feizhao/tts_mcp branch from d7a144f to e2fd2ea Compare November 6, 2025 08:31

fix format

108cae6

joshfree reviewed Nov 7, 2025

View reviewed changes

dilin-MS2 approved these changes Nov 7, 2025

View reviewed changes

alzimmermsft reviewed Nov 7, 2025

View reviewed changes

	Assert.True(resultObject.TryGetProperty("result", out var resultProperty));
	var resultProperty = resultObject.AssertProperty("result");

feature: Add Azure.Mcp.Tools.Speech tool azmcp_speech_tts_synthesize #902

Are you sure you want to change the base?

feature: Add Azure.Mcp.Tools.Speech tool azmcp_speech_tts_synthesize #902

Uh oh!

Conversation

ms-feizhao commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

GitHub issue number?

Pre-merge Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

joshfree commented Oct 21, 2025

Uh oh!

dilin-MS2 commented Oct 21, 2025

Uh oh!

ms-feizhao commented Oct 24, 2025

Uh oh!

ms-feizhao commented Nov 4, 2025

Uh oh!

ms-feizhao commented Nov 6, 2025

Uh oh!

joshfree commented Nov 7, 2025

Uh oh!

joshfree commented Nov 7, 2025

Uh oh!

joshfree left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ms-feizhao commented Oct 21, 2025 •

edited

Loading