feat: add extension support

Author: onderceylan

.gitignore

@@ -145,4 +145,5 @@ build/
 
 log.txt
 
-.DS_Store
+.DS_Store
+.idea

AGENTS.md

@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+TypeScript sources for the MCP server live in `src/`; `src/main.ts` bootstraps the server and `src/tools/` exposes Model Context Protocol tools. Shared helpers for logging, mutex control, trace processing, and formatting sit at the top level to keep concerns isolated. Tests belong in `tests/`, mirroring the source layout; `npm run build` emits JavaScript into `build/`, which should stay generated. Long-form docs live in `docs/`, and automation scripts sit in `scripts/`—always invoke them through npm scripts.
+
+## Build, Test, and Development Commands
+
+- `npm run build` — type-checks with `tsc` and writes output to `build/`.
+- `npm run start` — builds then runs `build/src/index.js`.
+- `npm run start-debug` — mirrors start with `DEBUG=mcp:*` enabled.
+- `npm run test` — builds and runs Node tests at `build/tests/**/*.test.js`.
+- `npm run test:only` — reruns only `.only` tests after a build.
+- `npm run format` — runs ESLint fixes plus Prettier.
+- `npm run docs` — rebuilds, regenerates docs, and formats results.
+
+## Coding Style & Naming Conventions
+
+Write strict TypeScript with ES modules and two-space indentation enforced by Prettier. Prettier also applies single quotes, no bracket spacing, trailing commas, and LF endings; run `npm run format` before committing. ESLint (`eslint.config.mjs`) requires license headers, consistent type-only imports/exports, alphabetized import blocks, and treats unused symbols without `_` prefixes as errors. Prefer named exports; reserve default exports for entry points such as `src/cli.ts`.
+
+## Testing Guidelines
+
+Place tests in `tests/**` with the `.test.ts` suffix to pick up the test-specific lint rules. Use `npm run test` for full runs, `npm run test:only` or `npm run test:only:no-build` when iterating, and `npm run test:update-snapshots` to refresh snapshots. Commit snapshot updates with their corresponding code.
+
+## Commit & Pull Request Guidelines
+
+Follow Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`) as seen in history, keeping each change scoped with matching tests or docs. PRs should include a concise summary, linked issues, and notes on how you tested; attach screenshots or CLI transcripts when user-visible behavior shifts.
+
+## Environment & Configuration Tips
+
+Use Node.js v22 per `.nvmrc` and the `engines` field. Manage dependencies with `npm`, avoid editing `node_modules/` or `build/` manually, and reach for `npm run start-debug` when you need verbose server logs.

CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Chrome DevTools MCP is a Model Context Protocol (MCP) server that allows AI coding assistants to control and inspect a live Chrome browser. It provides browser automation, debugging capabilities, and performance analysis through the Chrome DevTools protocol and Puppeteer.
+
+## Development Commands
+
+### Build and Type Checking
+
+- `npm run build` - Compiles TypeScript and runs post-build processing
+- `npm run typecheck` - Type checks without emitting files
+- `npm run format` - Runs ESLint with auto-fix and Prettier
+- `npm run check-format` - Lints and checks formatting without fixes
+
+### Testing
+
+- `npm test` - Builds and runs all tests
+- `npm run test:only` - Builds and runs tests marked with `test.only`
+- `npm run test:only:no-build` - Runs tests with `test.only` without rebuilding
+- `npm run test:update-snapshots` - Updates test snapshots
+
+### Documentation
+
+- `npm run docs` - Builds project and regenerates tool documentation
+- `npm run docs:generate` - Generates tool reference documentation only
+
+### Running the Server
+
+- `npm start` - Builds and starts the MCP server
+- `npm run start-debug` - Starts with debug logging enabled
+
+## Architecture
+
+### Core Components
+
+**Main Entry Point (`src/main.ts`)**
+
+- Sets up the MCP server using `@modelcontextprotocol/sdk`
+- Registers all tools from different categories
+- Uses a mutex to serialize tool execution
+- Handles browser initialization and context management
+
+**Browser Management (`src/browser.ts`, `src/McpContext.ts`)**
+
+- `resolveBrowser()` handles Chrome browser discovery and launching
+- `McpContext` manages browser instance, pages, network/console collectors
+- Supports connecting to existing browser instances or launching new ones
+
+**Tool System (`src/tools/`)**
+
+- Each tool category is in a separate file (input, pages, performance, etc.)
+- Tools use `ToolDefinition` interface with Zod schemas for validation
+- All tools are registered automatically in `main.ts`
+- Tool categories: Input automation, Navigation, Emulation, Performance, Network, Debugging
+
+**DevTools Integration**
+
+- Uses `chrome-devtools-frontend` package for trace processing and performance analysis
+- Heavy integration with Chrome DevTools models for performance insights
+- Custom formatters in `src/formatters/` for console, network, and snapshot data
+
+### Key Patterns
+
+**Page Management**
+
+- Uses `PageCollector` to track pages, network requests, and console messages
+- Maintains selected page state and handles page navigation
+- Each page has its own collectors for network and console data
+
+**Response Handling**
+
+- `McpResponse` class builds structured responses with text, images, and metadata
+- Tools can include page snapshots, network data, console logs automatically
+- Supports pagination for large datasets (network requests, console messages)
+
+**Performance Tracing**
+
+- `src/trace-processing/parse.ts` processes Chrome DevTools traces
+- Uses Chrome DevTools frontend models for analysis and insights
+- Stores trace results in context for later analysis
+
+### File Structure Highlights
+
+- `src/tools/` - All MCP tool implementations
+- `src/formatters/` - Data formatting utilities for different content types
+- `src/trace-processing/` - Performance trace analysis
+- `tests/` - Comprehensive test suite with snapshots
+- `scripts/` - Build and documentation generation scripts
+
+## Configuration
+
+The project uses modern TypeScript with ES modules (`"type": "module"` in package.json). Key configurations:
+
+- **Node.js**: Requires >= 22.12.0
+- **TypeScript**: Targets ES2023 with bundler module resolution
+- **ESLint**: Flat config with TypeScript, import, and stylistic rules
+- **Testing**: Node.js test runner with custom setup and snapshots
+
+## Extension Support
+
+The server now supports loading Chrome extensions during browser launch:
+
+- **EXTENSION_PATH** - Set this environment variable to automatically load an unpacked extension
+- Extensions are loaded with activity logging enabled for debugging
+- Use extension debugging tools: `extension_get_logs`, `extension_simple_test`
+
+## Development Notes
+
+- All tools must be thread-safe due to mutex serialization
+- Heavy use of Chrome DevTools frontend types and utilities
+- Network conditions and CPU throttling are supported for emulation
+- Browser user data is persistent by default (use `--isolated` for temporary)
+- Debug logging available via `DEBUG=*` environment variable