Cornea, deterministic visual inspection

Deterministic visual inspection for AI agents. Overlap, overflow, contrast, quality.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Remote HTTP

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "cornea-deterministic-visual-inspection": {
      "url": "http://127.0.0.1:8080/inspect"
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

bash

# 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):

Terminal

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.

html

<!-- 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:

text

$ ./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

bash

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

text

$ 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

bash

cornea --serve

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

json

→ {"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

bash

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

Terminal

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}'

JSON Config

{"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.

bash

cornea http://localhost:3000 390

json

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

json

{ "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

Code

                    ┌─────────────────────────────────────┐
   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):

config.json

{
  "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:

bash

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

json

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

3d ago

Most recent push to the default branch.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Cornea, deterministic visual inspection

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "cornea-deterministic-visual-inspection": { "command": "npx", "args": ["-y", "Cornea, deterministic visual inspection"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Cornea, deterministic visual inspection AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/cornea-deterministic-visual-inspection?style=directory)](https://allmcps.com/mcp/cornea-deterministic-visual-inspection)

HTML Embed

<a href="https://allmcps.com/mcp/cornea-deterministic-visual-inspection"><img src="https://allmcps.com/api/badge/cornea-deterministic-visual-inspection?style=directory" alt="Cornea, deterministic visual inspection on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

40Quality signal: Fair · 40/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity4/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Cornea, deterministic visual inspection →Install in Claude Desktop Install in Cursor Install in VS Code

Cornea, deterministic visual inspection

Deterministic visual inspection for AI agents. Overlap, overflow, contrast, quality.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Remote HTTP

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "cornea-deterministic-visual-inspection": {
      "url": "http://127.0.0.1:8080/inspect"
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Cornea

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

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

bash

# 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):

Terminal

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.

html

<!-- 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:

text

$ ./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

bash

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

text

$ 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

bash

cornea --serve

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

json

→ {"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

bash

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

Terminal

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}'

JSON Config

{"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)

bash

cornea http://localhost:3000 390

json

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

json

{ "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

Code

                    ┌─────────────────────────────────────┐
   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

config.json

{
  "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:

bash

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

json

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

3d ago

Most recent push to the default branch.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Cornea, deterministic visual inspection

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/cornea-deterministic-visual-inspection?style=directory)](https://allmcps.com/mcp/cornea-deterministic-visual-inspection)

HTML Embed

<a href="https://allmcps.com/mcp/cornea-deterministic-visual-inspection"><img src="https://allmcps.com/api/badge/cornea-deterministic-visual-inspection?style=directory" alt="Cornea, deterministic visual inspection on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

40Quality signal: Fair · 40/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity4/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Cornea, deterministic visual inspection →Install in Claude Desktop Install in Cursor Install in VS Code