Added Audio to FastMCP #1130

dragonier23 · 2025-07-12T07:50:52Z

Motivation and Context

Adding Audio in FastMCP that can be used to send audio content back. Related to Issue Closes: #952

How Has This Been Tested?

Breaking Changes

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

ochafik

Thanks @dragonier23 !

Looks good / in line w/ Image support! Suggesting some more tests before we can merge :-)

ochafik · 2025-08-05T15:21:57Z

tests/server/fastmcp/test_server.py

+            content = result.content[0]
+            assert isinstance(content, AudioContent)
+            assert content.type == "audio"
+            assert content.mimeType == "audio/wav"


Could you also add something to exercice the suffix-based mime type detection?

I just added a test to test the mimetypes, do let me know if this is what you are looking for!

Kludex · 2025-08-09T19:10:36Z

tests/server/fastmcp/test_server.py

+    @pytest.mark.anyio
+    async def test_tool_mixed_list_with_audio(self, tmp_path: Path):
+        """Test that lists containing Audio objects and other types are handled
+        correctly"""
+        # Create a test audio
+        audio_path = tmp_path / "test.wav"
+        audio_path.write_bytes(b"test audio data")
+
+        def mixed_list_fn() -> list:
+            return [
+                "text message",
+                Audio(audio_path),
+                {"key": "value"},
+                TextContent(type="text", text="direct content"),
+            ]
+
+        mcp = FastMCP()
+        mcp.add_tool(mixed_list_fn)
+        async with client_session(mcp._mcp_server) as client:
+            result = await client.call_tool("mixed_list_fn", {})
+            assert len(result.content) == 4
+            # Check text conversion
+            content1 = result.content[0]
+            assert isinstance(content1, TextContent)
+            assert content1.text == "text message"
+            # Check audio conversion
+            content2 = result.content[1]
+            assert isinstance(content2, AudioContent)
+            assert content2.mimeType == "audio/wav"
+            assert base64.b64decode(content2.data) == b"test audio data"
+            # Check dict conversion
+            content3 = result.content[2]
+            assert isinstance(content3, TextContent)


Remove this test and add Audio on the above please.

Kludex · 2025-08-09T19:10:58Z

tests/server/fastmcp/test_server.py

+        test_cases = [
+            ("test.wav", "audio/wav"),
+            ("test.mp3", "audio/mpeg"),
+            ("test.ogg", "audio/ogg"),
+            ("test.flac", "audio/flac"),
+            ("test.aac", "audio/aac"),
+            ("test.m4a", "audio/mp4"),
+            ("test.unknown", "application/octet-stream"),  # Unknown extension fallback
+        ]


Use pytest.mark.parametrize, please.

Kludex · 2025-08-09T19:11:48Z

src/mcp/server/fastmcp/utilities/types.py

+    def __init__(
+        self,
+        path: str | Path | None = None,
+        data: bytes | None = None,
+        format: str | None = None,
+    ):


Let's use @typing.override.

I would like to get some clarity as to what we are tying to override, given the audio class dosent inherit from any class at the moment

Kludex · 2025-08-09T19:12:40Z

src/mcp/server/fastmcp/utilities/types.py

+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")


I think you can do bool(path) ^ bool(data), and have a meaningful message: "Either path or data can be provided".

thanks for this suggestion! should i also make these changes to the Image class?

If you're up for it, please feel free to send a tiny follow up PR w/ both changes :-)

ochafik

Thanks again!

ochafik · 2025-08-22T10:36:46Z

src/mcp/server/fastmcp/utilities/types.py

+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")


If you're up for it, please feel free to send a tiny follow up PR w/ both changes :-)

* Add regression test for stateless request memory cleanup (modelcontextprotocol#1140) * Implement RFC9728 - Support WWW-Authenticate header by MCP client (modelcontextprotocol#1071) * Add streamable HTTP starlette example to Python SDK docs (modelcontextprotocol#1111) * fix markdown error in README in main (modelcontextprotocol#1147) * README - replace code snippets with examples - add lowlevel to snippets (modelcontextprotocol#1150) * README - replace code snippets with examples - streamable http (modelcontextprotocol#1155) * chore: don't allow users to create issues outside the templates (modelcontextprotocol#1163) * Tests(cli): Add coverage for helper functions (modelcontextprotocol#635) * Docs: Update CallToolResult parsing in README (modelcontextprotocol#812) Co-authored-by: Felix Weinberger <[email protected]> * docs: add pre-commit install guide on CONTRIBUTING.md (modelcontextprotocol#995) Co-authored-by: Felix Weinberger <[email protected]> * fix flaky fix-test_streamablehttp_client_resumption test (modelcontextprotocol#1166) * README - replace code snippets with examples -- auth examples (modelcontextprotocol#1164) * Support falling back to OIDC metadata for auth (modelcontextprotocol#1061) * Add CODEOWNERS file for sdk (modelcontextprotocol#1169) * fix flaky test test_88_random_error (modelcontextprotocol#1171) * Make sure `RequestId` is not coerced as `int` (modelcontextprotocol#1178) * Fix: Replace threading.Lock with anyio.Lock for Ray deployment compatibility (modelcontextprotocol#1151) * fix: fix OAuth flow request object handling (modelcontextprotocol#1174) * update codeowners group (modelcontextprotocol#1191) * fix: perform auth server metadata discovery fallbacks on any 4xx (modelcontextprotocol#1193) * server: skip duplicate response on CancelledError (modelcontextprotocol#1153) Co-authored-by: ihrpr <[email protected]> * Unpack settings in FastMCP (modelcontextprotocol#1198) * chore: Remove unused prompt_manager.py file (modelcontextprotocol#1229) Co-authored-by: Tapan Chugh <[email protected]> * Improved supported for ProtectedResourceMetadata (modelcontextprotocol#1235) Co-authored-by: Paul Carleton <[email protected]> * chore: Remove unused variable notification_options (modelcontextprotocol#1238) * Improve README around the Context object (modelcontextprotocol#1203) * fix: allow to pass `list[str]` to `token_endpoint_auth_signing_alg_values_supported` (modelcontextprotocol#1226) * Remove strict validation on `response_modes_supported` member of `OAuthMetadata` (modelcontextprotocol#1243) * Add pyright strict mode on the whole project (modelcontextprotocol#1254) * Consistent casing for default headers Accept and Content-Type (modelcontextprotocol#1263) * Update dependencies and fix type issues (modelcontextprotocol#1268) Co-authored-by: Marcelo Trylesinski <[email protected]> * fix: prevent async generator cleanup errors in StreamableHTTP transport (modelcontextprotocol#1271) Co-authored-by: David Soria Parra <[email protected]> * chore: uncomment .idea/ in .gitignore (modelcontextprotocol#1287) Co-authored-by: Claude <[email protected]> * docs: clarify streamable_http_path configuration when mounting servers (modelcontextprotocol#1172) * feat: Add CORS configuration for browser-based MCP clients (modelcontextprotocol#1059) Co-authored-by: Marcelo Trylesinski <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> * Added Audio to FastMCP (modelcontextprotocol#1130) * fix: avoid uncessary retries in OAuth authenticated requests (modelcontextprotocol#1206) Co-authored-by: Felix Weinberger <[email protected]> * Add PATHEXT to default STDIO env vars in windows (modelcontextprotocol#1256) * fix: error too many values to unpack (expected 2) (modelcontextprotocol#1279) Signed-off-by: San Nguyen <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> * SDK Parity: Avoid Parsing Server Response for non-JsonRPCMessage Requests (modelcontextprotocol#1290) * types: Setting default value for method: Literal (modelcontextprotocol#1292) * changes structured temperature to not deadly (modelcontextprotocol#1328) * Update simple-resource example to use non-deprecated read_resource return type (modelcontextprotocol#1331) Co-authored-by: Claude <[email protected]> * docs: Update README to include link to API docs for modelcontextprotocol#1329 (modelcontextprotocol#1330) * Allow ping requests before initialization (modelcontextprotocol#1312) * Python lint: Ruff rules for pylint and code complexity (modelcontextprotocol#525) * Fix context injection for resources and prompts (modelcontextprotocol#1336) * fix(fastmcp): propagate mimeType in resource template list (modelcontextprotocol#1186) Co-authored-by: Felix Weinberger <[email protected]> * fix: allow elicitations accepted without content (modelcontextprotocol#1285) Co-authored-by: Olivier Schiavo <[email protected]> * Use --frozen in pre-commit config (modelcontextprotocol#1375) * Return HTTP 403 for invalid Origin headers (modelcontextprotocol#1353) * Add test for ProtectedResourceMetadataParsing (modelcontextprotocol#1236) Co-authored-by: Paul Carleton <[email protected]> Co-authored-by: Marcelo Trylesinski <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> * Fastmcp logging progress example (modelcontextprotocol#1270) Co-authored-by: Felix Weinberger <[email protected]> * feat: add paginated list decorators for prompts, resources, and tools (modelcontextprotocol#1286) Co-authored-by: Claude <[email protected]> * Remove "unconditionally" from conditional description (modelcontextprotocol#1289) * Use streamable-http consistently in examples (modelcontextprotocol#1389) * feat: Add SDK support for SEP-1034 default values in elicitation schemas (modelcontextprotocol#1337) Co-authored-by: Tapan Chugh <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> * Implementation of SEP 973 - Additional metadata + icons support (modelcontextprotocol#1357) * Merge upstream/main with custom filtering --------- Signed-off-by: San Nguyen <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> Co-authored-by: yurikunash <[email protected]> Co-authored-by: Pamela Fox <[email protected]> Co-authored-by: Inna Harper <[email protected]> Co-authored-by: Marcelo Trylesinski <[email protected]> Co-authored-by: Ian Davenport <[email protected]> Co-authored-by: Dagang Wei <[email protected]> Co-authored-by: Felix Weinberger <[email protected]> Co-authored-by: Stanley Law <[email protected]> Co-authored-by: Luca Chang <[email protected]> Co-authored-by: leweng <[email protected]> Co-authored-by: Clare Liguori <[email protected]> Co-authored-by: lukacf <[email protected]> Co-authored-by: ihrpr <[email protected]> Co-authored-by: Tapan Chugh <[email protected]> Co-authored-by: Tapan Chugh <[email protected]> Co-authored-by: Yann Jouanin <[email protected]> Co-authored-by: Paul Carleton <[email protected]> Co-authored-by: Sreenath Somarajapuram <[email protected]> Co-authored-by: Omer Korner <[email protected]> Co-authored-by: joesavage-silabs <[email protected]> Co-authored-by: Gregory L <[email protected]> Co-authored-by: David Soria Parra <[email protected]> Co-authored-by: Moustapha Ebnou <[email protected]> Co-authored-by: Max Isbey <[email protected]> Co-authored-by: Claude <[email protected]> Co-authored-by: Jerome <[email protected]> Co-authored-by: xavier <[email protected]> Co-authored-by: keurcien <[email protected]> Co-authored-by: Tim Esler <[email protected]> Co-authored-by: San Nguyen <[email protected]> Co-authored-by: Justin Wang <[email protected]> Co-authored-by: jess <[email protected]> Co-authored-by: Peter Alexander <[email protected]> Co-authored-by: Reid Geyer <[email protected]> Co-authored-by: Eleftheria Stein-Kousathana <[email protected]> Co-authored-by: Christian Clauss <[email protected]> Co-authored-by: pchoudhury22 <[email protected]> Co-authored-by: owengo <[email protected]> Co-authored-by: Olivier Schiavo <[email protected]> Co-authored-by: Steve Billings <[email protected]> Co-authored-by: Mike Salvatore <[email protected]>

dragonier23 added 2 commits July 12, 2025 15:42

feat: Added Audio to FastMCP

992de10

Merge branch 'main' into fastMCPaudio

d35a23b

ochafik requested changes Aug 5, 2025

View reviewed changes

Merge branch 'main' into fastMCPaudio

b3ee109

dragonier23 requested review from a team and domdomegg August 9, 2025 09:08

fix: additional test for audio mimetype detection

40294d5

domdomegg requested review from ochafik and removed request for domdomegg August 9, 2025 17:40

Kludex reviewed Aug 9, 2025

View reviewed changes

dragonier23 added 4 commits August 16, 2025 21:26

fix: tests for audio, init

b905460

Merge branch 'main' into fastMCPaudio

b8f3561

fix: test

494f58a

fix: linting problems

1a043a4

ochafik approved these changes Aug 22, 2025

View reviewed changes

ochafik merged commit f4b2957 into modelcontextprotocol:main Aug 22, 2025
18 checks passed

Added Audio to FastMCP #1130

Added Audio to FastMCP #1130

Uh oh!

Conversation

dragonier23 commented Jul 12, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

ochafik 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!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants