ViewportIQ
ViewportIQ is an MCP server for browser inspection, responsive layout testing, and visual diagnostics via Playwright Chromium.
Open, navigate, reload, and inspect web pages or local HTML files.
Analyze DOM structure, elements, computed CSS, box models, and semantic page hierarchy.
Run multi-viewport responsiveness tests from 320px mobile to 1920px desktop.
Detect horizontal overflow, clipped text, fixed-width hazards, media overflow, and overlapping elements.
Inspect breakpoints and track how individual components scale across screen sizes.
Capture viewport, full-page, or element screenshots.
Compare layouts across mobile, tablet, and desktop with pixel-diff analysis.
Audit layout health with severity-rated findings and remediation guidance.
Inspect browser console errors and failed network requests while avoiding sensitive credentials.
Table of Contents
Related MCP server: QA Browser MCP Agent
Key Capabilities
Automated Multi-Viewport Testing: Validates layouts across 7 standard presets (320px Small Mobile to 1920px Ultrawide Desktop) or custom dimensions.
Evidence-Based Overflow Detection: Identifies horizontal page overflow, unconstrained fixed widths, media overflow, and text clipping with exact pixel measurements.
Visual Viewport Comparison & Pixel Diffing: Captures synchronized screenshots across device profiles and highlights responsive shifts using image diff analysis (
pixelmatch).Semantic DOM & Computed CSS: Inspects landmarks, heading hierarchies (h1-h6), accessible names, box models, flex/grid properties, and layout transitions.
Layout Health Audit: Grades pages with a 0–100 health score and classifies issues by severity (
Critical,High,Medium,Low).Real-Time Console & Network Diagnostics: Intercepts uncaught JavaScript exceptions, console warnings, and failed HTTP requests (4xx/5xx) while protecting sensitive credentials.
Robust Session Management: Single persistent Playwright Chromium instance with lifecycle handling and graceful recovery.
Strict Protocol Compliance: Emits all diagnostic logs exclusively to
stderr, preservingstdoutfor JSON-RPC MCP communication.
Architecture
ViewportIQ adheres to a clean, decoupled modular architecture separating browser automation, MCP tool registration, inspection logic, and report generation:
viewport-iq/
├── src/
│ ├── index.ts # CLI executable entry point
│ ├── server.ts # MCP Server initialization & tool registration
│ ├── browser/
│ │ ├── browser-manager.ts # Singleton Playwright browser & context lifecycle
│ │ ├── page-manager.ts # Active page state, console & network interception
│ │ └── navigation.ts # URL navigation, history, and reload
│ ├── tools/
│ │ ├── navigation.tools.ts # open_page, navigate_back, reload_page, etc.
│ │ ├── page-inspection.tools.ts # inspect_page, inspect_element, inspect_styles
│ │ ├── responsive.tools.ts # test_responsiveness, detect_overflow, etc.
│ │ ├── visual-comparison.tools.ts # compare_viewports, capture_screenshot
│ │ ├── layout-audit.tools.ts # audit_layout
│ │ ├── console.tools.ts # inspect_console
│ │ └── network.tools.ts # inspect_network
│ ├── services/
│ │ ├── dom-inspector.ts # Semantic landmarks, headings, images, forms
│ │ ├── css-inspector.ts # Computed styles, box-model, flex/grid layout
│ │ ├── overflow-detector.ts # Horizontal overflow & clipping analysis
│ │ ├── responsive-analyzer.ts # Multi-viewport sweep & breakpoint probing
│ │ ├── screenshot-service.ts # Viewport, full-page, element screenshots
│ │ ├── comparison-service.ts # Cross-screen comparison & pixel diffing
│ │ └── report-generator.ts # Layout health audit & structured JSON reports
│ ├── schemas/ # Zod input schemas for tool validation
│ ├── utils/
│ │ ├── logger.ts # Stderr-only logger (protects stdout JSON-RPC)
│ │ ├── errors.ts # Structured error handling
│ │ └── file-manager.ts # Output directory and file paths
│ └── types/ # Shared TypeScript interfaces & types
├── fixtures/ # HTML test fixtures (clean, overflow, clipping, etc.)
├── tests/ # Vitest automated test suite (24 tests)
├── output/ # Screenshots, diffs, and structured reports
├── package.json
└── tsconfig.jsonPrerequisites & Installation
Prerequisites
Node.js: v18.0.0 or later (tested on Node v20, v22, and v24)
npm: v9 or later
Operating System: macOS, Linux, or Windows
Installation
Clone or navigate to the repository:
cd c:/Users/user/mcp-projectInstall dependencies:
npm installInstall Playwright Chromium:
npx playwright install chromiumBuild the TypeScript project:
npm run buildRun the test suite:
npm run test
Client Configuration
Claude Desktop
Edit your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add viewport-iq under mcpServers:
{
"mcpServers": {
"viewport-iq": {
"command": "node",
"args": [
"C:/Users/user/mcp-project/dist/index.js"
],
"env": {
"NODE_OPTIONS": "--use-system-ca"
}
}
}
}Note on Windows paths: Use forward slashes (
/) or escaped backslashes (\\\\).
Cursor / Windsurf / Cline
In your MCP settings (or .cursor/mcp.json):
{
"mcpServers": {
"viewport-iq": {
"command": "node",
"args": ["C:/Users/user/mcp-project/dist/index.js"]
}
}
}Complete MCP Tool Reference
A. Browser Navigation
open_page
Opens a web URL or local file path.
Inputs:
url(string, required): E.g.,"https://example.com"or"file:///path/to/page.html"wait_until(string, optional):"load","domcontentloaded","networkidle", or"commit"(default:"load")timeout(number, optional): Milliseconds before navigation timeout (default:30000)
Output: Final URL, page title, HTTP response status, load time in ms, and current viewport.
navigate_back
Navigates to the previous page in history.
navigate_forward
Navigates forward to the next page in history.
reload_page
Reloads the currently active page.
B. Page & DOM Inspection
inspect_page
Provides a structural overview of the page.
Inputs:
max_items(number, optional): Maximum items to return for lists (default:25)include_hidden(boolean, optional): Include elements withdisplay:noneorvisibility:hidden
Output: Viewport and document dimensions, total DOM elements, landmarks (
header,nav,main,footer), heading hierarchy (h1–h6) with hierarchy error detection (e.g., skipping fromh1toh3), image dimensions and missingaltattributes, links, buttons, and form inputs.
inspect_element
Inspects a specific DOM element using a CSS selector.
Inputs:
selector(string, required): E.g.,"#hero",".navbar-brand","button.primary"
Output: Tag, text content, attributes, bounding box (
x,y,width,height,top,right,bottom,left), visibility status, parent details, and direct child element snippets.
inspect_styles
Inspects computed CSS properties and box model for an element.
Inputs:
selector(string, required): Target CSS selectorproperties(array of strings, optional): Specific CSS properties to inspect (default: box-model, display, flex/grid, typography, overflow)
Output: Computed styles map, layout model (
flex,grid,block, etc.), positioning type, and computed box model dimensions (margins, paddings, borders).
inspect_page_structure
Generates a clean, readable DOM hierarchy tree focusing on meaningful semantic elements.
Inputs:
root_selector(string, optional): Root selector (default:"body")max_depth(number, optional): Depth of tree (default:4)filter_semantic_only(boolean, optional): Filters out unstyled wrapperdivs (default:true)
C. Responsive Testing & Breakpoints
test_responsiveness (Core Feature)
Runs an automated multi-viewport test across standard device presets:
Category | Width | Height | Type |
Small mobile | 320px | 720px | Mobile / Touch |
Mobile | 375px | 812px | Mobile / Touch |
Large mobile | 430px | 932px | Mobile / Touch |
Tablet | 768px | 1024px | Tablet / Touch |
Small laptop | 1024px | 768px | Desktop |
Desktop | 1440px | 900px | Desktop |
Large desktop | 1920px | 1080px | Desktop |
For every viewport:
Resizes browser viewport.
Waits for CSS transitions and layout stabilization.
Checks for horizontal page overflow (
scrollWidth > viewportWidth).Identifies clipped content and unconstrained elements.
Evaluates navigation behavior (desktop horizontal vs mobile hamburger vs stacked links).
Detects interactive element collisions.
Captures a viewport screenshot saved to
output/responsive-tests/.
Output: Structured report per viewport, overall status (
PASS,WARNING,FAIL), critical issue counts, and actionable remediation recommendations.
detect_overflow
Pinpoints elements breaking the horizontal or vertical bounding box.
Inputs:
selector(string, optional): Optional selector to scope detection
Output: List of issues categorizing
page-horizontal,element-overflow,fixed-width-hazard,media-overflow, andtext-clippingwith exact measurements and CSS fix suggestions.
inspect_breakpoints
Probes how page layout adapts across widths (320px to 1920px).
Inputs:
key_widths(array of numbers, optional): Custom widths to testinspect_css_media_queries(boolean, optional): Queries accessible stylesheet@mediarules
Output: Layout transformation log (navigation transforms, column changes, revealed/hidden elements) and discovered CSS
@mediarules.
inspect_element_responsiveness
Tracks how a single component (e.g., hero banner, navigation bar, card) scales across screen widths.
Inputs:
selector(string, required): Component selectorviewports(array, optional): Custom viewports
D. Visual Comparison & Screenshots
compare_viewports
Captures multi-device screenshots (Mobile 375px, Tablet 768px, Desktop 1440px) and performs layout difference and pixel diff analysis.
Inputs:
url(string, optional): Target URLviewports(array, optional): Viewport presetsrun_pixel_diff(boolean, optional): Generates pixel diff image viapixelmatch(default:true)
Output: Screenshot paths, element shift and stacking analysis, diff image path, mismatched pixel count, and percentage.
capture_screenshot
Captures viewport, full-page, or element-scoped screenshots.
Inputs:
type(string):"viewport","fullPage", or"element"(default:"viewport")selector(string, optional): Required if type is"element"width/height(number, optional): Custom dimensionsfilename_prefix(string, optional): Custom prefix
Output: Existing file path, width, height, file size in bytes, and timestamp.
E. Layout Audit
audit_layout
Audits the page for layout defects and produces a scored health report.
Inputs:
selector(string, optional): Scope selector
Output:
score: 0 to 100 overall layout health score.findingsCount: Breakdown ofCritical,High,Medium,Low, andInformationalissues.findings: Evidence-based issues detailing selector, tag, bounding boxes, and concrete fixes.
F. Console & Network Diagnostics
inspect_console
Retrieves intercepted console logs.
Inputs:
level(string):"all","error","warn", or"info"clear(boolean): Clears buffer after reading
inspect_network
Retrieves intercepted network requests.
Inputs:
failed_only(boolean): Only return failed / 4xx / 5xx requests (default:true)clear(boolean): Clears network buffer after reading
Organized Output Structure
All artifacts generated by ViewportIQ are organized under the output/ directory:
output/
├── screenshots/ # Single-shot viewport, full-page, or element captures
│ └── shot_example_com_1440x900_1794555833208.png
├── responsive-tests/ # Per-viewport responsive sweep screenshots
│ └── resp_example_com_Mobile_375x812_1794555833706.png
├── comparisons/ # Visual comparison diff images
│ └── diff_example_com_375vs1440_1794555835058.png
└── reports/ # Persistent JSON reports for AI ingestion
├── report_responsive_suite_example_com_1794555833481.json
└── report_layout_audit_example_com_1794555833025.jsonAll paths returned to MCP clients are validated to exist on disk.
Practical Workflow Examples
Here is how frontend developers can interact with ViewportIQ via an AI assistant:
1. "Open https://example.com and check whether it works on mobile."
The AI assistant invokes open_page followed by test_responsiveness:
// Tool Call: test_responsiveness
{
"viewports": [
{ "name": "Mobile", "width": 375, "height": 812 }
]
}AI Explains:
"At 375px mobile, your page fails responsiveness with 425px of horizontal overflow. The
.hero-containerhas a rigidwidth: 800pxwithoutmax-width: 100%, forcing horizontal scroll on mobile devices."
2. "Inspect the hero section and explain why the image is overflowing."
The AI invokes inspect_element and inspect_styles:
// Tool Call: inspect_element
{ "selector": ".hero img" }AI Explains:
"The image has a
naturalWidthof 1600px and rendered width of 1600px inside a 375px container. Its computed CSS showsmax-width: none. Addmax-width: 100%; height: auto; display: block;to make it fluid."
3. "Compare this website at 375px, 768px, and 1440px."
The AI invokes compare_viewports:
// Tool Call: compare_viewports
{
"viewports": [
{ "name": "Mobile", "width": 375, "height": 812 },
{ "name": "Tablet", "width": 768, "height": 1024 },
{ "name": "Desktop", "width": 1440, "height": 900 }
]
}AI Explains:
"Between mobile (375px) and desktop (1440px), the layout undergoes significant restructuring (68.4% visual variance). The navigation collapses from horizontal links into a hamburger toggle, and the 3-column product grid stacks into a single column below 768px."
4. "Check the browser console for JavaScript errors."
The AI invokes inspect_console:
// Tool Call: inspect_console
{ "level": "error" }AI Explains:
"Found 1 uncaught JavaScript exception:
TypeError: Cannot read properties of undefined (reading 'initSlider')originating fromapp.js:142."
Automated Test Suite & Fixtures
ViewportIQ includes 6 realistic HTML fixtures and 24 automated unit and integration tests:
Test Fixtures (fixtures/)
responsive-clean.html: Fully responsive layout with fluid grid, auto-fitting cards, and zero overflow.horizontal-overflow.html: Layout with fixed 1200px container triggering mobile overflow.oversized-image.html: Layout with an unconstrained 1400px image bleeding out of its container.text-clipping.html: Fixed-height card withoverflow: hiddencutting off text.broken-mobile-nav.html: Desktop navbar set to 850px without wrapping or mobile toggle.overlapping-elements.html: Badly positioned absolute badge colliding with CTA buttons.
Running the Tests
npm run testOutputs:
✓ tests/browser-navigation.test.ts (2 tests)
✓ tests/console-network.test.ts (2 tests)
✓ tests/dom-inspection.test.ts (4 tests)
✓ tests/layout-audit.test.ts (2 tests)
✓ tests/mcp-server.test.ts (5 tests)
✓ tests/responsive-overflow.test.ts (6 tests)
✓ tests/visual-comparison.test.ts (3 tests)
Test Files 7 passed (7)
Tests 24 passed (24)Troubleshooting & Best Practices
STDIO Protocol Integrity: Never log using
console.login custom tool implementations.stdoutis exclusively reserved for JSON-RPC messages in STDIO mode. Always uselogger.info(),logger.warn(), orlogger.error(), which route tostderr.Windows Certificate / Proxy Configuration: If running behind a corporate network or proxy on Windows, launch Node with
--use-system-ca:NODE_OPTIONS="--use-system-ca" node dist/index.jsChromium Sandboxing on Linux/Containers: ViewportIQ launches Chromium with
--no-sandboxand--disable-dev-shm-usageby default, ensuring compatibility in Docker or CI environments.
Roadmap
STDIO Transport support
7-preset automated responsive sweeps
Visual pixel diffing via Pixelmatch
DOM semantic hierarchy & heading audits
Layout health score calculation
SSE (Server-Sent Events) and Stream transport for remote server deployments
Web Vitals inspection (LCP, CLS, FID) integration
Dark/Light mode theme contrast comparison
License
MIT © ViewportIQ Contributors
Available Tools
17 toolsaudit_layoutB
Perform a comprehensive layout audit on the current page to detect horizontal overflow, text clipping, unconstrained media, rigid fixed widths, and overlapping elements with severity ratings (Critical, High, Medium, Low).
Inputs: selector, viewport_width, viewport_height.
capture_screenshotC
Capture a viewport, full-page, or specific element screenshot and save it to the output directory with metadata.
Inputs: type, width, height, selector, +1 more.
compare_viewportsB
Capture screenshots of a webpage across mobile (375px), tablet (768px), and desktop (1440px) viewports, identify structural layout shifts, and compute visual pixel diff analysis.
Inputs: url, viewports, run_pixel_diff.
detect_overflowB
Identify horizontal page overflow, elements wider than their containers, content extending beyond viewport boundaries, fixed-width hazards, media overflow, and clipped text.
Inputs: selector, viewport_width, viewport_height.
inspect_breakpointsA
Inspect how layout transforms across viewport widths (320px to 1920px). Probes navigation shifts, grid/column count changes, and discovers declared CSS @media queries.
Inputs: key_widths, inspect_css_media_queries.
inspect_consoleA
Capture and inspect browser console output: JavaScript errors, warnings, uncaught exceptions, and console messages.
Inputs: clear, level.
inspect_elementB
Inspect a specific DOM element using a CSS selector. Returns tag, text, attributes, computed styles, bounding box, visibility, parent, and relevant children.
Inputs: selector (required).
inspect_element_responsivenessB
Track a specific element (e.g. hero section, nav bar, image, card grid, or button) across multiple viewports to analyze how its bounding box, font-size, layout model, and padding scale.
Inputs: selector (required), viewports.
inspect_networkA
Capture and inspect network activity: failed requests, HTTP 4xx/5xx responses, resource types, and failure reasons (avoids capturing sensitive auth tokens or cookies).
Inputs: clear, failed_only.
inspect_pageB
Inspect the currently opened page, returning document/viewport dimensions, landmarks, heading hierarchy, images, links, buttons, and forms with accessibility notices.
Inputs: max_items, include_hidden.
inspect_page_structureB
Return a clean, readable structural hierarchy of the page DOM focusing on semantic elements (header, nav, main, section, footer, headings) up to max_depth.
Inputs: max_depth, root_selector, filter_semantic_only.
inspect_stylesA
Inspect computed CSS styles and box model (display, position, width/height, margin, padding, flex/grid, overflow, z-index, font-size) for a selector.
Inputs: selector (required), properties.
open_pageA
Open a URL or local file path in the browser and return page metadata, final URL, HTTP status, and viewport dimensions.
Inputs: url (required), timeout, wait_until.
reload_pageC
Reload the currently active page in the browser.
Inputs: timeout, wait_until.
test_responsivenessA
Test a webpage across standard or custom viewport sizes (320px mobile to 1920px desktop). Detects horizontal overflow, clipped content, broken navigation, and overlapping elements at each size, captures screenshots, and returns structured findings.
Inputs: url, viewports, settle_time_ms, capture_screenshots.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Six tools (audit_layout, detect_overflow, test_responsiveness, inspect_breakpoints, inspect_element_responsiveness, compare_viewports) all perform responsive/overflow analysis with heavily overlapping findings, and inspect_page vs inspect_page_structure vs inspect_element/inspect_styles also overlap on returning DOM and style data. Descriptions hint at differences in scope and output format, but an agent asking 'does this page overflow?' has no obvious single correct choice.
All 17 names are snake_case and verb-first (navigate_, inspect_, open_, audit_, test_, detect_, compare_, capture_), which maps cleanly to the resource/action being performed. No camelCase or bare-noun outliers.
17 tools is at the heavy end for a browser-inspection server, and the count is inflated by overlapping responsive/overflow tools that could be consolidated into two or three with parameters. The core inspection set (open, navigate, inspect DOM/styles/console/network, screenshot) is justified, but the audit family is redundant.
For a read-only inspection-and-audit server the lifecycle is well covered: open/navigate/reload, DOM and style introspection, console and network capture, responsive testing across breakpoints, and screenshots. The main gap is any form of page interaction (click, type, scroll) or session teardown, which limits verification of dynamic states but is arguably outside the stated audit purpose.
Maintenance
Related MCP Connectors
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Free MCP server that audits any public URL: technical SEO, Core Web Vitals, indexing checks.
Visual regression testing over MCP: upload screenshots, review diffs, approve. No CI needed.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for rendering responsive screenshots of URLs at multiple viewports. Enables agents to capture screenshots and detect visual issues like overflow, clipped elements, and missing alt text.MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables browser-based QA testing of web applications using Playwright, with support for manual and AI-driven test execution and HTML reporting.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides structured control of a Playwright browser for QA, scraping, diagnostics, and reproducible browser workflows.MIT
- AlicenseNot gradedqualityCmaintenanceVisual frontend accessibility inspector MCP server. WCAG contrast checking, touch target validation, heading hierarchy audits, responsive screenshots, and S+ grading across mobile and desktop viewports.24 PyPIMIT