✨ chore: Add FastMCP stdio support, update CLI, docs, and dependencies

.cursor/rules/imports-order.mdc

@@ -0,0 +1,7 @@
+---
+description: 'Ignore unsorted/unformatted import block linting'
+globs: ['*.py']
+alwaysApply: false
+when: 'Import block is un-sorted or un-formatted'
+do: 'ignore'
+---

.pre-commit-config.yaml

@@ -1,10 +1,10 @@
 repos:
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.8.8
+    rev: 0.8.15
     hooks:
       - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.8
+    rev: v0.12.12
     hooks:
       - id: ruff-check
         args: [--fix]

ATTRIBUTION.md

@@ -7,7 +7,7 @@ This document lists the third-party dependencies, tools, and components used in
 - **Project Name**: MCP Selenium Grid
 - **Author**: [Marco (falamarcao)](https://github.com/Falamarcao)
 - **License**: MIT License
-- **Repository**: [mcp-selenium-grid](https://github.com/Falamarcao/mcp-selenium-grid)
+- **Repository**: [mcp-selenium-grid](https://github.com/CatchNip/mcp-selenium-grid)
 
 ## Core Dependencies
 
@@ -229,7 +229,7 @@ If you use this project in your work, research, or other projects, please includ
   title = {MCP Selenium Grid: A Model Context Protocol Server for Browser Automation},
   author = {Marco (falamarcao)},
   year = {2025},
-  url = {https://github.com/Falamarcao/mcp-selenium-grid},
+  url = {https://github.com/CatchNip/mcp-selenium-grid},
   license = {MIT},
   note = {A REST API server for managing Selenium browser instances through MCP}
 }
@@ -242,7 +242,7 @@ If you use this project in your work, research, or other projects, please includ
 
 This project uses the following third-party components:
 
-- **MCP Selenium Grid** - [MIT License](https://github.com/Falamarcao/mcp-selenium-grid/blob/main/LICENSE)
+- **MCP Selenium Grid** - [MIT License](https://github.com/CatchNip/mcp-selenium-grid/blob/main/LICENSE)
   - Model Context Protocol server for managing Selenium Grid.
   - Created by [Marco (falamarcao)](https://github.com/Falamarcao)
 ```
@@ -251,24 +251,24 @@ This project uses the following third-party components:
 
 ```python
 # This module uses MCP Selenium Grid
-# https://github.com/Falamarcao/mcp-selenium-grid
+# https://github.com/CatchNip/mcp-selenium-grid
 # MIT License - Copyright (c) 2025 Marco (falamarcao)
 ```
 
 ### requirements.txt (for Python projects)
 
 ```txt
 # MCP Selenium Grid - MIT License
-# https://github.com/Falamarcao/mcp-selenium-grid
-git+https://github.com/Falamarcao/mcp-selenium-grid.git
+# https://github.com/CatchNip/mcp-selenium-grid
+git+https://github.com/CatchNip/mcp-selenium-grid.git
 ```
 
 ### Dockerfile
 
 ```dockerfile
 # Uses MCP Selenium Grid - MIT License
-# https://github.com/Falamarcao/mcp-selenium-grid
-FROM ghcr.io/falamarcao/mcp-selenium-grid:latest
+# https://github.com/CatchNip/mcp-selenium-grid
+FROM ghcr.io/CatchNip/mcp-selenium-grid:latest
 ```
 
 ### License Compliance

CITATION.cff

@@ -7,8 +7,11 @@ message: "If you use this software, please cite it as below."
 type: software
 authors:
   - given-names: Marco
-    email: falamarcao@gmail.com
-repository-code: "https://github.com/Falamarcao/mcp-selenium-grid"
+    url: https://github.com/falamarcao
+  - name: CatchNip
+    type: organization
+    url: https://github.com/CatchNip
+repository-code: "https://github.com/catchnip/mcp-selenium-grid"
 abstract: " enables AI Agents to request and manage Selenium browser instances through a secure API. Perfect for your automated browser testing needs! "
 keywords:
   - selenium grid

CONTRIBUTING.md

@@ -30,20 +30,30 @@ When reporting issues, please include:
 
 ### Pull Request Process
 
-1. **Fork the repository** - Click the "Fork" button on GitHub
-2. **Create a feature branch** - Use a descriptive branch name:
+1. **Fork the repository `main` branch** - Click the "Fork" button on GitHub
+2. **Clone your repository to local using ssh** - `git clone git@github.com:YourGitHubUserName/mcp-selenium-grid.git`
+3. **Install the pre-commit hooks**
+
+   - This project uses pre-commit hooks configured in `.pre-commit-config.yaml` for automated code quality checks. When fresh cloned and when `.pre-commit-config.yaml` is updated, run:
+
+   ```bash
+   uv run pre-commit install && uv run pre-commit autoupdate && uv run pre-commit run --all-files
+   ```
+
+4. **Create a feature branch** - Use a descriptive branch name (be creative):
 
    ```bash
    git checkout -b feature/amazing-feature
    git checkout -b fix/bug-description
    git checkout -b docs/update-readme
    ```
 
-3. **Make your changes** - Write clean, well-documented code
-4. **Run and write tests** - Ensure everything works
-5. **Commit your changes** - Write clear, descriptive commit messages
-6. **Push to your branch**
-7. **Open a Pull Request** - Fill out the PR template
+5. **Make your changes** - Write clean, well-documented code
+6. **Run and write tests** - Ensure everything works
+7. **Commit your changes** - Write clear, descriptive commit messages
+8. **Make sure that your branch is updated with `main` branch** - keep a linear commit history, rebase if necessary
+9. **Push to your branch**
+10. **Open a Pull Request** - Fill out the PR template
 
 #### 💡 Commit Message Tips
 
@@ -84,7 +94,7 @@ When reporting issues, please include:
 
 ```bash
 # Clone the repository
-git clone git@github.com:Falamarcao/mcp-selenium-grid.git
+git clone git@github.com:catchnip/mcp-selenium-grid.git
 cd mcp-selenium-grid
 
 # Create a virtual environment and install dev/test dependencies
@@ -95,7 +105,7 @@ uv sync --all-groups --extra test
 
 This project requires a Kubernetes cluster for running tests and managing browser instances. We use K3s for local development and testing.
 
-#### Install K3s (<https://docs.k3s.io/quick-start>)
+#### 3.1 Install K3s (<https://docs.k3s.io/quick-start>)
 
 ```bash
 # Install K3s
@@ -108,7 +118,7 @@ k3s --version
 sudo systemctl start k3s
 ```
 
-#### Create K3s Kubernetes Context (Optional)
+#### 3.2 Create K3s Kubernetes Context (Optional)
 
 After installing K3s, you might want to create a dedicated `kubectl` context for it:
 
@@ -126,7 +136,7 @@ kubectl config set-context k3s-selenium-grid \
   --user=default
 ```
 
-#### Deploy Selenium Grid
+#### 3.3 Deploy Selenium Grid
 
 ```bash
 # See command help
@@ -166,7 +176,7 @@ uv run fastapi dev src/app/main.py
 uv run fastapi run src/app/main.py
 ```
 
-### 5. Running Tests
+### 5. Testing 🧪
 
 ```bash
 # Run all tests
@@ -182,9 +192,37 @@ uv run scripts/rich-coverage.py
 uv run scripts/rich-coverage.py --format=html
 ```
 
-#### 🧪 CI & Workflow Testing
+#### 5.1 Inspect MCP Server
+
+Use MCP Inspector to inspect the mcp server [mcp-dev.json](mcp-dev.json)
+
+```bash
+npx @modelcontextprotocol/inspector --config mcp-dev.json --server prod
+```
+
+```bash
+npx @modelcontextprotocol/inspector --config mcp-dev.json --server prod-k8s
+```
+
+```bash
+npx @modelcontextprotocol/inspector --config mcp-dev.json --server dev
+```
+
+```bash
+docker build -t ghcr.io/catchnip/mcp-selenium-grid:latest .
+```
+
+```bash
+npx @modelcontextprotocol/inspector --config mcp-dev.json --server docker
+```
+
+> Requires node installed. I recommend using [VOLTA - The Hassle-Free JavaScript Tool Manager](https://volta.sh/)
+
+#### 5.2 CI & Workflow Testing
+
+- To test GitHub Actions workflows locally, see [`.github/workflows/README.md`](.github/workflows/README.md) for simple act usage instructions.
 
-- To test GitHub Actions workflows locally, see [`.github/README.md`](.github/README.md) for simple act usage instructions.
+> Attention: Some actions like GitHub Actions upload/download artifacts don't work well when testing using `act`. Unsupported functionality: <https://nektosact.com/not_supported.html>
 
 ### 6. Code Quality
 
@@ -194,7 +232,7 @@ uv run mypy .                 # Type check
 uv run ruff format .          # Format
 ```
 
-This project uses pre-commit hooks configured in `.pre-commit-config.yaml` for automated code quality checks. If the pre-commit configuration is updated, run:
+This project uses pre-commit hooks configured in `.pre-commit-config.yaml` for automated code quality checks. If `.pre-commit-config.yaml` is updated, run:
 
 ```bash
 uv run pre-commit install && uv run pre-commit autoupdate && uv run pre-commit run --all-files

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.13-slim-bullseye
+FROM python:3.13-slim-bookworm
 
 # Set environment variables
 ENV PYTHONUNBUFFERED=1 \
@@ -26,7 +26,7 @@ EXPOSE 80
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
-    CMD sh -c 'curl -f -H "Authorization: Bearer $API_TOKEN" http://localhost:80/health || exit 1'
+    CMD sh -c 'curl -f -H "Authorization: Bearer $API_TOKEN" http://localhost:8000/health || exit 1'
 
 # Run the application.
-CMD ["/mcp-selenium-grid/.venv/bin/fastapi", "run", "src/app/main.py", "--port", "80"]
+CMD ["/mcp-selenium-grid/.venv/bin/fastapi", "run", "src/app/main.py", "--port", "8000"]

README.md

@@ -31,7 +31,19 @@ The MCP Selenium Grid provides a MCP Server for creating and managing browser in
 ### 📖 Usage
 
 The MCP Selenium Grid provides a Web API for creating and managing browser instances. The server runs on `localhost:8000` and exposes MCP endpoints at `/mcp` (Http Transport) and `/sse` (Server Sent Events).
-> Note: All requests to the server root `http://localhost:8000` will be redirected to either `/mcp` or `/sse` endpoints, depending on the request.
+> Note: All requests to the server root `http://localhost:8000` will be redirected to either `/mcp` or `/sse` endpoints, depending on the request, but you can choose to use directly `/mcp` (Http Transport) or `/sse` (Server Sent Events) endpoints.
+
+### Known Issues & Limitations
+
+- When you use [STDIO transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) with the `--stdio` flag, the MCP Servers do not shut down the same way they do in the terminal. To clean up resources and remove containers or pods, run:
+
+    ```bash
+    uv run mcp-selenium-grid clean
+    ```
+
+    ```bash
+    uv run mcp-selenium-grid clean -d kubernetes
+    ```
 
 ### MCP Client Configuration
 
@@ -46,18 +58,20 @@ 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",
+        "--stdio",
       ],
       "env": {
-        "API_TOKEN": "SERVER_AUTH_DISABLED",
+        "AUTH_ENABLED": "false",
         "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__SE_NODE_MAX_SESSIONS": "1",
+        "FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER": "true"
       }
     }
   }
@@ -85,7 +99,7 @@ k3s --version
 sudo systemctl start k3s
 ```
 
-###### Create K3s Kubernetes Context (Optional)
+###### Create K3s Kubernetes Context
 
 After installing K3s, you might want to create a dedicated `kubectl` context for it:
 
@@ -133,10 +147,11 @@ uvx mcp-selenium-grid helm uninstall --delete-namespace
       "command": "uvx",
       "args": ["mcp-selenium-grid", "server", "run",
         "--host", "127.0.0.1",
-        "--port", "8000"
+        "--port", "8000",
+        "--stdio",
       ],
       "env": {
-        "API_TOKEN": "SERVER_AUTH_DISABLED",
+        "AUTH_ENABLED": "false",
         "ALLOWED_ORIGINS": "[\"http://127.0.0.1:8000\"]",
         "DEPLOYMENT_MODE": "kubernetes",
         "SELENIUM_GRID__USERNAME": "USER",
@@ -148,7 +163,8 @@ uvx mcp-selenium-grid helm uninstall --delete-namespace
         "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",
+        "FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER": "true"
       }
     }
   }
@@ -165,21 +181,24 @@ uvx mcp-selenium-grid helm uninstall --delete-namespace
         "-i",
         "--rm",
         "--init",
-        "-p", "8000:80",
-        "-e", "API_TOKEN=SERVER_AUTH_DISABLED",
-        "-e", "ALLOWED_ORIGINS=[\"http://127.0.0.1:8000\"]",
+        "--network=host",
+        "-v", "/home/user/.kube/config-local-k3s:/.kube/config-local-k3s:ro", // path to your kubeconfig file
+        "-e", "AUTH_ENABLED=false",
+        "-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",
         "-e", "SELENIUM_GRID__VNC_PASSWORD=CHANGE_ME",
         "-e", "SELENIUM_GRID__VNC_VIEW_ONLY=false",
         "-e", "SELENIUM_GRID__MAX_BROWSER_INSTANCES=4",
         "-e", "SELENIUM_GRID__SE_NODE_MAX_SESSIONS=1",
-        "-e", "KUBERNETES__KUBECONFIG=/kube/config-local-k3s",
+        "-e", "KUBERNETES__KUBECONFIG=/.kube/config-local-k3s", // path to your kubeconfig file
+        "-e", "KUBERNETES__USE_HOST_DOCKER_INTERNAL=true",
         "-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"
+        "-e", "FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=true",
+        "ghcr.io/catchnip/mcp-selenium-grid:latest"
       ]
     }
   }
@@ -210,13 +229,18 @@ API_TOKEN=CHANGE_ME uvx mcp-selenium-grid server run --host 127.0.0.1 --port 800
 Default args
 
 ```bash
-docker run -i --rm --init -p 8000:80 ghcr.io/falamarcao/mcp-selenium-grid:latest
+docker run -i --rm --init --network=host \
+  -v ~/.kube/config-local-k3s:/kube/config-local-k3s:ro \
+  -e KUBERNETES__KUBECONFIG=/kube/config-local-k3s \
+  ghcr.io/catchnip/mcp-selenium-grid:latest
 ```
 
 Custom args
 
 ```bash
-docker run -i --rm --init -p 8000:80 \
+docker run -i --rm --init \
+  --network=host \
+  -v ~/.kube/config-local-k3s:/kube/config-local-k3s:ro \
   -e API_TOKEN=CHANGE_ME \
   -e ALLOWED_ORIGINS='["http://127.0.0.1:8000"]' \
   -e DEPLOYMENT_MODE=kubernetes \
@@ -227,12 +251,16 @@ docker run -i --rm --init -p 8000:80 \
   -e SELENIUM_GRID__MAX_BROWSER_INSTANCES=4 \
   -e SELENIUM_GRID__SE_NODE_MAX_SESSIONS=1 \
   -e KUBERNETES__KUBECONFIG=/kube/config-local-k3s \
+  --add-host=host.docker.inte.rnal:host-gateway \
+  -e KUBERNETES__USE_HOST_DOCKER_INTERNAL=true \
   -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/catchnip/mcp-selenium-grid:latest
 ```
 
+> Note: All environment variables have default values.
+
 #### MCP Server configuration (mcp.json)
 
 ```json