Thank you for your interest in contributing to MCP Selenium Grid!
When reporting issues, please include:
- A clear and descriptive title
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Environment details (OS, Python version, etc.)
- Any relevant logs or error messages
- Follow the existing code style and formatting
- Use type hints for all function parameters and return values
- Write docstrings for all public functions and classes
- Keep functions small and focused on a single responsibility
- Write tests for new features and bug fixes
- Ensure all tests pass before submitting a pull request
- Include unit, integration, e2e tests where appropriate
-
Fork the repository
mainbranch - Click the "Fork" button on GitHub -
Clone your repository to local using ssh -
git clone git@github.com:YourGitHubUserName/mcp-selenium-grid.git -
Install the pre-commit hooks
- This project uses pre-commit hooks configured in
.pre-commit-config.yamlfor automated code quality checks. When fresh cloned and when.pre-commit-config.yamlis updated, run:
uv run pre-commit install && uv run pre-commit autoupdate && uv run pre-commit run --all-files
- This project uses pre-commit hooks configured in
-
Create a feature branch - Use a descriptive branch name (be creative):
git checkout -b feature/amazing-feature git checkout -b fix/bug-description git checkout -b docs/update-readme
-
Make your changes - Write clean, well-documented code
-
Run and write tests - Ensure everything works
-
Commit your changes - Write clear, descriptive commit messages
-
Make sure that your branch is updated with
mainbranch - keep a linear commit history, rebase if necessary -
Push to your branch
-
Open a Pull Request - Fill out the PR template
- Use emojis to make commits more readable and fun! 🎉
- Use AI tools to generate commit messages
Examples:
✨ feature: Add Kubernetes deployment support
🐛 fix: browser instance cleanup on shutdown
📝 docs: Update MCP client configuration examples
♻️ refactor: split selenium hub logic into separated classes
✅ test: Add integration tests for browser workflowFor bigger changes:
✨ feature: Add Kubernetes deployment support
- Add Helm charts for Selenium Grid deployment
- Support for multiple Kubernetes contexts
- Automatic namespace creation and cleanup
- Health checks and monitoring integration# Clone the repository
git clone git@github.com:catchnip/mcp-selenium-grid.git
cd mcp-selenium-grid
# Create a virtual environment and install dev/test dependencies
uv sync --all-groups --extra testThis project requires a Kubernetes cluster for running tests and managing browser instances. We use K3s for local development and testing.
3.1 Install K3s (https://docs.k3s.io/quick-start)
# Install K3s
curl -sfL https://get.k3s.io | sh -
# Verify installation
k3s --version
# Start if not running
sudo systemctl start k3sAfter installing K3s, you might want to create a dedicated kubectl context for it:
# Copy K3s kubeconfig
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config-local-k3s
sudo chown $USER:$USER ~/.kube/config-local-k3s
chmod 600 ~/.kube/config-local-k3s
# Create context
KUBECONFIG=~/.kube/config-local-k3s \
kubectl config set-context k3s-selenium-grid \
--cluster=default \
--user=default# 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
# Deploy with specific context
uv run mcp-selenium-grid helm deploy --context k3s-selenium-grid
# Uninstall
uv run mcp-selenium-grid helm uninstall --delete-namespace# See command help
uv run mcp-selenium-grid server --help
uv run mcp-selenium-grid server run --help
uv run mcp-selenium-grid server dev --help
# Start server
uv run mcp-selenium-grid server run
uv run mcp-selenium-grid server run --host 127.0.0.1 --port 9000 --log-level debug
# Development mode with auto-reload
uv run mcp-selenium-grid server dev
# Using FastAPI Cli (auto-reload)
uv run fastapi dev src/app/main.py
# Using FastAPI Cli (no auto-reload)
uv run fastapi run src/app/main.py# Run all tests
uv run pytest
# Run specific test types
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m e2e
# Run with coverage
uv run scripts/rich-coverage.py
uv run scripts/rich-coverage.py --format=htmlUse MCP Inspector to inspect the mcp server mcp-dev.json
npx @modelcontextprotocol/inspector --config mcp-dev.json --server prodnpx @modelcontextprotocol/inspector --config mcp-dev.json --server prod-k8snpx @modelcontextprotocol/inspector --config mcp-dev.json --server devdocker build -t ghcr.io/catchnip/mcp-selenium-grid:latest .npx @modelcontextprotocol/inspector --config mcp-dev.json --server dockerRequires node installed. I recommend using VOLTA - The Hassle-Free JavaScript Tool Manager
- To test GitHub Actions workflows locally, see
.github/workflows/README.mdfor 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
uv run ruff check . # Lint
uv run mypy . # Type check
uv run ruff format . # FormatThis project uses pre-commit hooks configured in .pre-commit-config.yaml for automated code quality checks. If .pre-commit-config.yaml is updated, run:
uv run pre-commit install && uv run pre-commit autoupdate && uv run pre-commit run --all-filesInstalls hooks, updates them to latest versions, and runs all hooks on all files.
uvx pyclean . # Clear pycache
uv run ruff clean # Clear ruff cache- 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>
By contributing to MCP Selenium Grid, you agree that your contributions will be licensed under the MIT License.