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. Version 2.0.0 adds 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)
• 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 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.