camoufox-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

This is a TypeScript-based MCP (Model Context Protocol) server that provides browser automation capabilities using Camoufox (a privacy-focused Firefox fork). The server exposes browser tools with bounded output and extensive privacy controls:

• camoufox_status: return server, browser, queue, session, policy, and network-security posture status.
• browse: navigate once and return bounded text, HTML, metadata, diagnostics, and optional screenshot output.
• browse_snapshot: navigate once and return bounded visible text, ARIA snapshot data, and interactive element metadata.
• browse_sequence: navigate once, run a bounded CSS-selector action sequence, then return final content, snapshot data, diagnostics, and optional screenshot output.
• browse_links, browse_forms, browse_outline, browse_find: low-context page extraction tools.
• browse_screenshot, browse_console, browse_network_summary: focused screenshot and diagnostics tools.
• browse_session_*: short-lived isolated browser sessions with challenge pause/resume, best-effort attempt metadata, and optional LLM-assisted provider playbooks when CAPTCHA_AUTONOMOUS=true.

Commands

Development

Repository builds require Node >=22.15 and the optional launcher installed with npm install --include=optional for its TypeScript declarations. The published default runtime supports Node >=22.0 without that launcher.

• npm run build - Clean and compile TypeScript to dist/
• npm run dev - Watch mode for TypeScript compilation
• npm start - Run the compiled server
• npm run lint - Run ESLint checks via package script (or npx eslint src/)
• npm run fetch:camoufox - Download/fetch the Camoufox browser binaries
• npm run doctor - Run preflight sanity/diagnostic checks on Node, playwright-core, and cached browser versions
• Public package commands: camoufox-mcp-fetch and camoufox-mcp-doctor. Global installs of 2.6.0 expose them directly. After 2.6.0 is published, use npx --yes --package [email protected] <command> for npx installs. Preserve the server's compatibility flag and install-directory environment for both commands.
• npm test - Build and run Python test client locally (shortcut for npm run test:local)
• npm run test:unit - Build and run deterministic policy, sequence, snapshot, browser, and SQLite unit tests
• npm run test:local - Build and run Python test client locally against the local server
• npm run test:camoufox - Fetch the browser binary and run the local client tests
• npm run test:all - Comprehensive quality pipeline: lint, audit, unit tests, fetch, and client tests