Contributing
Bug reports, fixes, docs, and new tools are all welcome. The contribution guidelines cover the workflow; this page is the practical setup.
Set up
git clone https://github.com/adityasasidhar/browsercontrol
cd browsercontrol
uv sync # runtime and dev dependencies
uv run playwright install chromium # the browser engine
uv run pre-commit install # lint and format on commitRun the server with the MCP inspector:
uv run fastmcp dev browsercontrol/server.pyChecks
make help lists every shortcut. make check runs lint, type checks, and tests together.
| Check | Command |
|---|---|
| Tests | uv run pytest |
| One test | uv run pytest tests/test_navigation.py::TestScroll::test_scroll_down_medium |
| Lint and format | uv run ruff check . && uv run ruff format . |
| Types (strict) | uv run mypy browsercontrol/ |
| Security | uv run bandit -c pyproject.toml -r . --exclude ./tests,./.venv |
| Every hook | uv run pre-commit run --all-files |
Most tests mock Playwright and run in seconds. Two files drive a real headless browser against local pages: tests/test_som_real_browser.py (run it after touching element detection) and tests/test_features_real_browser.py (sessions, emulation, codegen, and the tools that use them). They're skipped when no browser is available.
CI runs lint first, then tests on Python 3.11 and 3.14 on Linux, Windows, and macOS (and 3.12 and 3.13 on Linux), plus bandit and mypy.
Pre-commit also runs actionlint on the GitHub Actions workflows, uv-lock to keep uv.lock in sync, a max-lines check (800 per file), and Tach on imports: the browser core (browser.py, elements.py, session.py, …) must not import from tools/ or server.py, and tools/ must not import server.py. The server imports and registers everything (tach.toml).
Commits and pull requests
- Conventional Commits for commits and PR titles:
feat:,fix:,docs:,chore:… - Sign off every commit with
git commit -s(DCO); CI rejects commits without it. - Explain the user-visible change, link related issues, and include tests, plus docs when an interface changes.
Add a tool
- Put it in the matching module under
browsercontrol/tools/and decorate it with@mcp.tool(). Its docstring and parameter descriptions are what clients see, so make them actionable. - Start with
await browser.ensure_started(). Resolve elements withawait browser.resolve_element(id)and catchElementErrorwithelement_error_result. Never act at stored coordinates. - Return
tuple[str, Image]built withget_screenshot_with_summary(browser)if the tool changes the page, orstrif it only reads. - For element actions, call
browser.codegen_target(locator)before acting andbrowser.log_action(...)after, soexport_testcan reproduce it. Add a step toactif it makes sense in a batch. - List it in the server
instructionsinserver.py(tests/test_server.pychecks they match). - Test the happy path and the error path, following the existing per-module test files.
- Regenerate the tool catalog and document it (next section).
Work on these docs
The site is VitePress with the Catppuccin theme, in docs/.
cd docs
npm ci
npm run dev # live preview at http://localhost:5173/browsercontrol/
npm run build # production build in docs/.vitepress/dist
npm run check:links # every internal link and #anchor in the build resolves- Tool catalog.
docs/public/tools.jsonis generated from the server and drives the tool explorer. After changing a tool, runuv run python scripts/gen_tools_json.py. A test fails while it's stale, and another checks that every tool and parameter appears indocs/reference/. - Pages. Each page has a
descriptionin its frontmatter; it's used in search results, social previews, andllms.txt. - Components.
<Mark n="7">Submit</Mark>draws an inline numbered mark;<CardGrid>and<Card>make link cards;<div class="steps">numbers its###headings like marks. - Agents.
llms.txt,llms-full.txt, and a.mdversion of every page are generated at build time. Wrap text meant only for agents in<llm-only>.
Release
Pushing a v* tag runs .github/workflows/release.yml: it re-runs the checks, builds, publishes to PyPI through Trusted Publishing, and opens a GitHub release.
The version lives in pyproject.toml, but the plugin manifests carry their own copy. A release bumps all of them in one commit:
| File | What to change |
|---|---|
pyproject.toml, uv.lock | uv version --bump minor (or patch / major) updates both. |
plugin.json, package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json | Set version to the same value. |
server.json | Set both version fields (the server and its PyPI package). The release job publishes it to the MCP Registry after PyPI. |
CHANGELOG.md | Move the [Unreleased] entries under a new ## [X.Y.Z] - YYYY-MM-DD heading, and add its compare link at the bottom. |
tests/test_version.py fails if any manifest disagrees with pyproject.toml. The package's __version__ and the HAR creator version read the installed package metadata, so they need no edit.
Release through a pull request like any other change, then tag the merge commit:
git checkout -b release/vX.Y.Z
# bump the files above
git commit -s -am "chore: release X.Y.Z"
git push -u origin release/vX.Y.Z # open a PR and merge it
git checkout main && git pull
git tag vX.Y.Z
git push origin vX.Y.ZThe tag must match project.version in pyproject.toml, and the workflow refuses a version that already exists on PyPI.
