feat: add dynamic session management for multiple browser instances

[awsmadi]

Summary

Adds session management support to chrome-devtools-mcp, enabling agents to work with multiple browser instances simultaneously. Sessions can be launched (new browser process) or connected (attach to existing browser via URL/WebSocket), switched between by ID or name, and independently closed — all through 4 new MCP tools gated behind the --category-session flag.

Motivation

The current architecture manages a single browser instance via a module-level singleton. This limits agents to one browser at a time, which is insufficient for workflows that require:

• Comparing behavior across Chrome channels (stable vs canary)
• Testing with multiple user profiles or browser contexts in parallel
• Connecting to remote browsers (e.g., via WebSocket with auth headers) while also running a local instance
• A/B testing across isolated sessions

Changes

New: SessionManager class (src/SessionManager.ts)

• Manages the lifecycle of multiple named browser sessions
• Tracks sessions by numeric ID and optional human-readable name
• Maintains an "active session" concept — all existing tools operate on the active session
• Supports two session types:
  • launched: starts a new browser process, closed on close_session
  • connected: attaches to an existing browser, disconnected on close_session (browser keeps running)
• Lazy default session creation: the first tool call auto-creates a session from CLI args, preserving existing single-session behavior

New: Session tools (src/tools/sessions.ts)

Four new tools, available when --category-session is enabled:

Tool	Description
create_session	Launch a new browser or connect to an existing one. Supports name, headless, channel, isolated, browserUrl, wsEndpoint, and wsHeaders parameters.
list_sessions	List all active sessions with ID, name, connection type, and page count.
select_session	Switch the active session by ID or name.
close_session	Close a session by ID. If the active session is closed, the next available session becomes active.

Refactored: Browser lifecycle (src/browser.ts, src/index.ts)

• Removed the module-level browser singleton from browser.ts, making ensureBrowserConnected and ensureBrowserLaunched stateless (each call creates a new connection)
• Moved browser initialization logic from inline in index.ts to SessionManager.createDefaultSession()
• getContext() now delegates to SessionManager.getActiveContext()

New: McpContext.close() method (src/McpContext.ts)

• Added close(mode: 'close' | 'disconnect') for proper session cleanup
• Disposes resources and either closes or disconnects the browser depending on session type

New CLI flag

• --categorySession / --category-session (default: false) — enables the session management tools

Documentation

• Added "Multi-session support" to README Key features
• Added "Session management tools (opt-in)" section to README with tool list and config example
• Added "Session management" concept section to README
• Added --categorySession to auto-generated options (via npm run gen)
• Added full session tool reference to docs/tool-reference.md

Backward compatibility

• Fully backward compatible. Session tools are behind --category-session (default: false)
• Without the flag, behavior is identical to before — a single default session is lazily created on first tool use
• No changes to existing tool signatures or behavior

Test plan

• npm run build passes
• npm run gen regenerates docs without errors
• Existing tests/cli.test.ts updated with new categorySession defaults
• Manual: verify --category-session exposes 4 new tools via MCP inspector
• Manual: verify create_session with type: "launch" starts a new browser
• Manual: verify create_session with type: "connect" attaches to a running browser
• Manual: verify select_session switches active context for subsequent tool calls
• Manual: verify close_session cleans up browser and auto-selects next session
• Manual: verify default behavior (no flag) is unchanged