From 83702a41f8acafd82a88934b01641d18391508c3 Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Sat, 18 Jul 2026 20:57:36 -0400
Subject: [PATCH] Document icon theme support (#4537)

* Document icon theme support and add round-trip tests

MCP SDK v2 added a `theme` field to `Icon` (light/dark), letting a
server ship complementary icon variants for clients that render in
different UI themes. Document the field on the icons page and cover
it with round-trip tests through the server/client protocol.

* docs: add 4.0.0 version badge to Theme Variants section
---
 docs/servers/icons.mdx     | 42 +++++++++++++++++++++++++++++++++++++-
 tests/server/test_icons.py | 28 ++++++++++++++++++++++++-
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/docs/servers/icons.mdx b/docs/servers/icons.mdx
index 589e054f2..6db88ba9f 100644
--- a/docs/servers/icons.mdx
+++ b/docs/servers/icons.mdx
@@ -12,7 +12,7 @@ Icons provide visual representations for your MCP servers and components, helpin
 
 ## Icon Format
 
-Icons use the standard MCP Icon type from the MCP protocol specification. Each icon specifies a source URL or data URI, and optionally includes MIME type and size information.
+Icons use the standard MCP Icon type from the MCP protocol specification. Each icon specifies a source URL or data URI, and optionally includes MIME type, size, and theme information.
 
 ```python
 from fastmcp.types import Icon
@@ -29,6 +29,7 @@ The fields serve different purposes:
 - **src**: URL or data URI pointing to the icon image
 - **mime_type** (optional): MIME type of the image (e.g., "image/png", "image/svg+xml")
 - **sizes** (optional): Array of size descriptors (e.g., ["48x48"], ["any"])
+- **theme** (optional): The UI theme the icon is designed for, `"light"` or `"dark"`
 
 ## Server Icons
 
@@ -110,6 +111,45 @@ def analyze_code(code: str):
     return f"Please analyze this code:\n\n{code}"
 ```
 
+## Theme Variants
+
+<VersionBadge version="4.0.0" />
+
+MCP clients like VS Code and GitHub Desktop render their own interface in either a light or dark theme, and an icon designed for one can be hard to see against the other, such as a dark logo that disappears into a dark sidebar. The `theme` field on `Icon` tells a client which UI theme an icon is designed for, so the client can display the version that stays visible.
+
+Supply two icons with complementary `theme` values and the client picks the one that matches its current appearance:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.types import Icon
+
+mcp = FastMCP(
+    name="WeatherService",
+    icons=[
+        Icon(src="https://weather.example.com/icon-light.png", theme="light"),
+        Icon(src="https://weather.example.com/icon-dark.png", theme="dark"),
+    ],
+)
+```
+
+The same field works on tools, resources, resource templates, and prompts:
+
+```python
+from fastmcp.types import Icon
+
+@mcp.tool(
+    icons=[
+        Icon(src="https://example.com/calculator-light.png", theme="light"),
+        Icon(src="https://example.com/calculator-dark.png", theme="dark"),
+    ]
+)
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+```
+
+Omitting `theme` means the icon is assumed suitable for any theme. That's the right choice for a single icon with enough contrast to read clearly against both light and dark backgrounds.
+
 ## Using Data URIs
 
 For small icons or when you want to embed the icon directly without external dependencies, use data URIs. This approach eliminates the need for hosting and ensures the icon is always available.
diff --git a/tests/server/test_icons.py b/tests/server/test_icons.py
index 9fba37b9b..2ee675307 100644
--- a/tests/server/test_icons.py
+++ b/tests/server/test_icons.py
@@ -1,6 +1,7 @@
 """Tests for icon support across all MCP object types."""
 
-from mcp_types import Icon
+import pytest
+from mcp_types import Icon, IconTheme
 
 from fastmcp import Client, FastMCP
 from fastmcp.prompts import Message, Prompt
@@ -325,6 +326,31 @@ class TestIconTypes:
             assert server_info.icons[0].sizes is None
 
 
+class TestIconTheme:
+    """Test icon theme support."""
+
+    @pytest.mark.parametrize("theme", ["light", "dark"])
+    async def test_icon_with_theme_round_trips(self, theme: IconTheme):
+        """Test that an icon's theme survives a client round-trip."""
+        icons = [Icon(src="https://example.com/icon.png", theme=theme)]
+
+        mcp = FastMCP("TestServer", icons=icons)
+
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.server_info
+            assert server_info.icons[0].theme == theme
+
+    async def test_icon_without_theme_is_none(self):
+        """Test that an icon with no theme specified round-trips as None."""
+        icons = [Icon(src="https://example.com/icon.png")]
+
+        mcp = FastMCP("TestServer", icons=icons)
+
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.server_info
+            assert server_info.icons[0].theme is None
+
+
 class TestIconImport:
     """Test that Icon must be imported from mcp_types."""