mcp-selenium: Instructions file for Codex

AGENTS.md

MCP server for Selenium WebDriver browser automation. JavaScript (ES Modules), Node.js, stdio transport (JSON-RPC 2.0).

File Map

src/lib/server.js                ← ALL server logic: tool definitions, state, helpers, cleanup
src/lib/accessibility-snapshot.js ← Browser-side JS injected via executeScript to build accessibility tree
bin/mcp-selenium.js              ← CLI entry point, spawns server.js as child process
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 scripts in separate files. 18 tools, 2 resources.

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.