VibeLens: Instructions file for Claude Code

CLAUDE.md — working on VibeLens

Guidance for AI coding assistants (Claude Code, Cursor, Antigravity, Copilot) contributing to this repository. Read this before editing.

What this project is

VibeLens is an MCP server that gives an AI coding assistant vision into a locally running web app. It exposes exactly one tool, inspect_localhost_ui, which returns a screenshot, console/network diagnostics, and a token-optimized DOM snapshot in a single call.

It is a developer tool that runs on the user's own machine and drives a real browser. That makes correctness around security and resource cleanup more important than features.

Stack

• Node.js ≥ 20, ESM only ("type": "module"). Playwright 1.62 requires >=20 and vitest 4 supports ^20 || ^22 || >=24, so 20 is the floor.
• TypeScript, strict (plus noUncheckedIndexedAccess)
• @modelcontextprotocol/sdk — MCP server + stdio transport
• playwright — headless Chromium
• zod — tool input schema
• vitest — tests

Dependencies are pinned exactly. Do not add a dependency without a concrete reason; do not swap Playwright for Puppeteer.

Architecture

src/index.ts     Executable entrypoint (#!/usr/bin/env node). Connects the
                 server to StdioServerTransport. Deliberately thin.
src/server.ts    MCP server: tool schema, description, response assembly,
                 error formatting. No side effects on import.
src/browser.ts   Playwright capture engine: launch → observe → capture → close.
src/dom.ts       sanitizeDomInPage() runs INSIDE the browser; truncateDom()
                 runs in Node.
src/security.ts  validateLocalUrl() — the SSRF allowlist.
src/types.ts     Shared types, VIEWPORT_PRESETS, LIMITS, CaptureError.

Data flow: server.ts → captureUIState() → { image, diagnostics, dom } → two MCP content blocks (image first, then text).

Invariants — do not break these

1. stdout belongs to the MCP transport. Never console.log. Use the log() helper in server.ts, which writes to stderr. A stray stdout write corrupts the JSON-RPC stream and silently breaks the integration.
2. The browser is always closed in a finally block. A leaked Chromium costs hundreds of MB and the server is long-lived.
3. Validate the URL before launching anything. validateLocalUrl() is the only gate against SSRF. Never add a bypass, an "allow any host" flag, or DNS resolution of arbitrary hostnames (that reintroduces DNS rebinding). Instance-metadata addresses stay unconditionally blocked.
4. A failed capture must never crash the process. Catch, wrap in CaptureError, return { isError: true, content: [text] }.
5. Every error the model sees needs a next step. CaptureError carries both a message (what happened) and a hint (what to do). Keep that contract.
6. Respect the token budget. Everything in LIMITS exists to protect the caller's context window. Raising a limit needs justification; adding a new unbounded field to the payload is not acceptable.
7. sanitizeDomInPage must stay self-contained. Playwright serializes it with Function.prototype.toString(), so it cannot reference imports or module-scope variables — configuration arrives via its single argument.
8. The tool stays read-only. It observes pages. It does not click, type, navigate the user's app into a mutating state, or write files.