Skip to content

Latest commit

 

History

History
106 lines (68 loc) · 3.45 KB

CLAUDE.md

File metadata and controls

106 lines (68 loc) · 3.45 KB

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:

  • name: Tool identifier
  • description: For MCP clients
  • annotations: Category and read-only hint
  • schema: Zod schema for input validation
  • handler: Implementation that receives request, response builder, and context

Tool categories are defined in src/tools/categories.ts and can be disabled via CLI flags (e.g., --categoryNetwork=false).

Data Collection

  • src/PageCollector.ts: Base class for collecting page events. Extended by NetworkCollector and ConsoleCollector to track requests and console messages across pages.

  • src/formatters/: Convert collected data to text format for MCP responses.

Third-Party Integration

  • src/third_party/index.ts: Re-exports from bundled dependencies (puppeteer, @modelcontextprotocol/sdk, zod).

  • chrome-devtools-frontend: Used for performance trace analysis and issue descriptions. Included via tsconfig.json.

Testing

Tests use Node.js built-in test runner. Test files mirror source structure under tests/. Snapshots are stored alongside test files with .snapshot extension.

  • tests/setup.ts: Configures snapshot paths and serializers
  • tests/server.ts: Test utilities for MCP server testing
  • tests/utils.ts: Shared test helpers

Conventions

  • Follow conventional commits for PR and commit titles
  • Run npm run docs after adding or modifying tools to update documentation
  • Node version: v22 (see .nvmrc)