mcp-ie-migration-vrt: Instructions file for Codex

AGENTS.md

MCP server for Selenium WebDriver browser automation and paired IE-to-Edge visual regression testing. JavaScript (ES Modules), Node.js, stdio transport (JSON-RPC 2.0).

File Map

src/lib/server.js                 ← Server logic: tools, sessions, VRT orchestration, cleanup
src/lib/accessibility-snapshot.js ← Browser-side JS injected via executeScript to build accessibility tree
src/vrt/                          ← Playwright Test PNG comparison runner and config
bin/mcp-ie-migration-vrt.js       ← Package entry point
skills/ie-migration-vrt/          ← Agent workflow for paired-session comparison and repair
test/mcp-client.mjs              ← Reusable MCP test client (JSON-RPC over stdio)
test/*.test.mjs                  ← Tests grouped by feature
test/fixtures/*.html             ← HTML files loaded via file:// URLs in tests

Architecture

Server logic lives in server.js, with browser-injected and Playwright comparison scripts in separate files. Existing Selenium tools accept an optional sessionId; start_vrt_browsers and vrt provide the paired-session workflow.

State is a module-level object:

const state = {
    drivers: new Map(),    // sessionId → WebDriver instance
    currentSession: null,  // active session ID
    bidi: new Map()        // sessionId → { available, consoleLogs, pageErrors, networkLogs }
};

Related operations are consolidated into single tools with action enum parameters (interact, window, frame, alert, diagnostics). This is intentional — it reduces context window token cost for LLM consumers.

BiDi (WebDriver BiDi) is auto-enabled on start_browser for passive capture of console logs, JS errors, and network activity. Modules are dynamically imported — if unavailable, BiDi is silently skipped.

Conventions

• ES Modules — import/export, not require.
• Zod schemas — tool inputs defined with Zod, auto-converted to JSON Schema by MCP SDK.
• Error pattern — every handler: try/catch, return { content: [...], isError: true } on failure.
• No console.log() — stdio transport. Use console.error() for debug output.
• send_keys clears first — calls element.clear() before typing. Intentional.
• MCP compliance — before modifying server behavior, read the MCP spec. Don't violate it.