mcp-camoufox: Instructions file for Codex

mcp-camoufox — Agent Guide

This guide applies to the entire repository and is the shared source of instructions for coding agents. Its purpose is not to govern every decision, but to preserve the workflows and invariants that are easy to miss — most of them were learned from a shipped bug. Developer requests may override working defaults; hard constraints may only be overridden when the developer explicitly asks for it.

Product and repository map

An MCP server (stdio JSON-RPC) that gives an agent a stealth browser: 133 tools over Camoufox, a Firefox build with C++-level anti-fingerprinting. Published on npm as mcp-camoufox.

npx -y mcp-camoufox → Node → camoufox-js → Playwright (Juggler) → Camoufox Firefox
                           └→ impit (Firefox JA4 TLS) → browserless HTTP path

• src/index.ts — entry: connects stdio, imports the tool modules.
• src/state.ts — the single mutable record S, page bookkeeping, shared capture buffers.
• src/helpers.ts — refs, clicks, fills, snapshots, paths, TOTP.
• src/server.ts — the McpServer instance and the regTool registry.
• src/tools/*.ts — the tools, grouped by area; each registers itself on import.
• scripts/test/ — the regression suites; scripts/*.mjs — release checks.
• docs/TOOLS.md — the authoritative tool reference. README.md — the summary and the pitch.
• docs/images/ — proof screenshots.
• Runtime data lives outside the repo: ~/.camoufox-mcp/{profile,screenshots,sessions}.

Hard constraints

• Never commit or print a credential. The npm token is set into ~/.npmrc immediately before npm publish and deleted immediately after; .npm-token and *.tgz stay ignored.
• Never publish from the working tree alone. A release is only verified once npm run smoke:install has installed the published package and driven a real browser.
• playwright-core must stay pinned <1.61.0. Playwright 1.61+ sends isMobile in Browser.setDefaultViewport, which Camoufox's Juggler schema rejects, and camoufox-js declares the peer as "*". Unpinning breaks browser_launch for every fresh install while this tree keeps working.
• Do not weaken a security property to make a test pass: secret field values never leave the browser, credential files are written 0600, name parameters never escape their directory, and browser cookies are recomputed per redirect hop.
• Do not add a tool that can fail silently. If an action may not have taken effect, the response says so — see the click/wait invariants below.
• reset_profile, browser_recover and anything that deletes a profile need an explicit request; the shared profile holds the developer's real logins.