Addresses typing issues.

Author: benjaminr

src/cdp_context.py

@@ -36,7 +36,7 @@ async def my_tool_function(cdp_client):
 F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
 
 
-def require_cdp_client(func: F) -> F:
+def require_cdp_client(func: F) -> Callable[..., Awaitable[Any]]:
     """
     Decorator that provides CDP client to tool functions with automatic validation.
 
@@ -95,7 +95,7 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
         except Exception as e:
             return create_error_response(f"CDP context error: {str(e)}")
 
-    return wrapper
+    return wrapper  # type: ignore[return-value]
 
 
 class CDPContext:
@@ -117,9 +117,9 @@ class CDPContext:
 
     def __init__(self) -> None:
         """Initialise the CDP context manager."""
-        self.cdp_client = None
+        self.cdp_client: Any = None
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Any:
         """
         Enter the async context and validate CDP client.
 
@@ -145,7 +145,7 @@ async def __aenter__(self):
         except ImportError as e:
             raise RuntimeError("CDP client module not available.") from e
 
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         """
         Exit the async context.
 
@@ -155,7 +155,7 @@ async def __aexit__(self, exc_type, exc_val, exc_tb):
         pass
 
 
-def get_cdp_client():
+def get_cdp_client() -> Any:
     """
     Get the current CDP client instance without validation.
 

src/tools/chrome_management.py

@@ -35,14 +35,17 @@
 import os
 import platform
 import subprocess
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import aiohttp
 from mcp.server.fastmcp import FastMCP
 
 from ..cdp_context import require_cdp_client
 from .utils import create_error_response, create_success_response
 
+if TYPE_CHECKING:
+    from ..main import ChromeDevToolsClient
+
 
 def get_chrome_executable_path(custom_path: str | None = None) -> str | None:
     """Locate Chrome executable path with cross-platform detection.
@@ -446,7 +449,7 @@ async def connect_to_browser(port: int = 9222) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def navigate_to_url(cdp_client, url: str) -> dict[str, Any]:
+    async def navigate_to_url(cdp_client: ChromeDevToolsClient, url: str) -> dict[str, Any]:
         """Navigate the connected browser to a specific URL.
 
         Instructs the currently connected Chrome instance to navigate to the specified

src/tools/console.py

@@ -39,13 +39,16 @@
 from __future__ import annotations
 
 import asyncio
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from mcp.server.fastmcp import FastMCP
 
 from ..cdp_context import require_cdp_client
 from .utils import create_error_response, create_success_response, safe_timestamp_conversion
 
+if TYPE_CHECKING:
+    from ..main import ChromeDevToolsClient
+
 
 def register_console_tools(mcp: FastMCP) -> None:
     """Register comprehensive console interaction tools with the MCP server.
@@ -82,7 +85,7 @@ def register_console_tools(mcp: FastMCP) -> None:
     @mcp.tool()
     @require_cdp_client
     async def get_console_logs(
-        cdp_client, level: str | None = None, limit: int | None = None
+        cdp_client: ChromeDevToolsClient, level: str | None = None, limit: int | None = None
     ) -> dict[str, Any]:
         """
         Get browser console logs with optional filtering.
@@ -122,7 +125,7 @@ async def get_console_logs(
 
     @mcp.tool()
     @require_cdp_client
-    async def get_console_error_summary(cdp_client) -> dict[str, Any]:
+    async def get_console_error_summary(cdp_client: ChromeDevToolsClient) -> dict[str, Any]:
         """
         Get an organised summary of console errors and warnings.
 
@@ -172,7 +175,7 @@ async def get_console_error_summary(cdp_client) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def execute_javascript(cdp_client, code: str) -> dict[str, Any]:
+    async def execute_javascript(cdp_client: ChromeDevToolsClient, code: str) -> dict[str, Any]:
         """
         Execute JavaScript code in the browser context.
 
@@ -211,7 +214,7 @@ async def execute_javascript(cdp_client, code: str) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def clear_console(cdp_client) -> dict[str, Any]:
+    async def clear_console(cdp_client: ChromeDevToolsClient) -> dict[str, Any]:
         """
         Clear the browser console.
 
@@ -232,7 +235,9 @@ async def clear_console(cdp_client) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def inspect_console_object(cdp_client, expression: str) -> dict[str, Any]:
+    async def inspect_console_object(
+        cdp_client: ChromeDevToolsClient, expression: str
+    ) -> dict[str, Any]:
         """
         Inspect a JavaScript object or expression in detail.
 
@@ -295,7 +300,9 @@ async def inspect_console_object(cdp_client, expression: str) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def monitor_console_live(cdp_client, duration_seconds: int = 10) -> dict[str, Any]:
+    async def monitor_console_live(
+        cdp_client: ChromeDevToolsClient, duration_seconds: int = 10
+    ) -> dict[str, Any]:
         """
         Monitor console output in real-time for a specified duration.
 

src/tools/css.py

@@ -43,13 +43,16 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from mcp.server.fastmcp import FastMCP
 
 from ..cdp_context import require_cdp_client
 from .utils import create_error_response, create_success_response
 
+if TYPE_CHECKING:
+    from ..main import ChromeDevToolsClient
+
 
 def register_css_tools(mcp: FastMCP) -> None:
     """Register comprehensive CSS analysis tools with the MCP server.
@@ -90,7 +93,7 @@ def register_css_tools(mcp: FastMCP) -> None:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_computed_styles(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_computed_styles(cdp_client: ChromeDevToolsClient, node_id: int) -> dict[str, Any]:
         """Retrieve computed CSS styles for a DOM element.
 
         Calculates and returns all computed CSS properties for the specified DOM element.
@@ -136,7 +139,7 @@ async def get_computed_styles(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_inline_styles(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_inline_styles(cdp_client: ChromeDevToolsClient, node_id: int) -> dict[str, Any]:
         """
         Get inline CSS styles for a DOM element.
 
@@ -178,7 +181,7 @@ async def get_inline_styles(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_matched_styles(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_matched_styles(cdp_client: ChromeDevToolsClient, node_id: int) -> dict[str, Any]:
         """
         Get comprehensive style information including all CSS rules matching a DOM element.
 
@@ -261,7 +264,9 @@ async def get_matched_styles(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_stylesheet_text(cdp_client, stylesheet_id: str) -> dict[str, Any]:
+    async def get_stylesheet_text(
+        cdp_client: ChromeDevToolsClient, stylesheet_id: str
+    ) -> dict[str, Any]:
         """
         Get the textual content of a CSS stylesheet.
 
@@ -292,7 +297,9 @@ async def get_stylesheet_text(cdp_client, stylesheet_id: str) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_background_colors(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_background_colors(
+        cdp_client: ChromeDevToolsClient, node_id: int
+    ) -> dict[str, Any]:
         """
         Get background colors and font information for a DOM element.
 
@@ -321,7 +328,7 @@ async def get_background_colors(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_platform_fonts(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_platform_fonts(cdp_client: ChromeDevToolsClient, node_id: int) -> dict[str, Any]:
         """
         Get platform font usage information for a DOM element.
 
@@ -364,7 +371,7 @@ async def get_platform_fonts(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_media_queries(cdp_client) -> dict[str, Any]:
+    async def get_media_queries(cdp_client: ChromeDevToolsClient) -> dict[str, Any]:
         """
         Get all media queries parsed by the rendering engine.
 
@@ -403,7 +410,9 @@ async def get_media_queries(cdp_client) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def collect_css_class_names(cdp_client, stylesheet_id: str) -> dict[str, Any]:
+    async def collect_css_class_names(
+        cdp_client: ChromeDevToolsClient, stylesheet_id: str
+    ) -> dict[str, Any]:
         """
         Collect all class names from a specified stylesheet.
 
@@ -434,7 +443,7 @@ async def collect_css_class_names(cdp_client, stylesheet_id: str) -> dict[str, A
 
     @mcp.tool()
     @require_cdp_client
-    async def start_css_coverage_tracking(cdp_client) -> dict[str, Any]:
+    async def start_css_coverage_tracking(cdp_client: ChromeDevToolsClient) -> dict[str, Any]:
         """
         Start tracking CSS rule usage for coverage analysis.
 
@@ -453,7 +462,7 @@ async def start_css_coverage_tracking(cdp_client) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def stop_css_coverage_tracking(cdp_client) -> dict[str, Any]:
+    async def stop_css_coverage_tracking(cdp_client: ChromeDevToolsClient) -> dict[str, Any]:
         """
         Stop tracking CSS rule usage and get coverage results.
 

src/tools/dom.py

@@ -44,13 +44,16 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from mcp.server.fastmcp import FastMCP
 
 from ..cdp_context import require_cdp_client
 from .utils import create_error_response, create_success_response
 
+if TYPE_CHECKING:
+    from ..main import ChromeDevToolsClient
+
 
 def register_dom_tools(mcp: FastMCP) -> None:
     """Register comprehensive DOM inspection and manipulation tools with the MCP server.
@@ -91,7 +94,9 @@ def register_dom_tools(mcp: FastMCP) -> None:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_document(cdp_client, depth: int = 1, pierce: bool = False) -> dict[str, Any]:
+    async def get_document(
+        cdp_client: ChromeDevToolsClient, depth: int = 1, pierce: bool = False
+    ) -> dict[str, Any]:
         """Retrieve the DOM document structure with configurable depth and shadow DOM access.
 
         Fetches the document tree starting from the root element, with control over
@@ -135,7 +140,9 @@ async def get_document(cdp_client, depth: int = 1, pierce: bool = False) -> dict
 
     @mcp.tool()
     @require_cdp_client
-    async def query_selector(cdp_client, node_id: int, selector: str) -> dict[str, Any]:
+    async def query_selector(
+        cdp_client: ChromeDevToolsClient, node_id: int, selector: str
+    ) -> dict[str, Any]:
         """
         Execute querySelector on a DOM node.
 
@@ -167,7 +174,9 @@ async def query_selector(cdp_client, node_id: int, selector: str) -> dict[str, A
 
     @mcp.tool()
     @require_cdp_client
-    async def query_selector_all(cdp_client, node_id: int, selector: str) -> dict[str, Any]:
+    async def query_selector_all(
+        cdp_client: ChromeDevToolsClient, node_id: int, selector: str
+    ) -> dict[str, Any]:
         """
         Execute querySelectorAll on a DOM node.
 
@@ -193,7 +202,9 @@ async def query_selector_all(cdp_client, node_id: int, selector: str) -> dict[st
 
     @mcp.tool()
     @require_cdp_client
-    async def get_element_attributes(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_element_attributes(
+        cdp_client: ChromeDevToolsClient, node_id: int
+    ) -> dict[str, Any]:
         """
         Get all attributes of a DOM element.
 
@@ -222,7 +233,9 @@ async def get_element_attributes(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_element_outer_html(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_element_outer_html(
+        cdp_client: ChromeDevToolsClient, node_id: int
+    ) -> dict[str, Any]:
         """
         Get the outer HTML of a DOM element.
 
@@ -249,7 +262,9 @@ async def get_element_outer_html(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def get_element_box_model(cdp_client, node_id: int) -> dict[str, Any]:
+    async def get_element_box_model(
+        cdp_client: ChromeDevToolsClient, node_id: int
+    ) -> dict[str, Any]:
         """
         Get the box model (layout information) of a DOM element.
 
@@ -281,7 +296,9 @@ async def get_element_box_model(cdp_client, node_id: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def describe_element(cdp_client, node_id: int, depth: int = 1) -> dict[str, Any]:
+    async def describe_element(
+        cdp_client: ChromeDevToolsClient, node_id: int, depth: int = 1
+    ) -> dict[str, Any]:
         """
         Get detailed information about a DOM element.
 
@@ -317,7 +334,9 @@ async def describe_element(cdp_client, node_id: int, depth: int = 1) -> dict[str
 
     @mcp.tool()
     @require_cdp_client
-    async def get_element_at_position(cdp_client, x: int, y: int) -> dict[str, Any]:
+    async def get_element_at_position(
+        cdp_client: ChromeDevToolsClient, x: int, y: int
+    ) -> dict[str, Any]:
         """
         Get the DOM element at a specific screen position.
 
@@ -346,7 +365,7 @@ async def get_element_at_position(cdp_client, x: int, y: int) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def search_elements(cdp_client, query: str) -> dict[str, Any]:
+    async def search_elements(cdp_client: ChromeDevToolsClient, query: str) -> dict[str, Any]:
         """
         Search for DOM elements matching a query string.
 
@@ -393,7 +412,7 @@ async def search_elements(cdp_client, query: str) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def focus_element(cdp_client, node_id: int) -> dict[str, Any]:
+    async def focus_element(cdp_client: ChromeDevToolsClient, node_id: int) -> dict[str, Any]:
         """
         Focus a DOM element.