concurrent-playwright-mcp AGENTS.md

Engineering conventions — concurrent-playwright-mcp

Conventions for humans and AI agents working in this repo. Keep changes consistent with this file.

Cross-cutting principles

• Clean architecture, one direction. Domain logic does not depend on transport. Here: SessionManager/BrowserSession (domain) know nothing about MCP; server.ts (transport) is a thin delegate. Never leak transport shapes (MCP content) into the domain.
• Parse, don't validate. Untrusted input is validated and shaped at the edge (server.ts via Zod, with .default() for defaults); inner layers receive complete, typed values and keep only genuine domain-state checks (a session/tab lookup miss). Use as only to bridge external (Playwright) types, never to skip a real check.
• Dependency inversion at the seams that need testing. The browser is injected as a BrowserLauncher so the isolation logic is unit-testable with fakes. Inject only where it buys testability or swappability; do not add abstraction layers a small tool does not need.
• Right-size it. SOLID and separation, yes; speculative managers/factories/interfaces, no. Heavy ceremony hurts readability and AI codegen alike.
• TDD the real logic. Write tests first for the logic that matters (session isolation, lifecycle, eviction, error paths). Do not chase coverage on thin pass-throughs to a library.
• Errors are explicit and typed. Named error classes (SessionNotFoundError, ...), never silent failure. At the transport edge, report failures in-band (isError), never throw across the wire.
• Secrets hygiene. No secrets in the repo. .env is gitignored from commit #1. This server takes none, but the rule stands.

Stack and tooling

• Language/runtime: TypeScript (strict) on Node 20+, ESM only ("type": "module").
• Imports: extensionless relative imports (moduleResolution: bundler; the output is bundled by tsup). SDK subpath imports keep their published .js (.../server/mcp.js).
• MCP: @modelcontextprotocol/sdk v1.x with the high-level McpServer + registerTool. inputSchema is a raw Zod shape ({ a: z.string() }), not z.object({...}). Transports: stdio (default) and Streamable HTTP. A stdio server must not write to stdout (it is the JSON-RPC channel) — log to stderr.
• Browser: Playwright. One shared Browser, one isolated BrowserContext per session. Always await closes; clean up on SIGINT/SIGTERM. Bound resources (session cap + idle eviction).
• Build: tsup (ESM, dts, sourcemaps). Types: tsc --noEmit. Lint: ESLint flat config (strictTypeChecked + stylisticTypeChecked) + Prettier (separate step). Tests: Vitest.