fix(types): add mypy type checking and fix 47 type errors (#716)

* fix(types): add mypy type checking and fix 47 type errors

- Add mypy to pre-commit hook (runs on src/ and pyproject.toml changes)
- Fix python_version 3.11 → 3.13 in mypy config to match requires-python
- Add mypy_path = "src" for correct src-layout module resolution
- Add jq to mypy ignore_missing_imports (Windows ARM64 conditional dep)

Type fixes across 12 files:
- auth/provider.py: fix OAuth error literals (invalid_client→invalid_request,
  server_error→invalid_client); preserve None for optional PKCE code_challenge
- client/rest_client.py: type payload dict, add fallback return after retry loop
- tools/backup.py: assert ws_client not None after error checks
- tools/tools_areas.py: remove duplicate type annotations in if/else branches
- tools/tools_config_dashboards.py: fix Traversable variable conflict, use cast
  instead of assert for jq_result narrowing
- tools/tools_config_automations.py: cast Any return to dict[str, Any]
- tools/tools_traces.py: str() cast on return, type sort_key function
- tools/tools_service.py, tools_addons.py, tools_mcp_component.py, backup.py:
  add missing **kwargs: Any annotations
- server.py: cast Any-returning methods, fix list|dict return type
- __main__.py: replace Any with specific types (HomeAssistantOAuthProvider,
  HomeAssistantClient, Settings, Coroutine) via TYPE_CHECKING imports

* Update src/ha_mcp/tools/tools_mcp_component.py

Author: sergeykad

.pre-commit-config.yaml

@@ -11,6 +11,12 @@ repos:
       - id: uv-lock
   - repo: local
     hooks:
+      - id: mypy
+        name: mypy type check
+        entry: uv run mypy src/
+        language: system
+        pass_filenames: false
+        files: ^(src/|pyproject\.toml)
       - id: unit-tests
         name: unit tests
         entry: uv run pytest tests/src/unit/ -n auto -m "not slow" --tb=short -q

pyproject.toml

@@ -55,7 +55,8 @@ packages = { find = { where = ["src", "."], include = ["ha_mcp*", "tests"] } }
 ha_mcp = ["py.typed", "_pypi_marker", "resources/*.md", "resources/*.json", "resources/skills-vendor/**/*"]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.13"
+mypy_path = "src"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -71,6 +72,7 @@ explicit_package_bases = true
 [[tool.mypy.overrides]]
 module = [
     "fastmcp.*",
+    "jq",
 ]
 ignore_missing_imports = true
 

src/ha_mcp/__main__.py

@@ -13,7 +13,16 @@
 import stat  # noqa: E402
 import sys  # noqa: E402
 import threading  # noqa: E402
-from typing import Any  # noqa: E402
+from collections.abc import Coroutine  # noqa: E402
+from typing import TYPE_CHECKING, Any  # noqa: E402
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+    from ha_mcp.auth.provider import HomeAssistantOAuthProvider
+    from ha_mcp.client.rest_client import HomeAssistantClient
+    from ha_mcp.config import Settings
+    from ha_mcp.server import HomeAssistantSmartMCPServer
 
 logger = logging.getLogger(__name__)
 
@@ -25,12 +34,12 @@ class OAuthProxyClient:
     The proxy allows us to inject different credentials per-request based on OAuth token claims.
     """
 
-    def __init__(self, auth_provider):
+    def __init__(self, auth_provider: "HomeAssistantOAuthProvider") -> None:
         self._auth_provider = auth_provider
-        self._oauth_clients = {}
+        self._oauth_clients: dict[str, HomeAssistantClient] = {}
         self._lock = threading.Lock()
 
-    def _get_oauth_client(self):
+    def _get_oauth_client(self) -> "HomeAssistantClient":
         """Get the OAuth client for the current request context."""
         from fastmcp.server.dependencies import get_access_token
 
@@ -74,7 +83,7 @@ async def close(self) -> None:
         for client in clients:
             await client.close()
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: str) -> Any:
         """Forward all attribute access to the OAuth client."""
         client = self._get_oauth_client()
         return getattr(client, name)
@@ -217,7 +226,7 @@ def _handle_config_error(error: Exception) -> None:
     sys.exit(1)
 
 
-def _validate_standard_credentials(settings) -> None:
+def _validate_standard_credentials(settings: "Settings") -> None:
     """Exit with error if HA credentials are OAuth sentinels in standard (non-OAuth) mode."""
     from ha_mcp.config import OAUTH_MODE_TOKEN, OAUTH_MODE_URL
 
@@ -264,14 +273,12 @@ def _http_run_kwargs(transport: str, port: int, path: str) -> dict:
     }
 
 
-def _create_server():
+def _create_server() -> "HomeAssistantSmartMCPServer":
     """Create server instance (deferred to avoid import during smoke test)."""
     from pydantic import ValidationError
 
     try:
-        from ha_mcp.server import (
-            HomeAssistantSmartMCPServer,  # type: ignore[import-not-found]
-        )
+        from ha_mcp.server import HomeAssistantSmartMCPServer
 
         return HomeAssistantSmartMCPServer()
     except ValidationError as e:
@@ -280,18 +287,18 @@ def _create_server():
 
 
 # Lazy server creation - only create when needed
-_server = None
+_server: "HomeAssistantSmartMCPServer | None" = None
 
 
-def _get_mcp():
+def _get_mcp() -> "FastMCP":
     """Get the MCP instance, creating server if needed."""
     global _server
     if _server is None:
         _server = _create_server()
     return _server.mcp
 
 
-def _get_server():
+def _get_server() -> "HomeAssistantSmartMCPServer":
     """Get the server instance, creating if needed."""
     global _server
     if _server is None:
@@ -390,7 +397,7 @@ async def _cancel_tasks(*tasks: asyncio.Task) -> None:
                 pass
 
 
-async def _run_with_shutdown(server_coro) -> None:
+async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
     """Run a server coroutine with graceful shutdown support.
 
     Handles signal-based shutdown, resource cleanup, and task cancellation.
@@ -431,7 +438,7 @@ async def _run_with_shutdown(server_coro) -> None:
         await _cancel_tasks(server_task, shutdown_task)
 
 
-def _run_entrypoint(coro, label: str) -> None:
+def _run_entrypoint(coro: Coroutine[Any, Any, Any], label: str) -> None:
     """Run an async entrypoint with standard exception handling."""
     _setup_signal_handlers()
 
@@ -659,7 +666,9 @@ async def _run_oauth_server(base_url: str, port: int, path: str) -> None:
     proxy_client = OAuthProxyClient(auth_provider)
 
     global _server
-    _server = HomeAssistantSmartMCPServer(client=proxy_client)
+    _server = HomeAssistantSmartMCPServer(
+        client=proxy_client,  # type: ignore[arg-type]  # OAuthProxyClient forwards all HomeAssistantClient attrs via __getattr__
+    )
     mcp = _server.mcp
     mcp.auth = auth_provider
 

src/ha_mcp/auth/provider.py

@@ -338,7 +338,7 @@ async def authorize(
         """
         if client.client_id is None:
             raise AuthorizeError(
-                error="invalid_client",
+                error="invalid_request",
                 error_description="Client ID is required",
             )
 
@@ -507,7 +507,7 @@ async def _consent_post(self, request: Request) -> Response:
             ),
             scopes=scopes_list,
             expires_at=expires_at,
-            code_challenge=pending.get("code_challenge"),
+            code_challenge=pending.get("code_challenge"),  # type: ignore[arg-type]  # None is valid per PKCE spec (RFC 7636 §4.3); empty string would break validation
         )
         self.auth_codes[auth_code_value] = auth_code
 
@@ -617,7 +617,7 @@ async def exchange_authorization_code(
         ha_credentials = self.ha_credentials.get(client.client_id)
         if not ha_credentials:
             raise TokenError(
-                "server_error",
+                "invalid_client",
                 f"No Home Assistant credentials found for client {client.client_id}",
             )
 

src/ha_mcp/client/rest_client.py

@@ -618,7 +618,7 @@ async def start_config_flow(
         Raises:
             HomeAssistantAPIError: If flow start fails
         """
-        payload = {"handler": handler}
+        payload: dict[str, Any] = {"handler": handler}
         if context:
             payload["context"] = context
 
@@ -740,6 +740,8 @@ async def send_websocket_message(self, message: dict[str, Any]) -> dict[str, Any
                 logger.error(f"WebSocket message failed: {e}")
                 return {"success": False, "error": str(e)}
 
+        return {"success": False, "error": "WebSocket request failed"}
+
     async def _handle_render_template(
         self, ws_client: Any, message: dict[str, Any]
     ) -> dict[str, Any]:

src/ha_mcp/client/websocket_client.py

@@ -688,7 +688,7 @@ async def get_client(
 
             # Evict least-recently-used connection if over limit
             if len(self._clients) > MAX_POOL_SIZE:
-                oldest_key = min(self._last_used, key=self._last_used.get)
+                oldest_key = min(self._last_used, key=lambda k: self._last_used[k])
                 stale = self._clients.pop(oldest_key, None)
                 self._last_used.pop(oldest_key, None)
                 if stale:

src/ha_mcp/server.py

@@ -11,9 +11,9 @@
 
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
-import yaml
+import yaml  # type: ignore[import-untyped]
 from fastmcp import FastMCP
 from mcp.types import Icon
 
@@ -314,9 +314,9 @@ async def smart_entity_search(
         self, query: str, domain_filter: str | None = None, limit: int = 10
     ) -> dict[str, Any]:
         """Bridge method to existing smart search implementation."""
-        return await self.smart_tools.smart_entity_search(
+        return cast(dict[str, Any], await self.smart_tools.smart_entity_search(
             query=query, limit=limit, include_attributes=False
-        )
+        ))
 
     async def get_entity_state(self, entity_id: str) -> dict[str, Any]:
         """Bridge method to existing entity state implementation."""
@@ -328,7 +328,7 @@ async def call_service(
         service: str,
         entity_id: str | None = None,
         data: dict | None = None,
-    ) -> list[dict[str, Any]]:
+    ) -> list[dict[str, Any]] | dict[str, Any]:
         """Bridge method to existing service call implementation."""
         service_data = data or {}
         if entity_id:
@@ -337,9 +337,9 @@ async def call_service(
 
     async def get_entities_by_area(self, area_name: str) -> dict[str, Any]:
         """Bridge method to existing area functionality."""
-        return await self.smart_tools.get_entities_by_area(
+        return cast(dict[str, Any], await self.smart_tools.get_entities_by_area(
             area_query=area_name, group_by_domain=True
-        )
+        ))
 
     async def start(self) -> None:
         """Start the Smart MCP server with async compatibility."""

src/ha_mcp/tools/backup.py

@@ -7,7 +7,7 @@
 import asyncio
 import logging
 from datetime import datetime
-from typing import TYPE_CHECKING, Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any, cast
 
 from fastmcp.exceptions import ToolError
 from pydantic import Field
@@ -105,6 +105,7 @@ async def create_backup(
                 ErrorCode.CONNECTION_FAILED,
                 "Failed to connect to Home Assistant WebSocket for backup",
             ))
+        ws_client = cast(HomeAssistantWebSocketClient, ws_client)
 
         # Get backup password
         password, error = await _get_backup_password(ws_client)
@@ -256,6 +257,7 @@ async def restore_backup(
                 ErrorCode.CONNECTION_FAILED,
                 "Failed to connect to Home Assistant WebSocket for restore",
             ))
+        ws_client = cast(HomeAssistantWebSocketClient, ws_client)
 
         # Verify backup exists
         backup_info = await ws_client.send_command("backup/info")
@@ -354,7 +356,7 @@ async def restore_backup(
                 pass  # Ignore errors during cleanup
 
 
-def register_backup_tools(mcp: "FastMCP", client: HomeAssistantClient, **kwargs) -> None:
+def register_backup_tools(mcp: "FastMCP", client: HomeAssistantClient, **kwargs: Any) -> None:
     """
     Register backup and restore tools with the MCP server.
 

src/ha_mcp/tools/tools_addons.py

@@ -257,7 +257,7 @@ async def list_available_addons(
                 pass
 
 
-def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs) -> None:
+def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -> None:
     """
     Register add-on management tools with the MCP server.
 

src/ha_mcp/tools/tools_areas.py

@@ -156,7 +156,7 @@ async def ha_config_set_area(
                         suggestions=["Provide a name for the new area"],
                     ))
 
-                message: dict[str, Any] = {
+                message = {
                     "type": "config/area_registry/create",
                     "name": name,
                 }
@@ -380,7 +380,7 @@ async def ha_config_set_floor(
                         suggestions=["Provide a name for the new floor"],
                     ))
 
-                message: dict[str, Any] = {
+                message = {
                     "type": "config/floor_registry/create",
                     "name": name,
                 }