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.

Commands

npm run bundle      # Build: clean + tsup + make executable + create .tgz
npm run lint        # ESLint (--fix) + TypeScript type-checking (tsc --noEmit)
npm test            # Run all unit tests (vitest run; env: happy-dom)
npm run dev         # Development server (tsx --watch) — picks up code changes automatically; rebundle only needed for npm package changes
npm run dev:http    # Dev server with HTTP transport (for browser-based MCP clients)
npm start           # Run built server from lib/server.js
npm run start:http  # Built server with HTTP transport (for browser-based MCP clients)

# Single test file / focused run (vitest is not exposed via an npm script):
npx vitest run tests/tools/get-elements-tool.test.ts   # one file
npx vitest run -t "filter pattern"                      # tests matching a name
npx vitest tests/trace/                                 # watch mode for a directory

# Type-check. Use the repo-pinned TypeScript, not a plain `tsc` from PATH — a global
# TypeScript 7 rejects this repo's tsconfig (`baseUrl` removed) and reports TS5102
# instead of any real error.
./node_modules/.bin/tsc --noEmit

vitest.config.ts sets environment: 'happy-dom'. Its typecheck.tsconfig names a tsconfig.test.json that is not in the repo, so tsc --noEmit — which covers tests/ via the root include — is the real type gate.

Architecture

src/
├── server.ts          # MCP server entry — registers all tools + resources
├── session/           # Session state (state.ts) + lifecycle (lifecycle.ts)
├── providers/         # SessionProvider implementations
│   ├── registry.ts    # getProvider() — routes to local or cloud provider
│   ├── local-browser.provider.ts  # Chrome/Firefox/Edge/Safari
│   ├── local-appium.provider.ts   # iOS/Android via Appium
│   └── cloud/
│       ├── browserstack.provider.ts  # BrowserStack (browser + App Automate)
│       ├── saucelabs.provider.ts     # Sauce Labs (browser + App Storage)
│       ├── testmu.provider.ts        # TestMu / LambdaTest (browser + mobile)
│       ├── testingbot.provider.ts    # TestingBot (browser + mobile + Storage)
│       └── digitalai.provider.ts     # Digital.ai Testing (browser + mobile; accessKey cap, deviceQuery)
├── trace/             # Playwright-compatible trace recording (recorder.ts, tool-mapping.ts, zip-writer.ts)
├── tools/             # One file per MCP tool (see Tool Pattern below); includes the Electron
│                       #   surface (electron-execute, electron-deeplink), mocking, and web extensions
├── resources/         # One file per MCP resource (see Recording below)
├── recording/         # step-recorder.ts (withRecording HOF) + code-generator.ts
├── scripts/           # Browser/mobile scripts executed via browser.execute() — no try/catch, raw data only
├── locators/          # Element detection, selector generation, XML parsing (mobile)
├── config/            # appium.config.ts — iOS/Android capability builders
├── utils/             # auth.ts, parse-args.ts, http-helpers.ts, zod-helpers.ts (coerceBoolean),
│                       #   docs-index.ts + docs-client.ts (docs corpus)
└── types/             # ToolDefinition, ResourceDefinition, RecordedStep interfaces