1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cornea inspect https://example.com for layout overlaps and contrast issues" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Cornea

by AbduljabbarBXR

Overview Schema Source Related Servers Discussions Admin

Rust

Local

Cornea

Deterministic visual inspection for AI agents. The eyes a coding agent never had.

Cornea gives a coding agent that builds web pages a real way to see them. As a token-cheap, deterministic structural model it can reason over exactly, instead of megabytes of screenshots and raw DOM dumped into context.

An agent doesn't need a photo of a page. It needs to know is my layout broken, and how. Cornea computes an abstract visual geometry model of every element (box, position, z-order, computed styles) and derives inspection conclusions. overlap, overflow, contrast, quality. Then exposes them as native tools on three surfaces: CLI, MCP, and HTTP API.

One promise holds everything together: same input → byte-identical output. No Chromium, no sub-pixel variance, no server. A single ~1.4 MB binary.

Quick start

# Build (Rust 1.98+, edition 2024)
cargo build --release

# Inspect a file, the simplest way to use Cornea
./target/release/cornea tests/fixtures/sample-bugs.html 360

Requires only cargo. No browser, no Node, no system dependencies. Builds fine on a phone-class device.

Or install the cornea command from npm (no Rust toolchain needed):

npm install -g optrex   # provides the cornea command
cornea --help

Related MCP server: bettercss

Visual guide: what Cornea does

Take this page below. It looks fine as source. But it's hiding four layout bugs. Cornea finds every one.

<!-- tests/fixtures/sample-bugs.html (excerpt) -->
<section class="row">
  <div class="card">Card 1</div><div class="card">Card 2</div><div class="card">Card 3</div>
</section>
<div class="overlap-left">Left overlap</div>   <!-- position:absolute; left:20; top:20 -->
<div class="overlap-right">Right overlap</div> <!-- position:absolute; left:150; top:40 -->
<div class="overflow-bad">...</div>            <!-- width:600 on a 360 viewport -->
<p class="low-contrast">Hard to read on white</p>  <!-- color:#cccccc on #ffffff -->

Run it and Cornea reports the damage instantly:

$ ./target/release/cornea tests/fixtures/sample-bugs.html 360

{
  "html_file": "tests/fixtures/sample-bugs.html",
  "viewport_w": 360.0,
  "element_count": 17,
  "est_tokens": 1068,                      // <-- entire page read for ~1k tokens
  "report": {
    "total_elements": 17,
    "visible_elements": 14,
    "overlaps": [ ... 7 collisions ... ],
    "overflows": [ ... 1 clipped ... ],
    "contrast":  [ ... 2 AA failures ... ],
    "quality":   { "score": 0.06, "label": "broken" }
  }
}

Each finding is precise and actionable:

Finding	Detail
Overlap	`section.row ⇄ div.overlap-right`, area 20000 px². The absolutely-positioned boxes cover the cards
Overflow	`div.overflow-bad`: right edge `600` exceeds viewport `360` → clipped
Contrast	black on `blue`: ratio `2.44:1`. Fails WCAG AA (needs 4.5)
Contrast	`#cccccc` on white: ratio `1.61:1`. Fails WCAG AA

That is the value: hundreds of tokens, not hundreds of kilobytes, and a deterministic answer the agent can act on and re-verify.

Visual guide: the three surfaces

Cornea is one engine, three doors. All three returns identical inspection JSON because they funnel through a single shared dispatch.

1. CLI. Inspect a file

cornea <file.html | http(s)://url> [viewport_width] [viewport_height] [--js]

$ cornea page.html 360
{
  "html_file": "page.html",
  "viewport_w": 360.0,
  "element_count": 42,
  "json_bytes": 8124,
  "est_tokens": 2193,
  "report": { "total_elements": 42, "visible_elements": 38, "overlaps": [], "overflows": [], "contrast": [], "quality": { "score": 1.0, "label": "good" } }
}

2. MCP. Native agent tools over stdio

cornea --serve

An agent calls layout.* tools directly; it passes the page source, or a live URL (see URL capture below), per call:

→ {"method":"tools/call","params":{"name":"layout.overlaps",
     "arguments":{"html":"<div style=\"position:absolute;left:20;top:20;width:200;height:100\">A</div>..."
                   ,"width":360}}}
← {"id":1,"result":{"content":[{"text":"[{\"a_sel\":\"...div \u21c4 ...div\",\"area\":20000}]"}]}}

Tool	Returns
`layout.inspect`	Full visual model + report
`layout.overlaps`	Elements whose boxes collide
`layout.overflow`	Clipped / collapsed / off-screen
`layout.contrast`	WCAG AA ratios for text elements
`layout.quality`	0..1 health score + issue list
`layout.fidelity`	Which CSS features are exact vs approximated

3. HTTP API. Call from anything

cornea --serve-http [addr]        # default 127.0.0.1:8080

curl -s -X POST http://127.0.0.1:8080/inspect \
  -H 'Content-Type: application/json' \
  -d '{"html":"<p style=\"color:#cccccc\">bady</p>","width":360}'

{"total_elements":1,"contrast":[{"selector":"...>p","fg":"#cccccc","bg":"#ffffff",
                                 "ratio":1.61,"pass_aa":false}]}

Route	Method	Returns
`/inspect`	POST	Full report
`/overlaps`	POST	Collisions
`/overflow`	POST	Clipped / collapsed / off-screen
`/contrast`	POST	WCAG ratios
`/quality`	POST	Health score
`/fidelity`	GET	Engine capabilities
`/health`	GET	Liveness

Watching a live page (URL capture)

Every surface accepts a URL where the HTML would go. Cornea fetches the page, inlines its external stylesheets and external scripts (relative URLs resolved against the page), then inspects what a browser would actually show. That is the live coding session loop: run your dev server, point cornea at it, read the layout verdict.

cornea http://localhost:3000 390

{ "url": "http://localhost:3000", "width": 390, "height": 844 }  // HTTP /inspect

{ "method": "tools/call", "params": { "name": "layout.quality",
  "arguments": { "url": "http://localhost:3000", "width": 390 } } }  // MCP

Honesty around capture:

Failed fetches leave the original tag in place and record a note, so the report warnings still flag what did not load.
A positive height emulates a fixed viewport (screenshot frame, iframe, email) and enables below the fold clipping checks. Default 0 means an unbounded scrolling page.
Capture is a snapshot in time. Determinism holds engine side: the same fetched bytes always produce the same report.
Plain HTTP is supported natively. HTTPS pages need a TLS stack, which the binary does not carry; capture from a local http dev server or pre inline the page with a fetch layer of your own.

Architecture

                    ┌─────────────────────────────────────┐
   HTML + CSS ──►   │           cornea (one binary)       │
                    │                                     │
                    │   dom.rs      html5ever ──► tree    │
                    │   css.rs      <style> + inline      │
                    │                                    │
                    │   layout.rs   deterministic layout  │
                    │               (block/inline/flex,   │
                    │                box model, z-index)  │
                    │                    │                │
                    │   model.rs    Visual Geometry Model │
                    │                    │                │
                    │   inspect.rs  overlap / overflow /  │
                    │               contrast / quality    │
                    │                    │                │
                    │   rest.rs     canonical dispatch    │
                    └───────┬─────────────┬───────────────┘
                            │             │
                      ┌─────┴────┐   ┌────┴───────────────┐
                      │  CLI     │   │  MCP (stdio) / HTTP│
                      │  cornea  │   │  layout.* / REST   │
                      └──────────┘   └────────────────────┘

Read the full technical spec: CORNEA-ARCHITECTURE.md

Fidelity. Honest about what's approximate

Cornea never silently fakes precision. layout.fidelity tells an agent exactly what it can trust, and every report carries its own warnings for sources the engine saw but did not apply (external stylesheets, external scripts, media queries, unresolved colors):

{
  "exact":        ["box model", "block flow", "inline text estimates", "flex row/column (no wrap)",
                   "z-index", "visibility", "absolute/fixed left/top", "inline styles",
                   "class/id/tag selectors", "WCAG contrast (hex, rgb, hsl, alpha)"],
  "approximate":  ["text glyph width (not shaping)", "flex-grow/flex-basis distribution",
                   "percentage widths", "overlap semantics ignore intentional stacking"],
  "deferred":     ["grid (parsed as block flow)", "media queries", "border-radius",
                   "external stylesheet <link> when not captured",
                   "complex selectors (combinators, pseudo)"],
  "js": {
    "engine":      "boa",
    "phase":       "A",
    "enabled":     "opt-in via --js / js:true",
    "dom_shim":    "static HTML mirrored in first; getElementById; innerHTML parses markup",
    "unsupported": ["async APIs", "event dispatch", "selector engine", "React/SPA mounting (Phase B)"]
  }
}

JavaScript built-in pages (Phase A)

Cornea can execute inline <script> that builds its DOM via a minimal shim, then run the result through the same deterministic layout engine:

cornea page.html 360 --js            # inline scripts build the DOM first

{ "html": "<p>…</p>", "width": 360, "js": true }   // HTTP /inspect and MCP layout.*

Static HTML is mirrored into the shim before scripts run, so scripts can attach to existing nodes via document.getElementById, and innerHTML parses real markup into elements. Static content survives script runs.
style.* assignments are serialized back to style="…" and participate in overlap/contrast checks.
Async APIs are rejected (setTimeout, fetch, …) rather than hung. Any such use is surfaced in the report's js_notes, so determinism stays a guarantee.
External <script src> runs only when a capture layer (URL capture) inlined its body first.
Full React/SPA mounting is Phase B (experimental). Tracked in ROADMAP-JS.md.

Visual guide: testing (battle-tested)

54 tests run clean with cargo test; CI enforces fmt, clippy -D warnings, release build, tests, and a CLI smoke test on every push.

$ cargo test
Running unittests src/lib.rs      ... 36 passed   // determinism, overlap, overflow,
Running unittests src/main.rs     ...  9 passed    //   contrast, inline flow, flex,
Running tests/endpoints.rs        ...  9 passed    //   nesting, empty input, MCP, CLI, JS, capture

Determinism. Same page inspected twice gives byte-identical JSON (the core thesis).
Bug detection. The fixture's overlaps, overflows, and contrast failures are all asserted.
End-to-end. The compiled binary is spawned and layout.* is called over real stdio MCP.
HTTP. The TCP server boots on an ephemeral port and real requests are made.
Live capture. A real page is served over a local socket; linked CSS must change a contrast verdict.
Edge cases. Empty HTML, deep nesting (no crash), display:none, long text, flex row/col, inline wrapping.

Layout support (v1 scope)

Feature	Status
Block flow, box model (content/border-box)	exact
Inline text runs (horizontal, wrapping)	exact
Flex row / column (simplified, no wrap)	approximate
Absolute / fixed positioning (left/top)	exact
z-index, visibility, `display:none`	exact
`.class` / `#id` / `tag` selectors + inline styles	exact
WCAG contrast (hex, rgb, hsl, alpha, inherited colors)	exact
Live URL capture (CSS and script inlining)	supported
Grid, media queries, border-radius	deferred

Repository layout

cornea/
├── Cargo.toml             # crate: html5ever + serde/serde_json, release LTO+strip
├── README.md              # this file
├── CORNEA-ARCHITECTURE.md # full technical spec
├── src/
│   ├── lib.rs             # build_model / analyze pipeline + unit tests
│   ├── dom.rs             # html5ever -> lightweight element tree
│   ├── css.rs             # <style> + inline style resolution
│   ├── fetch.rs           # live URL capture: GET + css/script inlining
│   ├── layout.rs          # deterministic layout engine
│   ├── model.rs           # VisualModel / ElementView / Rect
│   ├── inspect.rs         # overlap / overflow / contrast / quality / warnings
│   ├── rest.rs            # canonical endpoint dispatch (shared by all surfaces)
│   ├── main.rs            # CLI + stdio MCP server
│   └── server_http.rs     # dependency-free HTTP/1.1 API
├── tests/
│   ├── endpoints.rs       # end-to-end CLI + MCP binary tests
│   └── fixtures/sample-bugs.html  # known-bug fixture for CI smoke
└── .github/workflows/ci.yml

Status

Working MVP, hardened and battle-tested. Deterministic inspection engine with CLI + MCP + HTTP API, live URL capture, below the fold checks, report warnings, 54 passing tests, green CI, plus Phase A inline-script rendering (--js). The roadmap builds toward giving Cornea (and the sibling Crayon text-to-image project) an even richer perception over subsequent phases.

Publishing

Cornea is distributed four ways: npm (npm install -g optrex, gives the cornea command), crates.io (cargo install cornea), GitHub Release + Homebrew (brew install), and the MCP Registry (layout.* tools discoverable by agents). All are staged in this repo. See PUBLISHING.md for the tokens, server.json manifest, and the release/tag recipe.

mcp-name: io.github.AbduljabbarBXR/cornea

License

MIT. See LICENSE.

This server cannot be deployed

Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

render-mcp A
io.github.RodRomer
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Browser Automation Testing & QA Tools
61
CaptureOneAI Web Perception A
com.captureoneai
Give agents eyes on any web page: structured context, and changes explained in plain language.
Browser Automation Web Scraping
61
aiqaramba
io.github.ajrogier
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Testing & QA Tools Browser Automation Agent Orchestration
2
SnoopScan A
com.snoopscan
Web scraping for agents. Point it at a URL and it returns the page as clean markdown, JavaScript-rendered pages included. Point it at a site and it maps the URLs or crawls the section you need in the background, a few pages at a time so results fit in the conversation. Search the web and read full pages, extract fields with a JSON schema you define (validated, never invented), read a store's catalogue or a blog's posts from the platform's own feed, and check whether a page has changed. Failed requests cost nothing. The free plan includes 1,500 credits a month.
Research & Data Search Web Scraping
271

Related MCP Servers

websight
Browser Automation Testing & QA Tools
h34tsink
A
license
Not graded
quality
D
maintenance
Enables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.
Updated 7 months ago (2026-03-07 17:47 UTC)
2 npm
MIT
bettercss
Developer Tools Testing & QA Tools
ikraamg
A
license
Not graded
quality
A
maintenance
Enables CSS layout verification and debugging by extracting deterministic, diffable rendered layout from a browser, allowing agents to inspect, explain, and diff CSS changes.
Updated a month ago (2026-09-04 17:41 UTC)
12 npm
2
MIT
PageMapofficial
Browser Automation Web Scraping
Retio-ai
A
license
A
quality
C
maintenance
Converts raw HTML into structured, AI-readable page maps with 97% token reduction, enabling agents to read, click, type, and navigate any web page.
Updated 5 months ago (2026-05-21 08:23 UTC)
2
13
36
AGPL 3.0
agent-eyes
Browser Automation Testing & QA Tools
oljodev
A
license
A
quality
B
maintenance
Enables AI coding agents to see, measure, and verify web pages through a real Chrome browser, including screenshots, responsive layout and accessibility audits, pixel diffing against baselines, secure logins, and deployed-fix verification.
Updated 18 days ago (2026-09-18 17:31 UTC)
27
1
MIT

Cornea

Quick start

Visual guide: what Cornea does

Visual guide: the three surfaces

1. CLI. Inspect a file

2. MCP. Native agent tools over stdio

3. HTTP API. Call from anything

Watching a live page (URL capture)

Architecture

Fidelity. Honest about what's approximate

JavaScript built-in pages (Phase A)

Visual guide: testing (battle-tested)

Layout support (v1 scope)

Repository layout

Status

Publishing

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

websight

bettercss

PageMapofficial

agent-eyes