Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Add MCP tool annotations to smart_home example (#2777)

Bryan Thompson30a239637bf1
diff --git a/examples/smart_home/src/smart_home/hub.py b/examples/smart_home/src/smart_home/hub.py
index 862d12a05..09fd3dd84 100644
--- a/examples/smart_home/src/smart_home/hub.py
+++ b/examples/smart_home/src/smart_home/hub.py
@@ -1,3 +1,4 @@
+from mcp.types import ToolAnnotations
from phue2 import Bridge
from fastmcp import FastMCP
@@ -11,7 +12,7 @@ hub_mcp.mount(lights_mcp, prefix="hue")
# Add a status check for the hub
-@hub_mcp.tool
+@hub_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
def hub_status() -> str:
"""Checks the status of the main hub and connections."""
try:
diff --git a/examples/smart_home/src/smart_home/lights/server.py b/examples/smart_home/src/smart_home/lights/server.py
index aa559b68f..cbe615a51 100644
--- a/examples/smart_home/src/smart_home/lights/server.py
+++ b/examples/smart_home/src/smart_home/lights/server.py
@@ -7,6 +7,7 @@
from typing import Annotated, Any, Literal, TypedDict
+from mcp.types import ToolAnnotations
from phue2.exceptions import PhueException
from pydantic import Field
from typing_extensions import NotRequired
@@ -46,7 +47,7 @@ class HueAttributes(TypedDict, total=False):
lights_mcp = FastMCP("Hue Lights Service (phue2)")
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
def read_all_lights() -> list[str]:
"""Lists the names of all available Hue lights using phue2."""
if not (bridge := _get_bridge()):
@@ -62,7 +63,7 @@ def read_all_lights() -> list[str]:
# --- Tools ---
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
def toggle_light(light_name: str, state: bool) -> dict[str, Any]:
"""Turns a specific light on (true) or off (false) using phue2."""
if not (bridge := _get_bridge()):
@@ -79,7 +80,7 @@ def toggle_light(light_name: str, state: bool) -> dict[str, Any]:
return handle_phue_error(light_name, "toggle_light", e)
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
def set_brightness(light_name: str, brightness: int) -> dict[str, Any]:
"""Sets the brightness of a specific light (0-254) using phue2."""
if not (bridge := _get_bridge()):
@@ -103,7 +104,7 @@ def set_brightness(light_name: str, brightness: int) -> dict[str, Any]:
return handle_phue_error(light_name, "set_brightness", e)
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
def list_groups() -> list[str]:
"""Lists the names of all available Hue light groups."""
if not (bridge := _get_bridge()):
@@ -116,7 +117,7 @@ def list_groups() -> list[str]:
return [f"Error listing groups: {e}"]
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
def list_scenes() -> dict[str, list[str]] | list[str]:
"""Lists Hue scenes, grouped by the light group they belong to.
@@ -157,7 +158,7 @@ def list_scenes() -> dict[str, list[str]] | list[str]:
return [f"Error listing scenes by group: {e}"]
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
def activate_scene(group_name: str, scene_name: str) -> dict[str, Any]:
"""Activates a specific scene within a specified light group, verifying the scene belongs to the group."""
if not (bridge := _get_bridge()):
@@ -218,7 +219,7 @@ def activate_scene(group_name: str, scene_name: str) -> dict[str, Any]:
return handle_phue_error(f"{group_name}/{scene_name}", "activate_scene", e)
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
def set_light_attributes(light_name: str, attributes: HueAttributes) -> dict[str, Any]:
"""Sets multiple attributes (e.g., hue, sat, bri, ct, xy, transitiontime) for a specific light."""
if not (bridge := _get_bridge()):
@@ -245,7 +246,7 @@ def set_light_attributes(light_name: str, attributes: HueAttributes) -> dict[str
return handle_phue_error(light_name, "set_light_attributes", e)
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, openWorldHint=True))
def set_group_attributes(group_name: str, attributes: HueAttributes) -> dict[str, Any]:
"""Sets multiple attributes for all lights within a specific group."""
if not (bridge := _get_bridge()):
@@ -270,7 +271,7 @@ def set_group_attributes(group_name: str, attributes: HueAttributes) -> dict[str
return handle_phue_error(group_name, "set_group_attributes", e)
-@lights_mcp.tool
+@lights_mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
def list_lights_by_group() -> dict[str, list[str]] | list[str]:
"""Lists Hue lights, grouped by the room/group they belong to.