🎉 Refactor MCP Selenium Grid CLI + 🧰 NEW: Add rich-coverage development script +🐛 Fix Server Warnings

.github/workflows/1.2_unit_tests.yml

@@ -28,7 +28,7 @@ jobs:
             uv.lock
 
       - name: Install dependencies
-        run: uv sync --locked --all-groups --extra test --extra coverage
+        run: uv sync --locked --all-groups --extra test
 
       - name: Run code format
         run: uv run ruff format . --check

.github/workflows/1.3_docker_tests.yml

@@ -30,7 +30,7 @@ jobs:
             uv.lock
 
       - name: Install dependencies
-        run: uv sync --locked --all-groups --extra test --extra coverage
+        run: uv sync --locked --all-groups --extra test
 
       - name: Run Docker integration & E2E tests with coverage
         run: uv run coverage run --parallel-mode -m pytest -m "integration or e2e" -k "docker"

.github/workflows/1.4_kubernetes_tests.yml

@@ -58,7 +58,7 @@ jobs:
           echo "KUBERNETES__KUBECONFIG=$kube_config" >> $GITHUB_ENV
 
       - name: Install dependencies
-        run: uv sync --locked --all-groups --extra test --extra coverage
+        run: uv sync --locked --all-groups --extra test
 
       - name: Deploy Selenium Grid to KinD
         run: uv run mcp-selenium-grid helm deploy

.github/workflows/1_tests.yml

@@ -14,6 +14,7 @@ permissions: {}  # deny all by default
 env:
   UV_SYSTEM_PYTHON: 1
   MIN_COVERAGE: 70
+  COVERAGE_TOLERANCE_MARGIN: 5
 
 jobs:
   filter:
@@ -30,12 +31,11 @@ jobs:
           filters: |
             py:
               - 'src/**/*.py'
-              - 'scripts/**/*.py'
 
   lint:
     uses: ./.github/workflows/1.1_lint.yml
     needs:  filter
-    if: github.ref == 'refs/heads/main' && needs.filter.outputs.src_changed == 'true'
+    if: needs.filter.outputs.src_changed == 'true'
     permissions:
       contents: read
   unit-tests:
@@ -96,18 +96,10 @@ jobs:
         with:
           enable-cache: true
           cache-dependency-glob: |
-            pyproject.toml
-            uv.lock
-
-      - name: Install dependencies
-        run: uv sync --locked --extra coverage
+            scripts/rich-coverage.py.lock
 
       - name: Combine and report coverage
-        run: |
-          uv run coverage combine
-          uv run coverage report --format=markdown >> $GITHUB_STEP_SUMMARY
-          uv run coverage report --fail-under=$MIN_COVERAGE
-
+        run: uv run ./scripts/rich-coverage.py --format=html >> $GITHUB_STEP_SUMMARY # no need to install dependencies
   check:
     name: Did all tests pass?
     if: always()

.pre-commit-config.yaml

@@ -1,10 +1,10 @@
 repos:
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.21
+    rev: 0.8.5
     hooks:
       - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.3
+    rev: v0.12.7
     hooks:
       - id: ruff
         args: [--fix]

CONTRIBUTING.md

@@ -88,7 +88,7 @@ git clone [email protected]:Falamarcao/mcp-selenium-grid.git
 cd mcp-selenium-grid
 
 # Create a virtual environment and install dev/test dependencies
-uv sync --all-groups --extra test --extra coverage
+uv sync --all-groups --extra test
 ```
 
 ### 3. Kubernetes Setup (Optional)
@@ -131,6 +131,8 @@ kubectl config set-context k3s-selenium-grid \
 ```bash
 # See command help
 uv run mcp-selenium-grid helm --help
+uv run mcp-selenium-grid helm deploy --help
+uv run mcp-selenium-grid helm uninstall --help
 
 # Deploy using default config
 uv run mcp-selenium-grid helm deploy
@@ -142,8 +144,6 @@ uv run mcp-selenium-grid helm deploy --context k3s-selenium-grid
 uv run mcp-selenium-grid helm uninstall --delete-namespace
 ```
 
-> See [scripts/helm/README.md](scripts/helm/README.md) for more details.
-
 ### 4. Start Server
 
 ```bash
@@ -178,8 +178,8 @@ uv run pytest -m integration
 uv run pytest -m e2e
 
 # Run with coverage
-uv run coverage run -m pytest -m unit
-uv run coverage report
+uv run scripts/rich-coverage.py
+uv run scripts/rich-coverage.py --format=html
 ```
 
 #### 🧪 CI & Workflow Testing
@@ -211,7 +211,7 @@ uv run ruff clean             # Clear ruff cache
 
 ## 📦 Dependency Management
 
-- Install all dependencies: `uv sync --all-groups --extra test --extra coverage`
+- Install all dependencies: `uv sync --all-groups --extra test`
 - Add a dependency: `uv add <package>`
 - Add a dev dependency: `uv add <package> --dev`
 - Add a test dependency: `uv add <package> --optional test`

Dockerfile

@@ -11,7 +11,6 @@ COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
 # Copy project files
 COPY pyproject.toml config.yaml LICENSE README.md uv.lock ./mcp-selenium-grid/
 COPY deployment ./mcp-selenium-grid/deployment
-COPY scripts ./mcp-selenium-grid/scripts
 COPY src/app ./mcp-selenium-grid/src/app
 
 # Install the application dependencies

README.md

@@ -45,18 +45,18 @@ For Docker-based deployment, ensure Docker is running and use the Docker configu
       "command": "uvx",
       "args": ["mcp-selenium-grid", "server", "run",
         "--host", "127.0.0.1",
-        "--port", "8000",
+        "--port", "8000"
       ],
       "env": {
         "API_TOKEN": "CHANGE_ME",
-        "ALLOWED_ORIGINS": ["http://localhost:8000"],
+        "ALLOWED_ORIGINS": "[\"http://127.0.0.1:8000\"]",
         "DEPLOYMENT_MODE": "docker",
         "SELENIUM_GRID__USERNAME": "USER",
         "SELENIUM_GRID__PASSWORD": "CHANGE_ME",
         "SELENIUM_GRID__VNC_PASSWORD": "CHANGE_ME",
-        "SELENIUM_GRID__VNC_VIEW_ONLY": false,
-        "SELENIUM_GRID__MAX_BROWSER_INSTANCES": 4,
-        "SELENIUM_GRID__SE_NODE_MAX_SESSIONS": 1,
+        "SELENIUM_GRID__VNC_VIEW_ONLY": "false",
+        "SELENIUM_GRID__MAX_BROWSER_INSTANCES": "4",
+        "SELENIUM_GRID__SE_NODE_MAX_SESSIONS": "1"
       }
     }
   }
@@ -104,24 +104,25 @@ kubectl config set-context k3s-selenium-grid \
 
 ###### Deploy Selenium Grid
 
-Using kubernetes context name from [config.yaml](./config.yaml):
+Please run for help to get to know the available commands and parameters:
 
 ```bash
 uvx mcp-selenium-grid helm --help
-uvx mcp-selenium-grid helm deploy
+uvx mcp-selenium-grid helm deploy --help
+uvx mcp-selenium-grid helm uninstall --help
 ```
 
-For a given kubernetes context name:
+Deploy using default parameters:
 
 ```bash
-uvx mcp-selenium-grid helm deploy --context k3s-selenium-grid
+uvx mcp-selenium-grid helm deploy
 ```
 
-Uninstall:
+Uninstall using default parameters:
 
 ```bash
+# using default parameters
 uvx mcp-selenium-grid helm uninstall --delete-namespace
-uvx mcp-selenium-grid helm uninstall --context k3s-selenium-grid --delete-namespace
 ```
 
 ```json
@@ -131,22 +132,22 @@ uvx mcp-selenium-grid helm uninstall --context k3s-selenium-grid --delete-namesp
       "command": "uvx",
       "args": ["mcp-selenium-grid", "server", "run",
         "--host", "127.0.0.1",
-        "--port", "8000",
+        "--port", "8000"
       ],
       "env": {
         "API_TOKEN": "CHANGE_ME",
-        "ALLOWED_ORIGINS": ["http://localhost:8000"],
+        "ALLOWED_ORIGINS": "[\"http://127.0.0.1:8000\"]",
         "DEPLOYMENT_MODE": "kubernetes",
         "SELENIUM_GRID__USERNAME": "USER",
         "SELENIUM_GRID__PASSWORD": "CHANGE_ME",
         "SELENIUM_GRID__VNC_PASSWORD": "CHANGE_ME",
-        "SELENIUM_GRID__VNC_VIEW_ONLY": false,
-        "SELENIUM_GRID__MAX_BROWSER_INSTANCES": 4,
-        "SELENIUM_GRID__SE_NODE_MAX_SESSIONS": 1,
+        "SELENIUM_GRID__VNC_VIEW_ONLY": "false",
+        "SELENIUM_GRID__MAX_BROWSER_INSTANCES": "4",
+        "SELENIUM_GRID__SE_NODE_MAX_SESSIONS": "1",
         "KUBERNETES__KUBECONFIG": "~/.kube/config-local-k3s",
         "KUBERNETES__CONTEXT": "k3s-selenium-grid",
         "KUBERNETES__NAMESPACE": "selenium-grid-dev",
-        "KUBERNETES__SELENIUM_GRID_SERVICE_NAME": "selenium-grid",
+        "KUBERNETES__SELENIUM_GRID_SERVICE_NAME": "selenium-grid"
       }
     }
   }
@@ -165,7 +166,7 @@ uvx mcp-selenium-grid helm uninstall --context k3s-selenium-grid --delete-namesp
         "--init",
         "-p", "8000:80",
         "-e", "API_TOKEN=CHANGE_ME",
-        "-e", "ALLOWED_ORIGINS=http://localhost:8000",
+        "-e", "ALLOWED_ORIGINS=[\"http://127.0.0.1:8000\"]",
         "-e", "DEPLOYMENT_MODE=kubernetes", // required for docker
         "-e", "SELENIUM_GRID__USERNAME=USER",
         "-e", "SELENIUM_GRID__PASSWORD=CHANGE_ME",
@@ -177,7 +178,7 @@ uvx mcp-selenium-grid helm uninstall --context k3s-selenium-grid --delete-namesp
         "-e", "KUBERNETES__CONTEXT=k3s-selenium-grid",
         "-e", "KUBERNETES__NAMESPACE=selenium-grid-dev",
         "-e", "KUBERNETES__SELENIUM_GRID_SERVICE_NAME=selenium-grid",
-        "ghcr.io/falamarcao/mcp-selenium-grid:latest",
+        "ghcr.io/falamarcao/mcp-selenium-grid:latest"
       ]
     }
   }

config.yaml

@@ -23,7 +23,7 @@ selenium_grid:
         memory: "1G"
         cpu: "0.5"
     undetected-chrome:
-      image: falamarcao/node-undetected-chrome:latest # not public yet (testing)
+      image: ghcr.io/catchnip/node-undetected-chrome:latest # not public yet (testing)
       port: 4444
       resources:
         memory: "1G"

deployment/README.md

@@ -2,6 +2,8 @@
 
 This directory contains the deployment configurations for the Selenium Grid on Kubernetes using Helm.
 
+⚠️ Not meant to be used directly. Use `uvx mcp-selenium-grid helm deploy --help` instead. ⚠️
+
 ## Directory Structure
 
 ```txt

pyproject.toml

@@ -3,14 +3,17 @@
 # AI Agents and contributors: Please assume uv is the default tool for all dependency and environment management in this project.
 # You do NOT need to ask the user if uv is being used—always use uv commands for installs, updates, and checks.
 #
-# To install dependencies: `uv pip install .` or `uv pip install -e ".[dev]"` (for development)
-# To add a dependency: `uv pip install <package>`
+# - Install all dependencies: `uv sync --all-groups --extra test`
+# - Add a dependency: `uv add <package>`
+# - Add a dev dependency: `uv add <package> --dev`
+# - Add a test dependency: `uv add <package> --optional test`
+# - Remove a dependency: `uv remove <package>`
 #
 # For more info, see the README.
 
 [project]
 name = "mcp-selenium-grid"
-version = "0.1.0.dev1"
+version = "0.1.0.dev2"
 description = "MCP Server for managing Selenium Grid instances"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -54,23 +57,20 @@ test = [
     "pytest-mock>=3.14.1",
     "pytest-asyncio>=1.0.0", # Parallel test execution
     "pytest-sugar>=1.0.0",
-]
-
-coverage = [
-    "coverage[toml]>=7.9.2",
+    "coverage>=7.10.2",
 ]
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/app", "scripts"]
+packages = ["src/app"]
 
 [tool.ruff]
 line-length = 100
 target-version = "py312"
-src = ["src/app", "src/tests"]
+src = ["src/app", "src/tests", "scripts"]
 
 [tool.ruff.lint]
 extend-select = [
@@ -93,7 +93,7 @@ disallow_untyped_defs = true
 check_untyped_defs = true
 
 [[tool.mypy.overrides]]
-module = ["fastapi_mcp", "sh"]
+module = ["fastapi_mcp"]
 ignore_missing_imports = true
 
 [tool.pytest.ini_options]