MCP 服务器

VibeLens

Enables AI coding assistants to visually inspect local web pages by providing screenshots, console errors, and sanitized DOM snapshots.

README

<p> <b>Free and MIT-licensed. No paid tier, no account, no telemetry, no network calls beyond your own localhost.</b> </p>

<p> <a href="https://soumyachk101.github.io/VibeLens/"><b>Documentation site</b></a> · <a href="#install"><b>Install</b></a> · <a href="#configure-your-ide"><b>IDE setup</b></a> · <a href="#the-tool"><b>Tool</b></a> · <a href="#what-the-plugin-adds"><b>Skills</b></a> · <a href="./docs/design/ANTI-SLOP.md"><b>Anti-slop guide</b></a> · <a href="./docs/ARCHITECTURE.md"><b>Architecture</b></a> · <a href="./docs/FAQ.md"><b>FAQ</b></a> </p>

</div>

The problem

AI assistants write frontend code well but cannot see what the browser actually rendered. So you become the framebuffer: you open the page, spot the bug, and describe it in prose — "the button is overflowing the card", "spacing looks off on mobile" — and the model guesses which selector you mean.

Three failure modes dominate that loop:

Invisible errors. A hydration mismatch or a 404 asset lives in the console, not in your description.
Selector hallucination. The model edits .btn-primary when the element actually carries .cta-button, because it is recalling its own earlier output instead of reading the DOM.
Generated-looking UI. Untouched framework accent, one radius on everything, no type scale, no empty or focus states. It works, and it looks like nobody made it.

The fix

VibeLens is an MCP server that closes the loop. One tool call returns a screenshot, the console and network diagnostics, and a token-optimized DOM snapshot — so the model reasons from evidence instead of memory. The Claude Code plugin adds twelve skills on top, including a design-craft set aimed squarely at the third problem.

<sub><b>Every frame is real output.</b> The screenshots are the tool's own JPEG payload and the console and DOM lines are its own text payload — regenerate them with <code>npm run assets:gif</code>.</sub>

</div>

What comes back	Why it matters
Screenshot (JPEG)	The model can see layout, spacing, colour, overflow and hierarchy.
Console + network errors	Catches hydration errors, uncaught exceptions and 404 assets a screenshot cannot show.
Sanitized DOM snapshot	Real ids and Tailwind/CSS classes, so fixes target selectors that exist.

How it works

Install

Claude Code — install the plugin and you get the MCP server plus twelve skills, four subagents and two advisory hooks:

claude plugin marketplace add soumyachk101/VibeLens
claude plugin install vibelens@vibelens

Every other IDE — VibeLens is a plain MCP server on npm. There is no global install step; npx fetches it on first run:

npx playwright install chromium   # one-time, ~95 MB

Then paste the config block for your IDE from the next section.

Requirements: Node.js 20 or newer (Playwright 1.62 requires it) and Chromium for Playwright.

<details> <summary><b>From source</b></summary>

git clone https://github.com/soumyachk101/VibeLens.git
cd VibeLens
npm install
npx playwright install chromium
npm run build                      # emits dist/
npm test                           # 63 tests, includes real browser captures
npm run smoke                      # end-to-end check over real stdio

Then point your IDE at node /absolute/path/to/VibeLens/dist/index.js. </details>

Configure your IDE

VibeLens speaks MCP over stdio, so every MCP-capable client takes the same shape:

{
  "mcpServers": {
    "vibelens": {
      "command": "npx",
      "args": ["-y", "mcp-vibelens@1"]
    }
  }
}

<details open> <summary><b>Claude Code</b></summary>

As a plugin (recommended — bundles the skills, agents and hooks):

claude plugin marketplace add soumyachk101/VibeLens
claude plugin install vibelens@vibelens

Or as a bare MCP server:

claude mcp add vibelens --scope user -- npx -y mcp-vibelens@1      # every project
claude mcp add vibelens --scope project -- npx -y mcp-vibelens@1   # writes .mcp.json for the team

Verify with /mcp in a session — vibelens should be listed as connected. </details>

<details> <summary><b>OpenAI Codex (CLI and IDE extension)</b></summary>

codex mcp add vibelens -- npx -y mcp-vibelens@1

Or edit ~/.codex/config.toml directly. Codex shares this config between the CLI and the IDE extension, so it only needs doing once:

[mcp_servers.vibelens]
command = "npx"
args = ["-y", "mcp-vibelens@1"]

Check with codex mcp list. Codex only supports local stdio servers, which is exactly what VibeLens is. </details>

<details> <summary><b>Cursor</b></summary>

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects, with the JSON block above. Then enable vibelens under Settings → MCP. </details>

<details> <summary><b>Google Antigravity</b></summary>

Open the MCP config from the UI — three-dot menu in chat → MCP Servers → Manage MCP Servers → View raw config, or Settings → Customizations → Open MCP Config — and paste the same block. Depending on your build the file lives at:

~/.gemini/antigravity/mcp_config.json
~/.gemini/config/mcp_config.json (newer builds and the Antigravity CLI)

Using the in-app menu is the safest way to open the right one. </details>

<details> <summary><b>Windsurf</b></summary>

~/.codeium/windsurf/mcp_config.json, same JSON block. </details>

<details> <summary><b>VS Code (GitHub Copilot agent mode)</b></summary>

.vscode/mcp.json:

{
  "servers": {
    "vibelens": { "command": "npx", "args": ["-y", "mcp-vibelens@1"] }
  }
}

</details>

<details> <summary><b>Claude Desktop</b></summary>

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, same JSON block. Restart the app afterwards. </details>

The tool

`inspect_localhost_ui`

Parameter	Type	Default	Description
`url`	string, required	—	Local URL, e.g. `http://localhost:3000/dashboard`. A missing scheme is assumed to be `http://`.
`viewport`	`desktop` \| `tablet` \| `mobile`	`desktop`	`desktop` 1920×1080, `tablet` 820×1180 @2x, `mobile` 390×844 @2x with touch emulation.
`delay`	number (0–15000)	`1000`	Milliseconds to wait after load, for hydration, animations or data fetching.
`fullPage`	boolean	`false`	Capture the whole scrollable page instead of the viewport.

Returns two content blocks: an image (base64 JPEG, quality 75) and a text block containing JSON:

{
  "summary": {
    "url": "http://localhost:3000/health",
    "pageTitle": "Service health",
    "viewport": "desktop (1920x1080)",
    "fullPage": false,
    "waitedMs": 1000,
    "captureMs": 1253,
    "consoleErrors": 1,
    "consoleWarnings": 0,
    "uncaughtPageErrors": 0,
    "failedRequests": 1,
    "domTruncated": false
  },
  "consoleLogs": [
    { "level": "error", "text": "Hydration failed...", "location": "http://localhost:3000/app.js:42:13" }
  ],
  "uncaughtPageErrors": ["TypeError: Cannot read properties of undefined"],
  "failedRequests": [
    { "url": "http://localhost:3000/avatar.png", "method": "GET", "failure": "HTTP 404", "status": 404 }
  ],
  "simplifiedDOM": "<body class=\"...\">...</body>"
}

It is read-only and local-only. It observes a page; it cannot click, hover, type, scroll, or reach a public host. That constraint shapes every skill below — hover and :focus-visible styles are read from the source, not observed.

Prompts that work well

Check localhost:3000 on mobile and tell me what breaks.
Look at localhost:5173/settings — the cards aren't aligned. Fix it.
Does localhost:3000/checkout throw anything in the console?
This page looks AI-generated. Tell me why, then fix the worst of it.
The accent is just default Tailwind blue — give me a real palette.
Compare localhost:3000 on desktop vs mobile and make the nav responsive.

What the plugin adds

The raw tool gives the model eyes. The plugin gives it a method — and a set of skills aimed at the thing screenshots alone do not fix: UI that works but looks like nobody designed it.

Debugging

Skill	What it does
`/vibelens:check-ui`	Capture → read the DOM and diagnostics → locate the source → fix → re-capture to verify.
`/vibelens:console-triage`	Groups console and network failures by root cause, maps them to source files, fixes by severity.
`/vibelens:responsive-audit`	Captures mobile, tablet and desktop; reports only real breakage; fixes the narrowest breakpoint first.
`/vibelens:a11y-audit`	Heuristic pass: missing alt, unnamed controls, unlabelled inputs, heading order, contrast, tap targets.

Design craft — the anti-slop set

Skill	What it does
`/vibelens:design-review`	The flagship. Judges whether the page reads as designed, then fixes what gives it away: no type scale, untouched framework accent, one radius everywhere, uniform spacing, missing empty and loading states, invisible focus, pure black and white, filler copy.
`/vibelens:type-system`	How many sizes and weights are actually in use, whether they form a scale, measure, line height, tracking at display sizes, tabular numerals, font-loading shift.
`/vibelens:color-system`	Is the accent still the framework default; hardcoded hex instead of tokens; pure black and white; a flat neutral ramp; weak contrast; colour as the only signal of state.
`/vibelens:layout-audit`	Spacing-scale consistency, whether spacing groups related content, container width and measure, optical alignment, grid versus flex misuse, magic z-index, overflow.
`/vibelens:motion-system`	Durations against distance travelled, easing by intent, which properties are animated, reduced-motion handling, missing exit transitions — then a named token set.
`/vibelens:micro-interactions`	The state matrix for every control: hover, active, focus-visible, disabled, loading, selected, error — plus feedback timing, validation timing and touch targets.
`/vibelens:polish-pass`	The last 10%: focus rings, selection colour, scroll behaviour, skeletons that match final layout, empty and error states, cursors, icon optical sizing, favicon and title, 404 and offline.

Verification

Skill	What it does
`/vibelens:before-after`	Capture before, change, capture after with identical parameters, report a concrete diff. Different parameters make the comparison meaningless.

Subagents

Subagent	Delegate when
`ui-debugger`	A UI bug needs diagnosing from what the browser actually rendered. Never proposes a fix for a page it has not seen.
`ui-reviewer`	You want an independent pre-merge look across three viewports. Reports defects with evidence; does not edit code.
`design-reviewer`	You want a verdict on whether the UI looks deliberately designed, ranked by perceived-quality impact, with the proving class quoted.
`frontend-builder`	You are building new UI. Establishes tokens before components, builds the full state matrix, never ships a screen it has not captured.

Advisory hooks

Both are PostToolUse, both are advisory only — they print one line and always exit 0, so they can never block a tool call or edit a file.

Hook	Fires when
Unverified change	A `.tsx/.jsx/.vue/.svelte/.css/.scss` file is written or edited — the change is unverified until the page is captured again.
Raw values	That file contains a six-digit hex, `rgb()`/`rgba()`, or arbitrary bracket utilities like `text-[13px]` — suggesting a token or a step on the scale instead.

Every skill is model-invoked as well as slash-invoked. Saying "this looks AI-generated" reaches design-review; "the modal just snaps open" reaches motion-system; "prove that fix worked" reaches before-after.

The design knowledge base

The design skills stay short by citing a shared reference instead of restating it. It is written for an agent mid-task: tables, thresholds and code, no essays.

Document	Contents
ANTI-SLOP.md	17 recognisable tells of machine-generated UI — the tell, why it reads as generated, and the concrete correction.
TYPOGRAPHY.md	Modular scales, line height by size, measure in `ch`, tracking rules, variable fonts, `font-display`, metric-compatible fallbacks, `tabular-nums`, `text-wrap: balance`.
COLOR.md	Deriving a palette instead of picking colours, why `oklch()` beats HSL for even ramps, semantic over primitive tokens, WCAG 4.5:1 and 3:1, dark mode as a remap.
SPACING-LAYOUT.md	A 4px scale, spacing as a proximity signal, optical vs mathematical alignment, grid vs flex, container queries, `min()`/`clamp()`, a named z-index scale.
MOTION.md	Duration bands by distance, easing by intent, compositor-safe properties, `prefers-reduced-motion` that degrades rather than removes meaning, FLIP and view transitions, what never to animate.

Start at docs/design/README.md for the index and the working order.

How it protects your context window

A raw document.body.outerHTML from a modern app is mostly noise. VibeLens sanitizes it inside the browser, before it ever reaches the model.

Reproduce that measurement yourself with npm run assets:measure.

Removed: <script>, <style>, <noscript>, <template>, <link>, <meta>, <base>, <title> and HTML comments.
Collapsed to an empty placeholder: <svg>, <canvas>, <iframe>, <video>, <audio>, <object>, <embed>, <map>, <picture> — the box still appears in the tree because it affects layout, but its internals are gone.
Attributes kept: id, class, role, aria-*, data-testid/-test/-cy/-qa, plus form and table structure attributes.
Attributes shortened: data: URIs become data:image/png[stripped]; anything over 300 chars is truncated; inline style over 120 chars is cut.
Text nodes: whitespace collapsed, each node capped at 160 chars.
Hard cap: 20,000 characters, with an explicit  marker so the model knows the tree is partial.

Architecture

Module-by-module detail, the request lifecycle and the resource model live in docs/ARCHITECTURE.md. The reasoning behind each significant choice is recorded as an ADR in docs/adr/:

ADR	Decision
0001	MCP over stdio
0002	Playwright over Puppeteer
0003	An allowlist, not a denylist
0004	One tool, not many
0005	The plugin ships from a subdirectory
0006	JPEG screenshots and DOM truncation

Security

VibeLens drives a real browser on your machine, so an unvalidated URL would be a server-side request forgery (SSRF) primitive. Every URL is checked before Chromium launches.

Allowed: localhost, *.localhost, 127.0.0.0/8, 0.0.0.0, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, [::1], IPv6 unique-local (fc00::/7) and link-local (fe80::/10).

Blocked:

Every public hostname and IP address.
Any DNS name that is not localhost-based — resolving one invites DNS rebinding, so hostnames are refused rather than looked up.
Cloud instance-metadata endpoints (169.254.169.254, 169.254.170.2, fd00:ec2::254, 100.100.100.200) and all of IPv4 link-local 169.254.0.0/16.
Non-HTTP schemes (file:, ftp:, javascript:, ...).
URLs containing credentials (http://user:pass@...).

Two further points worth knowing:

The tool is annotated readOnlyHint — it observes a page, it never modifies your project, and it cannot click, type or scroll.
Page content is untrusted input. Text scraped from a rendered page could contain instructions aimed at your assistant. Treat the DOM snapshot as data, never as direction.

To report a vulnerability, see SECURITY.md.

Each call launches an ephemeral Chromium and closes it in a finally block, so a failed capture cannot leave a zombie browser behind. This matters on Apple Silicon laptops where every stray Chromium costs hundreds of MB of RSS.

Troubleshooting

Message	Cause and fix
`BROWSER_NOT_INSTALLED`	Run `npx playwright install chromium`.
`CONNECTION_REFUSED`	The dev server isn't running, or is on another port.
`INVALID_URL`	The URL isn't local. VibeLens only inspects localhost and private-network addresses.
`UNSAFE_PORT`	Chromium refuses a fixed port list (1, 7, 69, 79, 6000, 6666...). Use 3000, 5173, 8080.
`TIMEOUT`	Page never finished loading. Retry, or raise `delay`.
Screenshot is blank	The app hadn't hydrated — raise `delay` to 2000–3000.
Tool not listed in the IDE	Check the config path, then restart the IDE. Logs go to stderr prefixed `[vibelens]`.

The long-form version, including per-IDE diagnosis, is in docs/TROUBLESHOOTING.md. Common questions are answered in docs/FAQ.md.

Development

npm run dev                  # run the server from source over stdio
npm run typecheck            # tsc --noEmit
npm test                     # vitest: security, DOM, capture e2e, MCP protocol
npm run build                # emit dist/
npm run smoke                # spawn dist/ and exercise it over real stdio
npm run validate:manifests   # npm + plugin + marketplace + docs consistency
npm run validate:plugin      # claude plugin validate for both manifests
npm run assets:measure       # reproduce the DOM-reduction figure
npm run assets:gif           # regenerate the README animation from real captures
npm run site:build           # build the documentation site into site-dist/
npm run site:check           # link-check it, then inspect it with VibeLens itself

Repository map

src/
├── index.ts        executable entrypoint: wires the server to stdio
├── server.ts       MCP server + inspect_localhost_ui registration
├── browser.ts      Playwright capture engine
├── dom.ts          in-page DOM sanitizer + truncation
├── security.ts     SSRF guard (URL allowlist)
└── types.ts        shared types, viewport presets, payload limits

tests/              vitest suites, incl. real Chromium captures
├── security.test.ts        44 allow/block cases
├── dom.test.ts             truncation boundaries
├── capture.test.ts         end-to-end against a noisy fixture page
├── server.test.ts          real MCP client over InMemoryTransport
└── fixture-server.ts       the deliberately broken fixture page

plugin/             what Claude Code installs — no package.json, on purpose
├── .claude-plugin/plugin.json
├── .mcp.json       launches npx -y mcp-vibelens@1
├── skills/         12 skills: 4 debugging · 7 design craft · 1 verification
├── agents/         ui-debugger · ui-reviewer · design-reviewer · frontend-builder
└── hooks/          two advisory PostToolUse reminders

docs/
├── ARCHITECTURE.md         modules, lifecycle, resource and token model
├── design/                 the anti-slop, type, colour, layout and motion rules
├── adr/                    six architecture decision records
├── PRD-TRD.md              product + technical requirements
├── TROUBLESHOOTING.md      every error code, per-IDE diagnosis
└── FAQ.md                  honest answers, including the limitations

site/                   hand-authored design system for the docs site
├── styles.css      tokens, type scale, themes; no framework
└── app.js          theme toggle, copy buttons, TOC highlight

scripts/
├── smoke.mjs               spawns dist/ and drives it over real stdio
├── validate-manifests.mjs  keeps npm + plugin + marketplace + docs in sync
├── site/                   static site generator + its own link checker
└── assets/                 regenerates the README animation and measurements

.claude-plugin/marketplace.json   one-plugin marketplace catalog
.github/                          CI, tag-driven release, issue forms, CODEOWNERS

Contributing

Start with CONTRIBUTING.md — it lists the seven invariants that must not break (chief among them: never write to stdout, it is the MCP transport) and the verification checklist every PR must pass. Project guidance for AI agents working in this repo lives in CLAUDE.md.

Release process: RELEASE.md. Version history: CHANGELOG.md. Conduct: CODE_OF_CONDUCT.md.

Roadmap

[ ] Element-scoped capture (selector: "#navbar")
[ ] Interaction before capture (click, hover, fill, scroll) — would let the state-matrix skills observe hover and focus instead of reading them
[ ] Multi-viewport diffing in a single call
[ ] Full network waterfall for failed API calls
[ ] Accessibility-tree output alongside the DOM

Ideas and votes belong in Discussions or a feature request.

Free forever, MIT licensed — see LICENSE. No paid tier, no hosted service, no telemetry.

<sub>If VibeLens saved you a round of "no, the <i>other</i> button", a star helps other people find it.</sub>

</div>

VibeLens

README

The problem

The fix

How it works

Install

Configure your IDE

The tool

inspect_localhost_ui

Prompts that work well

What the plugin adds

Debugging

Design craft — the anti-slop set

Verification

Subagents

Advisory hooks

The design knowledge base

How it protects your context window

Architecture

Security

Troubleshooting

Development

Repository map

Contributing

Roadmap

推荐服务器

`inspect_localhost_ui`