js-reverse-mcp: Instructions file for Claude Code

CLAUDE.md

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

Build and Development Commands

# Install dependencies
npm ci

# Build the project (TypeScript compilation + post-build scripts)
npm run build

# Run all tests
npm test

# Run a single test file (after building)
node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test "build/tests/path/to/test.test.js"

# Run only tests marked with { only: true }
npm run test:only

# Update test snapshots
npm run test:update-snapshots

# Type checking without emitting
npm run typecheck

# Lint and format
npm run format

# Check formatting without fixing
npm run check-format

# Start the MCP server (builds first)
npm run start

# Start with debug logging
npm run start-debug

# Generate documentation (after changing tools)
npm run docs

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node build/src/index.js

Architecture Overview

This is an MCP (Model Context Protocol) server that exposes Chrome DevTools functionality to AI coding assistants via Puppeteer.

Core Components

• src/main.ts: Entry point. Creates the MCP server, registers all tools, and handles tool execution with mutex-based serialization.

• src/McpContext.ts: Central state management class. Maintains:

  • Browser and page state (selected page, page list)
  • Accessibility tree snapshots for element interaction
  • Network and console collectors
  • Debugger context for script/breakpoint management
  • Performance trace state

• src/McpResponse.ts: Response builder that tools use to construct their output (text, images, snapshots, network data, console data).

• src/browser.ts: Browser lifecycle management. Handles launching new Chrome instances or connecting to existing ones via browserURL/wsEndpoint.

Tool System

Tools are defined in src/tools/ using the defineTool() helper from src/tools/ToolDefinition.ts. Each tool has: