Performance & cache architecture cleanup

[smartlabsAT]

TL;DR: Clean up technical debt and modularize the MCP server into clear architectural layers, establishing the foundation for v0.2.0 performance improvements.

Context

Epic 1 of the v0.2.0 release cycle. The current MCP server (src/mcp/server.ts, 2223 LOC) mixes tool registration, browser lifecycle, error recovery, and execution logic in a single file. The cache subsystem spans 5 files with overlapping responsibilities (3788 LOC). Several test files reference code removed in PR #29 — npm test currently fails due to a hardcoded stale version check in tests/test-cli-commands.js:280.

This epic eliminates dead code, consolidates the cache subsystem, and introduces a layered server architecture. The result is a cleaner, smaller codebase that subsequent epics can iterate on safely.

Success Criteria

• Server starts and accepts client connections within 3 seconds (measured)
• All currently-working tools remain functional through the refactored entry point
• Cache subsystem consolidated from 5 files to 1–2 files
• Integration test covers the new server architecture end-to-end
• npm test passes cleanly (no broken imports, no stale assertions)
• Existing .mcp.json configurations continue to work without modification
• v0.2.0-alpha.1 published to npm with @alpha tag

Scope

In Scope:

• Remove artificial setTimeout delays from surviving modules
• Delete obsolete test files; audit entire tests/ directory for broken imports and stale assertions
• Consolidate overlapping cache modules into a coherent unit
• Modularize MCP server into routing layer (src/proxy/) and execution layer
• Delete protocol-validation modules (~933 LOC) replaced by SDK-level handling
• Add integration test coverage for new architecture
• Release v0.2.0-alpha.1

Out of Scope:

• New features, new tools, new CLI commands (deferred to Epic 2–3)
• Cache logic improvements or new caching strategies (deferred to Epic 2)
• Session/scenario/profile tool ports (deferred to Epic 3)
• README rewrite (deferred to Epic 4)
• Public API migration guide (ships with v0.2.0 final in Epic 4)

Architecture Decisions

Binding for ALL sub-issues. Deviations require updating this section.

• MCP SDK Server class (low-level): Use Server with setRequestHandler instead of McpServer.tool() — upstream tools use raw JSON Schema, not Zod schemas.
• @playwright/mcp as execution layer: Pinned dependency (0.0.75). Resolved via require.resolve('@playwright/mcp/cli.js') — no network lookup per start. PoC verified 2026-05-18: 23 tools, 2.5s wall time.
• Backward-compat shim: src/mcp/server.ts becomes a re-export to src/proxy/proxy-server.ts. dist/mcp/server.cjs stays valid for existing .mcp.json configs.
• Node.js >= 18: Required by @playwright/mcp. Bump engines.node from >=16.
• Cache consolidation = mechanical only: Inline files, do NOT improve cache logic. Epic 2 redesigns the cache. cache-migration.ts stays (needed for Epic 4).
• Protocol modules deleted in Modularize MCP server into routing and execution layers #39: protocol-validator.ts, protocol-validation-layer.ts, protocol-error-recovery.ts (~933 LOC) — replaced by SDK-level handling.
• browser_* prefix: All tools (local + execution layer) use browser_* for consistent discovery.
• tsup.config.ts: New entry for src/proxy/proxy-server.ts; add @playwright/mcp to externals in existing MCP entry.

Sub-Issues

Order	Issue	Description	Status	Depends on
1	#36	Remove artificial setTimeout delays from test-scenario-cache.ts	open	—
2	#37	Remove obsolete test files; audit tests/ for broken imports and stale assertions	open	—
3	#38	Consolidate cache subsystem (5 files → 1–2); update src/index.ts exports	open	—
4	#39	Modularize MCP server into routing + execution layers; delete protocol modules	open	#38
5	#40	Integration test for new server architecture	open	#39
6	#41	Release v0.2.0-alpha.1	open	#36, #37, #38, #39, #40

Parallelization: #36 and #37 can run in parallel (no file overlap). #38 should complete before #39.

References

• Affected modules: src/mcp/server.ts, src/core/bidirectional-cache.ts, src/core/enhanced-cache-integration.ts, src/core/tiered-cache.ts, src/core/enhanced-cache-key.ts, src/core/context-aware-similarity.ts, src/core/protocol-*.ts
• Milestone: v0.2.0 (due 2026-06-27)
• Branch: feature/v0.2.0

Risks

1. Cache consolidation regression — merging 5 files could break edge cases. Mitigation (Consolidate cache subsystem modules #38): existing cache tests must pass; run both tsup and tsc.
2. Subprocess management — zombie processes, stdio hangs. Mitigation (Modularize MCP server into routing and execution layers #39): auto-restart with rate-limit (max 5/min); 5s cleanup timeout.
3. @playwright/mcp instability (v0.0.x) — breaking changes possible. Mitigation (Modularize MCP server into routing and execution layers #39): pin exact version 0.0.75 (PoC-verified).
4. Public API breaks — 6+ symbols removed from src/index.ts. Mitigation: acceptable for v0.2.0; migration guide in Epic 4.

Dependencies

• Blocked by: none
• Blocks: Epic 2, Epic 3, Epic 4

Audit Log

Date	Audit	Result
2026-05-27	/check — format, content, technical feasibility, cross-issue consistency	All 6 sub-issues verified against codebase. Sub-issue bodies rewritten. GraphQL relations created.
2026-05-27	/check — re-audit with masterplan context	5/6 sub-issues BEREIT, #38 rewritten (symbol count 6→9, TestStep clarification). GraphQL sub-issue relations verified (6/6 linked via subIssues).