Set up pre-commit hooks with ruff, mypy, and tests

- Add .pre-commit-config.yaml with ruff formatting, mypy type checking, and test validation
- Install pre-commit as dev dependency
- Fix all type annotations in test file
- Update chrome_management.py to use consistent cdp_client injection pattern
- Add pre-commit targets to Makefile
- Update README with pre-commit documentation
- All pre-commit hooks now pass: ruff, mypy, pytest

Author: benjaminr

.claude/CLAUDE.md

@@ -0,0 +1,22 @@
+You are an expert coding assistant. This documents some of our ways of working and things you should adhere to.
+
+# General Principles
+
+- Write in British English at all times, for docs and code.
+- Write clean, functional code and minimise the use of abstraction.
+- Follow DRY principles.
+- Be modular and build for extensibility.
+- When you write code, you should follow TDD and start with a unit test to describe the behaviour you're trying to acheive. You should then write the code that passes the test, with the desired functionality.
+- You should always provide good documentation with examples.
+- If you're unsure about an API or SDK, search the web for official docs and guidance.
+
+# Tool use 
+
+Sometimes you will need to call upon other tools to perform certain tasks, here's a cheatsheet for what you should reach for in certain scenarios:
+
+- Looking for text and strings in files: rg
+- Looking more specificially for code-aware / structural find and replace: ast-grep
+- Looking for files or directories: fd
+- When narrowing down options, pipe other commands into: fzf
+- Parsing JSON from files or requests, use: jq
+- Parsing YAML or XML, use: yq

.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+repos:
+  # Ruff linting and formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix]
+        types_or: [python, pyi]
+      # Run the formatter
+      - id: ruff-format
+        types_or: [python, pyi]
+
+  # MyPy type checking
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies: 
+          - mcp
+          - fastmcp
+          - websockets
+          - types-requests
+        args: [--ignore-missing-imports]
+
+  # Local hooks for tests and validation
+  - repo: local
+    hooks:
+      # Run tests
+      - id: pytest
+        name: Run tests
+        entry: uv run python -m pytest test_devtools_server.py -v
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+      # Validate MCP server registration
+      - id: mcp-validation
+        name: Validate MCP server
+        entry: uv run python test_devtools_server.py
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]

CLAUDE.md

@@ -0,0 +1,23 @@
+I want to build this as a Desktop Extension, abbreviated as "DXT". Please follow these steps:
+
+Read the specifications thoroughly:
+https://github.com/anthropics/dxt/blob/main/README.md - DXT architecture overview, capabilities, and integration patterns
+https://github.com/anthropics/dxt/blob/main/MANIFEST.md - Complete extension manifest structure and field definitions
+https://github.com/anthropics/dxt/tree/main/examples - Reference implementations including a "Hello World" example
+Create a proper extension structure:
+Generate a valid manifest.json following the MANIFEST.md spec
+Implement an MCP server using @modelcontextprotocol/sdk with proper tool definitions
+Include proper error handling, security measures, and timeout management
+Follow best development practices:
+Implement proper MCP protocol communication via stdio transport
+Structure tools with clear schemas, validation, and consistent JSON responses
+Make use of the fact that this extension will be running locally
+Add appropriate logging and debugging capabilities
+Include proper documentation and setup instructions
+Test considerations:
+Validate that all tool calls return properly structured responses
+Verify manifest loads correctly and host integration works
+Generate complete, production-ready code that can be immediately tested. Focus on defensive programming, clear error messages, and following the exact DXT specifications to ensure compatibility with the ecosystem.
+
+Recent Updates:
+- Updated use of CDP in the app and general tidying

Makefile

@@ -1,6 +1,6 @@
 # Chrome DevTools MCP - Build Automation
 
-.PHONY: install test lint format clean build package check dev help
+.PHONY: install test lint format clean build package check dev help pre-commit
 
 # Default target
 help:
@@ -17,6 +17,7 @@ help:
 	@echo "  lint       Run linting checks"
 	@echo "  format     Format code with ruff"
 	@echo "  check      Run all checks (lint + type check + test)"
+	@echo "  pre-commit Run pre-commit hooks"
 	@echo ""
 	@echo "Distribution:"
 	@echo "  package    Build DXT extension package"
@@ -29,7 +30,7 @@ help:
 install:
 	uv sync
 
-dev: install
+dev: install install-pre-commit
 	uv run mcp install server.py -n "Chrome DevTools MCP" --with-editable .
 
 # Code quality
@@ -42,6 +43,13 @@ format:
 typecheck:
 	uv run mypy src/
 
+# Pre-commit hooks
+pre-commit:
+	uv run pre-commit run --all-files
+
+install-pre-commit:
+	uv run pre-commit install
+
 # Testing
 test:
 	uv run python -m pytest test_devtools_server.py -v
@@ -58,8 +66,8 @@ test-console:
 test-network:
 	uv run python -m pytest test_devtools_server.py -k "test_network" -v
 
-# All checks
-check: lint typecheck test
+# All checks  
+check: pre-commit
 
 # CI test suite
 ci-test: install check

README.md

@@ -654,11 +654,24 @@ npx @anthropic-ai/dxt pack
 ```bash
 make help           # Show all commands
 make install        # Install dependencies
+make dev            # Setup development environment + pre-commit
 make check          # Run all checks (lint + type + test)
+make pre-commit     # Run pre-commit hooks manually
 make package        # Build .dxt extension
 make release        # Full release build
 ```
 
+### Pre-commit Hooks
+
+This project uses pre-commit hooks to ensure code quality:
+
+- **ruff**: Linting and formatting
+- **mypy**: Type checking  
+- **pytest**: Test validation
+- **MCP validation**: Server registration check
+
+Pre-commit hooks run automatically on `git commit` and can be run manually with `make pre-commit`.
+
 ## License
 
 MIT License

chrome-devtools-protocol-1.0.1.dxt

@@ -58,6 +58,7 @@ dev-dependencies = [
     "pytest-asyncio>=0.23.0",
     "ruff>=0.1.0",
     "mypy>=1.0.0",
+    "pre-commit>=4.2.0",
 ]
 
 [tool.ruff]
@@ -80,4 +81,4 @@ ignore = []
 python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
-disallow_untyped_defs = true
+disallow_untyped_defs = true

devtools-mcp.dxt

@@ -45,19 +45,20 @@ def require_cdp_client(func: F) -> Callable[..., Awaitable[Any]]:
 
     1. Imports the CDP client from the main module
     2. Validates that the client exists and is connected
-    3. Passes the validated client as the first parameter to the decorated function
+    3. Injects the validated client into kwargs as 'cdp_client'
     4. Returns appropriate error responses if client is unavailable
 
     Args:
-        func: The async function to decorate. Must accept cdp_client as first parameter.
+        func: The async function to decorate. Can access cdp_client from kwargs.
 
     Returns:
         The decorated function with automatic CDP client injection.
 
     Example:
         ```python
         @require_cdp_client
-        async def get_page_title(cdp_client, **kwargs):
+        async def get_page_title(**kwargs):
+            cdp_client = kwargs['cdp_client']
             result = await cdp_client.send_command("Runtime.evaluate", {
                 "expression": "document.title",
                 "returnByValue": True
@@ -85,8 +86,11 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
                     "Not connected to browser. Please connect to Chrome first."
                 )
 
-            # Call the original function with CDP client as first argument
-            return await func(cdp_client, *args, **kwargs)
+            # Inject CDP client into kwargs
+            kwargs["cdp_client"] = cdp_client
+
+            # Call the original function with CDP client available in kwargs
+            return await func(*args, **kwargs)
 
         except ImportError:
             return create_error_response(
@@ -176,6 +180,7 @@ def get_cdp_client() -> Any:
     """
     try:
         from . import main
+
         return main.cdp_client
     except ImportError:
         return None

pyproject.toml

@@ -133,7 +133,7 @@ async def check_chrome_running(port: int) -> bool:
     try:
         async with aiohttp.ClientSession() as session:
             async with session.get(f"http://localhost:{port}/json/version", timeout=2) as response:
-                return response.status == 200
+                return bool(response.status == 200)
     except Exception:
         return False
 
@@ -175,6 +175,7 @@ async def start_chrome(
         headless: bool = False,
         chrome_path: str | None = None,
         auto_connect: bool = False,
+        **kwargs: Any,
     ) -> dict[str, Any]:
         """Start Chrome with remote debugging enabled and optionally establish connection.
 
@@ -349,7 +350,11 @@ async def start_chrome(
 
     @mcp.tool()
     async def start_chrome_and_connect(
-        url: str, port: int = 9222, headless: bool = False, chrome_path: str | None = None
+        url: str,
+        port: int = 9222,
+        headless: bool = False,
+        chrome_path: str | None = None,
+        **kwargs: Any,
     ) -> dict[str, Any]:
         """Start Chrome with debugging, connect, and navigate to URL in one step.
 
@@ -446,7 +451,7 @@ async def connect_to_browser(port: int = 9222) -> dict[str, Any]:
 
     @mcp.tool()
     @require_cdp_client
-    async def navigate_to_url(cdp_client: Any, url: str) -> dict[str, Any]:
+    async def navigate_to_url(url: str, **kwargs: Any) -> dict[str, Any]:
         """Navigate the connected browser to a specific URL.
 
         Instructs the currently connected Chrome instance to navigate to the specified
@@ -472,6 +477,7 @@ async def navigate_to_url(cdp_client: Any, url: str) -> dict[str, Any]:
             load completion if needed.
         """
         try:
+            cdp_client = kwargs["cdp_client"]
             await cdp_client.send_command("Page.navigate", {"url": url})
             await asyncio.sleep(1)
 
@@ -483,7 +489,8 @@ async def navigate_to_url(cdp_client: Any, url: str) -> dict[str, Any]:
             return create_error_response(f"Navigation error: {e}")
 
     @mcp.tool()
-    async def disconnect_from_browser() -> dict[str, Any]:
+    @require_cdp_client
+    async def disconnect_from_browser(**kwargs: Any) -> dict[str, Any]:
         """Disconnect from the current browser session.
 
         Cleanly terminates the connection to the Chrome browser instance while
@@ -504,14 +511,8 @@ async def disconnect_from_browser() -> dict[str, Any]:
             This function only disconnects the client from Chrome; it doesn't
             close or terminate the browser process itself.
         """
-        from .. import main
-
-        cdp_client = main.cdp_client
-
-        if not cdp_client:
-            return create_error_response("CDP client not initialised")
-
         try:
+            cdp_client = kwargs["cdp_client"]
             await cdp_client.disconnect()
             return create_success_response(
                 message="Disconnected from browser", data={"connected": False}
@@ -521,7 +522,8 @@ async def disconnect_from_browser() -> dict[str, Any]:
             return create_error_response(f"Disconnection error: {e}")
 
     @mcp.tool()
-    async def get_connection_status() -> dict[str, Any]:
+    @require_cdp_client
+    async def get_connection_status(**kwargs: Any) -> dict[str, Any]:
         """Get the current connection status to the browser.
 
         Retrieves comprehensive information about the current connection state,
@@ -548,17 +550,8 @@ async def get_connection_status() -> dict[str, Any]:
             This function is safe to call at any time and will not modify the
             connection state, only report it.
         """
-        from .. import main
-
-        cdp_client = main.cdp_client
-
-        if not cdp_client:
-            return create_success_response(
-                message="CDP client not initialised",
-                data={"connected": False, "status": "not_initialised"},
-            )
-
         try:
+            cdp_client = kwargs["cdp_client"]
             if cdp_client.connected:
                 target_info = await cdp_client.get_target_info()
                 return create_success_response(