Cornea, deterministic visual inspection MCP server

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

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:

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:

Shortened. The full README is on GitHub.