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

@@ -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.

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."""