v0.8.2 — path confinement (CWE-22) security fix

Security

• Confine caller-supplied write destinations to the browse-mcp data roots (CWE-22, reported privately by novice-22). browser_download's save_dir is now resolved under ~/.browse-mcp/downloads and browser_save_state / browser_load_state's explicit path under ~/.browse-mcp/state; absolute paths and .. escapes are rejected, and download filenames are reduced to a bare basename. Previously a caller (a malicious MCP client, or an agent steered by indirect prompt injection) could pass an arbitrary save_dir and a URL whose body became the file contents, writing attacker-controlled bytes to any path (e.g. ~/.bashrc). Relocate the roots with BROWSE_MCP_HOME. The force_fetch fallback now also honours BROWSE_MCP_ALLOWED_ORIGINS / BROWSE_MCP_BLOCKED_ORIGINS, which its raw fetch() previously bypassed.

Full changelog: https://github.com/That1Drifter/browse-mcp/blob/v0.8.2/CHANGELOG.md

v0.8.1 — docs correction + stealth opt-out

Added

• BROWSE_MCP_NO_STEALTH=1: opt out of the navigator.webdriver strip for operators whose target sites'' ToS expect automation to identify itself.

Fixed

• README no longer claims Readability is "fetched from unpkg at runtime" — it has been bundled via the @mozilla/readability npm dependency since 0.3.0 (no runtime network fetch, works offline). Stale claim flagged by external review; the npm package page now shows the corrected docs.

v0.8.0 — CLI mode

Added

• CLI mode (#41): npx browse-mcp read|search|research ... runs the same core as the MCP tools but writes results to stdout, a token-light path for shell-capable agents. read handles HTML and PDFs; search covers web/news/images; research emits one concatenated document.
• Attaches to a running server''s browser when the server is started with BROWSE_MCP_CDP (opt-in localhost CDP port; see SECURITY.md); otherwise launches its own browser on the shared profile, ephemeral when locked.
• No arguments still starts the MCP server, so existing client configs are unaffected.

Full details in CHANGELOG.md.

v0.7.0 — per-session isolated contexts

Added

• browser_context (#39): open/switch/close/list named incognito-style contexts that share nothing with the persistent profile. All tools act on the active context; the stealth script and origin fence apply per context. Pair with browser_load_state to inject scoped auth into a clean context. In-memory only; lost on browser_close/browser_handoff.

Full details in CHANGELOG.md.

v0.6.0 — interaction completeness, PDFs, proxy, origin fence, state portability

Added

• browser_handle_dialog: arm accept/dismiss (+ prompt text) for upcoming dialogs, or report recent ones. Unarmed dialogs auto-dismiss and feed the issues log (#34).
• browser_select_option, browser_file_upload, browser_navigate_back/forward, browser_drag (#35).
• PDF text extraction: browser_read takes .pdf URLs or local paths; browser_research reads PDF results instead of skipping them (#36).
• BROWSE_MCP_PROXY / BROWSE_MCP_PROXY_BYPASS proxy passthrough and BROWSE_MCP_ALLOWED_ORIGINS / BROWSE_MCP_BLOCKED_ORIGINS navigation fence with a route backstop (#37).
• browser_save_state / browser_load_state: move cookies + localStorage between machines as a JSON file (#38).
• Opt-in coordinate mouse tools (vision bundle): browser_click_xy / move_xy / drag_xy for empty-a11y-tree pages (#40).

Full details in CHANGELOG.md.

v0.5.0 — client-agnostic + page-context errors

Added

• Timeout and not-found errors from browser_wait_for / browser_wait_for_text / browser_find_text now include page context (URL, readyState, title, body excerpt) plus a browser_handoff hint on CAPTCHA/Cloudflare interstitials.
• networkidle waits that time out explain that the state often never fires and suggest alternatives.

Changed

• Repositioned as client-agnostic: registration docs for Codex CLI, Gemini CLI, Cursor, and VS Code alongside Claude Code / Claude Desktop, plus a Windows/Linux/macOS support matrix.
• CI builds and tests on Windows and macOS in addition to Ubuntu.

Fixed

• MCP server metadata reports the real package version (was hardcoded 0.1.0).
• Lint clean: caught errors attached as cause, dead code removed, unused imports dropped.

Full details in CHANGELOG.md.

v0.4.1

Fixed

• postinstall script now runs playwright install chromium so the Chromium binary is fetched at install time instead of erroring on first browser call with Executable doesn't exist at .../chrome-headless-shell.exe. Removes the manual npx playwright install chromium step from the source-install path (#29).

Full changelog: v0.4.0...v0.4.1

v0.4.0 — Search resilience overhaul + CSP fix + href_pattern fix

Release notes for 0.4.0 (2026-05-27). See CHANGELOG.md for the full structured entry.

Added

• BROWSE_MCP_TAVILY_API_KEY opt-in Tavily Search provider (1000 req/mo free, AI-curated). Tried after Brave in the search provider chain. (#27)
• Playwright-rendered DDG/Bing fallback for browser_search. When the fetch-based scrape returns 0 (anti-bot interstitial or layout drift), the search reruns inside the real browser context and parses the live DOM. Layered chain: Brave (key) → Tavily (key) → fetch DDG → fetch Bing → rendered DDG → rendered Bing. (#24)
• Structured difficulty log entries with 600-char htmlExcerpt, page title, and URL when rendered DDG/Bing fallbacks return 0 results. Visible via browser_review_issues for drift debugging without a live repro. (#26)

Fixed

• browser_extract_listings({ href_pattern: "/inventory/used" }) no longer throws Invalid flags supplied to RegExp constructor 'used'. href_pattern is now treated as a substring by default; the value is only parsed as a regex when wrapped in /.../flags AND flags validate against /^[gimsuy]*$/. Applied symmetrically to browser_links. (#22)
• browser_read no longer fails with Refused to execute inline script on github.com, Cloudflare-challenged pages, and any site with strict script-src CSP. Readability source now runs through page.evaluate(<string>) (CDP Runtime.evaluate, which bypasses CSP) instead of page.addScriptTag which injects a real <script> element. (#23)

Changed

• FRAGILITY NOTICE in src/search.ts and the README search section now lead with the API-key recommendation. The scrape rungs are documented as a best-effort backstop; the new fallback chain and telemetry are documented as the response to Cloudflare / TLS-JA3 fingerprinting that increasingly blocks Playwright clients.

Recommended setup for new installs

For reliable search, set one of:

Provider	Free tier	Env var
Brave Search API	~1k req/mo on the free credit	BROWSE_MCP_BRAVE_API_KEY
Tavily Search	1000 req/mo, AI-curated	BROWSE_MCP_TAVILY_API_KEY

Either is sufficient. The scrape fallback still works for zero-config installs.

v0.3.0

Published to npm: browse-mcp@0.3.0

Added

• BROWSE_MCP_EPHEMERAL=1 runs Chromium without a persistent profile (no cookies/localStorage/tokens written to disk). browser_reset_profile no-ops under ephemeral mode.
• BROWSE_MCP_BRAVE_API_KEY opt-in Brave Search API fallback for web search; no-key behavior unchanged (DDG/Bing scrape).
• Search endpoints log structured issues to browser_review_issues when parsers return 0 results (likely layout change).
• SECURITY.md documenting persistent-profile risks, threat model, and mitigations.
• ROADMAP.md with near-term priorities toward 1.0.
• VERSIONING.md documenting the project's semver contract.
• CHANGELOG.md following Keep a Changelog structure.
• vitest test suite (50 unit tests covering search parsing, readability-to-markdown, diff, snapshot rendering, inspect formatting); npm test now runs in CI on Node 20/22.
• ESLint (flat config, typescript-eslint) + Prettier, with lint, format, format:check scripts. Lint runs in CI (non-blocking initially).
• README "Project status" section.

Changed

• Bundled @mozilla/readability as a dependency instead of fetching from unpkg at runtime. browser_read no longer requires network access for the Readability library.
• Split the 1081-line src/index.ts into per-category modules under src/tools/ (navigation, snapshot, content, search, debug, edit, session, issues) + thin 120-line dispatcher. Tool behavior identical.
• Improved search error messages (layout-change diagnostics, Brave API hint).

Full diff: v0.2.1...v0.3.0

v0.2.1 — first public release

First public release of browse-mcp.

Highlights

• 37 tools — navigation, snapshotting, interaction, search, content extraction, multi-tab, a11y, CSS inspection, visual diffing
• browser_research — single call: search → read top N → concatenated Markdown
• browser_read — Mozilla Readability article extraction
• browser_search / _news / _images — DuckDuckGo + Bing fallback, no API key
• Persistent Chromium profile — OAuth/MFA/CAPTCHA survive across sessions
• Self-improvement loop — tool errors auto-log to ~/.browse-mcp/issues.jsonl
• BROWSE_MCP_TOOLS env filter — named bundles + explicit names, for clients that can't lazy-load the full schema

Install

npx browse-mcp

Or from source — see the README.

Schema budget

All 37 tools: ~4.9K tokens / 19.5 KB of schema. Use BROWSE_MCP_TOOLS to restrict for token-constrained clients.