blowsh-mcp: Instructions file for Codex

blowsh-mcp — Project Context Hub

Project Overview

blowsh-mcp is a Model Context Protocol (MCP) server that exposes Browsh — a fully JavaScript-capable terminal browser backed by headless Firefox — to AI agents. It renders any modern web page after full JS execution and returns plain text, HTML, or Markdown. Current version is 2.6.0 (see CHANGELOG.md); 2.0.0 added web search, link extraction, batch fetching, structured extraction, an SSRF guard, and a TTL render cache.

Tech stack: TypeScript 7 (strict, NodeNext ESM), Node.js >= 20.18, @modelcontextprotocol/sdk 1.30, zod 4, axios, cheerio, html2markdown CLI (external binary), Browsh CLI + Firefox (external binaries), Docker (multi-stage fat image).

Setup & Dev Commands

• Build: npm run build (tsc, outputs dist/)
• Start: node dist/server.js (stdio MCP transport, default)
• Singleton HTTP: MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8107 node dist/server.js (in Docker; host publish stays -p 127.0.0.1:8107:8107)
• Dev: npm run dev (tsx watch-less runner)
• Docker build: docker build -t blowsh-mcp:latest .
• Docker run (MCP over stdio — MUST include -i): docker run --rm -i blowsh-mcp:latest
• Verify: build, docker build, then an MCP JSON-RPC smoke test over stdio (initialize → tools/list → tools/call)
• Lint: none configured; strict tsc is the gatekeeper

Actionable Guardrails (Do's & Don'ts)

• Don't run the server directly on this machine for fetch tests — Firefox/Browsh/html2markdown are NOT installed locally. -> Do test through Docker: docker run --rm -i blowsh-mcp:latest.
• Don't use firefox-esr as a bare binary name for Browsh — it resolves /usr/bin/firefox-esr only. -> Do set BROWSH_FIREFOX_PATH=/usr/bin/firefox-esr in the Dockerfile (already done).
• Don't return error strings as successful tool results — tools must throw FetchError so MCP responds with isError: true. -> Do propagate FetchError (with HTTP status when known) and let server.ts format it.
• Don't bypass the SSRF guard (assertSafeUrl) when adding new fetch paths. -> Do call assertSafeUrl(url) before any URL reaches Browsh.
• Don't execute Git commands like git add, git commit, or git push autonomously or try to guess when to stage code. -> Do execute Git commands ONLY when explicitly instructed by an Orchestrator task block. Otherwise, rely on the custom_context_stage_and_inject_diff MCP tool. -> Exception: git mv is permitted autonomously for moving task files between Kanban directories (backlog, in-progress, qa, completed, archive).
• Don't read context-reports/ markdown files yourself. -> Do generate them using the MCP server — context reports via custom_context_read_source_files, tree reports via custom_context_create_tree_report ("create a tree of the project") — and hand the file path to the Manager.
• Don't guess blindly when facing complex bugs, deadlocks, or silent timeouts. -> Do utilize the debug-instrumentation skill to inject strategic logs and trace the runtime execution path.
• Don't write bash scripts without strict mode or mask errors with 2>/dev/null on data commands. -> Do follow the Defensive Shell Protocol: set -euo pipefail, ban error masking, sidecar isolation for Docker backups. See docs/conventions.md.
• Don't perform financial mutations without snapshotting the prior state or allow nulls in monetary aggregations. -> Do follow the Universal Financial Ledger Standard: snapshot-on-write, $ifNull precedence, discrepancy alerting, deep config merging. See docs/conventions.md.
• Don't leave task numbers in visible prompt prose, section headings, or skill instructions. -> Do keep task-number references in code comments, CHANGELOG entries, task files, history archives, and HTML comments only. See docs/conventions.md.
• Don't carry over assumptions, partial results, or architectural hypotheses from a previous task. -> Do flush context and treat every task as contextually independent (Buffer Isolation directive in validation-phase).
• Don't execute raw, informal, or non-English (Farsi) prompts directly. -> Do load the prompt-refactor skill to translate and expand the intent into an elite English spec first. (Note: If you receive a standard XML task block, skip this and execute normally).
• Don't attempt to resolve cross-disciplinary ambiguity within a single persona. -> Do trigger the Multi-Agent Brainstorming Loop if the Manager explicitly requests brainstorming or a task exhibits cross-disciplinary ambiguity. Interpret the <brainstorming_session> results in backlog tasks as non-functional guidelines that govern execution.