ha-mcp-dev 7.2.0.dev346__tar.gz → 7.2.0.dev347__tar.gz

{ha_mcp_dev-7.2.0.dev346/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.2.0.dev347}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.2.0.dev346
+Version: 7.2.0.dev347
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.2.0.dev346 → ha_mcp_dev-7.2.0.dev347}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.2.0.dev346"
+version = "7.2.0.dev347"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -133,7 +133,41 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 "tests/**/*" = ["E501", "B011"]
-"src/ha_mcp/tools/**" = ["C901"]
+# C901 ignores for unmigrated tools files (see #925).
+# Remove lines as files are migrated to class-based pattern.
+"src/ha_mcp/tools/backup.py" = ["C901"]
+"src/ha_mcp/tools/best_practice_checker.py" = ["C901"]
+"src/ha_mcp/tools/device_control.py" = ["C901"]
+"src/ha_mcp/tools/helpers.py" = ["C901"]
+"src/ha_mcp/tools/registry.py" = ["C901"]
+"src/ha_mcp/tools/smart_search.py" = ["C901"]
+"src/ha_mcp/tools/tools_addons.py" = ["C901"]
+"src/ha_mcp/tools/tools_areas.py" = ["C901"]
+"src/ha_mcp/tools/tools_blueprints.py" = ["C901"]
+"src/ha_mcp/tools/tools_calendar.py" = ["C901"]
+"src/ha_mcp/tools/tools_config_automations.py" = ["C901"]
+"src/ha_mcp/tools/tools_config_dashboards.py" = ["C901"]
+"src/ha_mcp/tools/tools_config_entry_flow.py" = ["C901"]
+"src/ha_mcp/tools/tools_config_helpers.py" = ["C901"]
+"src/ha_mcp/tools/tools_config_scripts.py" = ["C901"]
+"src/ha_mcp/tools/tools_entities.py" = ["C901"]
+"src/ha_mcp/tools/tools_filesystem.py" = ["C901"]
+"src/ha_mcp/tools/tools_groups.py" = ["C901"]
+"src/ha_mcp/tools/tools_hacs.py" = ["C901"]
+"src/ha_mcp/tools/tools_history.py" = ["C901"]
+"src/ha_mcp/tools/tools_integrations.py" = ["C901"]
+"src/ha_mcp/tools/tools_mcp_component.py" = ["C901"]
+"src/ha_mcp/tools/tools_registry.py" = ["C901"]
+"src/ha_mcp/tools/tools_resources.py" = ["C901"]
+"src/ha_mcp/tools/tools_search.py" = ["C901"]
+"src/ha_mcp/tools/tools_service.py" = ["C901"]
+"src/ha_mcp/tools/tools_services.py" = ["C901"]
+"src/ha_mcp/tools/tools_system.py" = ["C901"]
+"src/ha_mcp/tools/tools_todo.py" = ["C901"]
+"src/ha_mcp/tools/tools_traces.py" = ["C901"]
+"src/ha_mcp/tools/tools_updates.py" = ["C901"]
+"src/ha_mcp/tools/tools_utility.py" = ["C901"]
+"src/ha_mcp/tools/util_helpers.py" = ["C901"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{ha_mcp_dev-7.2.0.dev346 → ha_mcp_dev-7.2.0.dev347}/src/ha_mcp/tools/helpers.py

@@ -299,3 +299,22 @@ def log_tool_usage(func: Any) -> Any:
             )
 
     return wrapper
+
+
+def register_tool_methods(mcp: Any, instance: Any) -> None:
+    """Register all @tool-decorated methods from a class instance with the MCP server.
+
+    Discovers methods bearing a ``__fastmcp__`` attribute (set by the outermost
+    ``@tool`` decorator — must be listed above ``@log_tool_usage``) and registers
+    them via ``mcp.add_tool()``.
+    """
+    count = 0
+    for attr in dir(instance):
+        method = getattr(instance, attr)
+        if callable(method) and hasattr(method, "__fastmcp__"):
+            mcp.add_tool(method)
+            count += 1
+    if count == 0:
+        logger.warning(
+            f"No @tool-decorated methods found on {type(instance).__name__}"
+        )

{ha_mcp_dev-7.2.0.dev346 → ha_mcp_dev-7.2.0.dev347}/src/ha_mcp/tools/tools_camera.py

@@ -8,19 +8,61 @@ that returns images directly to the LLM for visual analysis.
 import logging
 from typing import Any
 
+from fastmcp.tools import tool
 from fastmcp.utilities.types import Image
 
-from .helpers import log_tool_usage
+from .helpers import log_tool_usage, register_tool_methods
 
 logger = logging.getLogger(__name__)
 
 
-def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
-    """Register Home Assistant camera tools."""
+_CONTENT_TYPE_MAP = {
+    "jpeg": "jpeg", "jpg": "jpeg", "png": "png", "gif": "gif",
+}
+
+
+def _detect_image_format(content_type: str) -> str:
+    """Detect image format from Content-Type header, defaulting to JPEG."""
+    for key, fmt in _CONTENT_TYPE_MAP.items():
+        if key in content_type:
+            return fmt
+    return "jpeg"
+
 
-    @mcp.tool(tags={"Camera"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Camera Image"})
+class CameraTools:
+    """Camera snapshot retrieval tools."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    @staticmethod
+    def _check_response(response: Any, entity_id: str) -> None:
+        """Validate camera proxy HTTP response status and content, raising on errors."""
+        if response.status_code == 401:
+            raise PermissionError("Invalid authentication token for camera access")
+        if response.status_code == 404:
+            raise ValueError(
+                f"Camera entity not found: {entity_id}. "
+                "Use ha_search_entities() to find available cameras."
+            )
+        if response.status_code >= 400:
+            raise RuntimeError(
+                f"Failed to retrieve camera image: HTTP {response.status_code}"
+            )
+        if not response.content:
+            raise RuntimeError(
+                f"Camera {entity_id} returned empty image data. "
+                "The camera may be offline or unavailable."
+            )
+
+    @tool(
+        name="ha_get_camera_image",
+        tags={"Camera"},
+        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Camera Image"},
+    )
     @log_tool_usage
     async def ha_get_camera_image(
+        self,
         entity_id: str,
         width: int | None = None,
         height: int | None = None,
@@ -64,14 +106,12 @@ def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         - camera.turn_on/turn_off: Control camera power
         - camera.enable_motion_detection: Enable motion detection
         """
-        # Validate entity_id format
         if not entity_id or "." not in entity_id:
             raise ValueError(
                 f"Invalid entity_id format: {entity_id}. "
                 "Expected format: camera.entity_name"
             )
 
-        # Validate domain is camera
         domain = entity_id.split(".")[0]
         if domain != "camera":
             raise ValueError(
@@ -90,54 +130,19 @@ def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             params["height"] = str(height)
 
         try:
-            # Use the client's httpx_client directly for binary image data
-            response = await client.httpx_client.get(endpoint, params=params or None)
-
-            # Handle authentication errors
-            if response.status_code == 401:
-                raise PermissionError("Invalid authentication token for camera access")
-
-            # Handle not found errors
-            if response.status_code == 404:
-                raise ValueError(
-                    f"Camera entity not found: {entity_id}. "
-                    "Use ha_search_entities() to find available cameras."
-                )
-
-            # Handle other HTTP errors
-            if response.status_code >= 400:
-                raise RuntimeError(
-                    f"Failed to retrieve camera image: HTTP {response.status_code}"
-                )
-
-            # Get the image bytes
-            image_data = response.content
-
-            if not image_data:
-                raise RuntimeError(
-                    f"Camera {entity_id} returned empty image data. "
-                    "The camera may be offline or unavailable."
-                )
-
-            # Determine MIME type from response headers or default to JPEG
+            response = await self._client.httpx_client.get(endpoint, params=params or None)
+            self._check_response(response, entity_id)
+
             content_type = response.headers.get("content-type", "image/jpeg")
-            if "jpeg" in content_type or "jpg" in content_type:
-                image_format = "jpeg"
-            elif "png" in content_type:
-                image_format = "png"
-            elif "gif" in content_type:
-                image_format = "gif"
-            else:
-                # Default to JPEG as Home Assistant camera proxy typically returns JPEG
-                image_format = "jpeg"
+            image_format = _detect_image_format(content_type)
 
             logger.info(
                 f"Retrieved camera image from {entity_id} "
-                f"({len(image_data)} bytes, format={image_format})"
+                f"({len(response.content)} bytes, format={image_format})"
             )
 
             # Return FastMCP Image object which automatically converts to MCP ImageContent
-            return Image(data=image_data, format=image_format)
+            return Image(data=response.content, format=image_format)
 
         except (PermissionError, ValueError, RuntimeError):
             raise
@@ -147,3 +152,8 @@ def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 f"Failed to retrieve camera image from {entity_id}: {str(e)}. "
                 "Ensure the camera is online and accessible."
             ) from e
+
+
+def register_camera_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant camera tools."""
+    register_tool_methods(mcp, CameraTools(client))

{ha_mcp_dev-7.2.0.dev346 → ha_mcp_dev-7.2.0.dev347}/src/ha_mcp/tools/tools_categories.py

@@ -12,27 +12,34 @@ import logging
 from typing import Annotated, Any
 
 from fastmcp.exceptions import ToolError
+from fastmcp.tools import tool
 from pydantic import Field
 
 from ..errors import ErrorCode, create_error_response
-from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
+from .helpers import (
+    exception_to_structured_error,
+    log_tool_usage,
+    raise_tool_error,
+    register_tool_methods,
+)
 
 logger = logging.getLogger(__name__)
 
 
-def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
-    """Register Home Assistant category management tools."""
+class CategoryTools:
+    """Category management tools for Home Assistant."""
 
-    @mcp.tool(
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    @tool(
+        name="ha_config_get_category",
         tags={"Labels & Categories"},
-        annotations={
-            "idempotentHint": True,
-            "readOnlyHint": True,
-            "title": "Get Category"
-        }
+        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Category"},
     )
     @log_tool_usage
     async def ha_config_get_category(
+        self,
         scope: Annotated[
             str,
             Field(
@@ -74,7 +81,7 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "scope": scope,
             }
 
-            result = await client.send_websocket_message(message)
+            result = await self._client.send_websocket_message(message)
 
             if not result.get("success"):
                 raise_tool_error(
@@ -87,7 +94,6 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
             categories = result.get("result", [])
 
-            # List mode - return all categories
             if category_id is None:
                 return {
                     "success": True,
@@ -97,7 +103,6 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "message": f"Found {len(categories)} category(ies) for scope '{scope}'",
                 }
 
-            # Get mode - find specific category
             category = next(
                 (cat for cat in categories if cat.get("category_id") == category_id),
                 None,
@@ -142,15 +147,14 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 ],
             )
 
-    @mcp.tool(
+    @tool(
+        name="ha_config_set_category",
         tags={"Labels & Categories"},
-        annotations={
-            "destructiveHint": True,
-            "title": "Create or Update Category"
-        }
+        annotations={"destructiveHint": True, "title": "Create or Update Category"},
     )
     @log_tool_usage
     async def ha_config_set_category(
+        self,
         name: Annotated[str, Field(description="Display name for the category")],
         scope: Annotated[
             str,
@@ -190,7 +194,6 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         After creating a category, use ha_set_entity(categories={"automation": "category_id"}) to assign it.
         """
         try:
-            # Determine if this is a create or update
             action = "update" if category_id else "create"
 
             message: dict[str, Any] = {
@@ -202,11 +205,10 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             if action == "update":
                 message["category_id"] = category_id
 
-            # Add optional fields only if they are explicitly provided (not None)
             if icon is not None:
                 message["icon"] = icon
 
-            result = await client.send_websocket_message(message)
+            result = await self._client.send_websocket_message(message)
 
             if result.get("success"):
                 category_data = result.get("result", {})
@@ -245,16 +247,14 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 ],
             )
 
-    @mcp.tool(
+    @tool(
+        name="ha_config_remove_category",
         tags={"Labels & Categories"},
-        annotations={
-            "destructiveHint": True,
-            "idempotentHint": True,
-            "title": "Remove Category"
-        }
+        annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Category"},
     )
     @log_tool_usage
     async def ha_config_remove_category(
+        self,
         scope: Annotated[
             str,
             Field(
@@ -288,7 +288,7 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "category_id": category_id,
             }
 
-            result = await client.send_websocket_message(message)
+            result = await self._client.send_websocket_message(message)
 
             if result.get("success"):
                 return {
@@ -318,3 +318,8 @@ def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "Verify the category_id exists using ha_config_get_category()",
                 ],
             )
+
+
+def register_category_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant category management tools."""
+    register_tool_methods(mcp, CategoryTools(client))

{ha_mcp_dev-7.2.0.dev346 → ha_mcp_dev-7.2.0.dev347}/src/ha_mcp/tools/tools_labels.py

@@ -9,20 +9,34 @@ import logging
 from typing import Annotated, Any
 
 from fastmcp.exceptions import ToolError
+from fastmcp.tools import tool
 from pydantic import Field
 
 from ..errors import ErrorCode, create_error_response
-from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
+from .helpers import (
+    exception_to_structured_error,
+    log_tool_usage,
+    raise_tool_error,
+    register_tool_methods,
+)
 
 logger = logging.getLogger(__name__)
 
 
-def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
-    """Register Home Assistant label management tools."""
+class LabelTools:
+    """Label management tools for Home Assistant."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
 
-    @mcp.tool(tags={"Labels & Categories"}, annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Label"})
+    @tool(
+        name="ha_config_get_label",
+        tags={"Labels & Categories"},
+        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get Label"},
+    )
     @log_tool_usage
     async def ha_config_get_label(
+        self,
         label_id: Annotated[
             str | None,
             Field(
@@ -53,7 +67,7 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "type": "config/label_registry/list",
             }
 
-            result = await client.send_websocket_message(message)
+            result = await self._client.send_websocket_message(message)
 
             if not result.get("success"):
                 raise_tool_error(create_error_response(
@@ -64,7 +78,6 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
             labels = result.get("result", [])
 
-            # List mode - return all labels
             if label_id is None:
                 return {
                     "success": True,
@@ -73,7 +86,6 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "message": f"Found {len(labels)} label(s)",
                 }
 
-            # Get mode - find specific label
             label = next(
                 (lbl for lbl in labels if lbl.get("label_id") == label_id), None
             )
@@ -103,9 +115,14 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "Verify WebSocket connection is active",
             ])
 
-    @mcp.tool(tags={"Labels & Categories"}, annotations={"destructiveHint": True, "title": "Create or Update Label"})
+    @tool(
+        name="ha_config_set_label",
+        tags={"Labels & Categories"},
+        annotations={"destructiveHint": True, "title": "Create or Update Label"},
+    )
     @log_tool_usage
     async def ha_config_set_label(
+        self,
         name: Annotated[str, Field(description="Display name for the label")],
         label_id: Annotated[
             str | None,
@@ -154,7 +171,6 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         After creating a label, use ha_set_entity(labels=["label_id"]) to assign it to entities.
         """
         try:
-            # Determine if this is a create or update
             action = "update" if label_id else "create"
 
             message: dict[str, Any] = {
@@ -167,7 +183,6 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 # Note: name is always provided as it's a required parameter
                 # The validation of at least one field is satisfied by name being required
 
-            # Add optional fields only if they are explicitly provided (not None)
             if color is not None:
                 message["color"] = color
             if icon is not None:
@@ -175,7 +190,7 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             if description is not None:
                 message["description"] = description
 
-            result = await client.send_websocket_message(message)
+            result = await self._client.send_websocket_message(message)
 
             if result.get("success"):
                 label_data = result.get("result", {})
@@ -203,9 +218,14 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "For updates, verify the label_id exists using ha_config_get_label()",
             ])
 
-    @mcp.tool(tags={"Labels & Categories"}, annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Label"})
+    @tool(
+        name="ha_config_remove_label",
+        tags={"Labels & Categories"},
+        annotations={"destructiveHint": True, "idempotentHint": True, "title": "Remove Label"},
+    )
     @log_tool_usage
     async def ha_config_remove_label(
+        self,
         label_id: Annotated[
             str,
             Field(description="ID of the label to delete"),
@@ -231,7 +251,7 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "label_id": label_id,
             }
 
-            result = await client.send_websocket_message(message)
+            result = await self._client.send_websocket_message(message)
 
             if result.get("success"):
                 return {
@@ -255,3 +275,7 @@ def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 "Verify the label_id exists using ha_config_get_label()",
             ])
 
+
+def register_label_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register Home Assistant label management tools."""
+    register_tool_methods(mcp, LabelTools(client))