VisionMCP

A visual compiler and verifier for coding agents.

VisionMCP turns rendered evidence into inspectable visual programs, compares target and candidate worlds, maps residuals back to source, and binds claims to tamper-evident receipts. It runs locally, exposes a small MCP surface by default, and moves heavy evidence through content-addressed resources.

uvx --from \
  'visionmcp-ocular[compiler] @ git+https://github.com/joshuahickscorp/visionmcp@v0.8.0-alpha.1' \
  visionmcp demo compiler

That demo needs no account, API key, model weight, or network after installation. It compiles a bundled CC0 fixture, injects one controlled source defect, maps the residual to its declaration, repairs it, verifies the receipt, and rejects two tampered copies. <!-- capability:compiler.visual-program -->

Public alpha. Ocular is EXPERIMENTAL. The previous Apple benchmark scored 297 cases across three experiments with zero complete passes. VisionMCP does not claim a perfect copy or original-source recovery. <!-- capability:ocular.perception --> <!-- capability:compiler.apple-parity04 -->

What works

• A 15-tool lightweight core for projects, local evidence, artifact lookup, comparison, verification, progress, and review. <!-- capability:core.project-artifacts -->
• Versioned, paginated, content-addressed MCP resources for captures, states, motion, correspondence, residuals, source bindings, repairs, receipts, benchmarks, models, and binary analyses. <!-- capability:core.mcp-resources -->
• An evidence-to-VisualProgramIR compiler with deterministic HTML/CSS emission and explicit uncertainty.
• A loopback-only Studio with target/candidate views, correspondence, residuals, source traces, repair queue, motion, receipts, 3D, and authorized binary summaries. <!-- capability:studio.local-workspace -->
• Portable receipt verification that rejects changed payloads and artifacts. <!-- capability:core.receipts -->
• Optional physical Ghidra and Blender lanes with governed authorization and honest blockers when runtimes are absent. <!-- capability:binary.ghidra --> <!-- capability:3d.blender -->

The machine-readable claim authority is artifacts/capability-ledger.json; the human view is docs/CAPABILITY_LEDGER.md. README claims are checked against that ledger in CI.

Try it from a clone

git clone https://github.com/joshuahickscorp/visionmcp
cd visionmcp
uv sync --extra dev --extra ocular

uv run visionmcp doctor --core
uv run visionmcp demo compiler
uv run visionmcp demo verify
uv run visionmcp studio

The distribution name remains visionmcp-ocular; the import and command are both visionmcp. Production PyPI is not published as part of this alpha without separate operator authorization.

Profiles

Profile	Adds	Host requirements
core	projects, local media evidence, receipts, resources	none beyond core Python dependencies
web	governed Chromium/DOM/a11y/style/network evidence	.[web] and host Chrome
compiler	VisualProgramIR, emission, repair planning, benchmark creation	core install
3d	Blender, GLB/glTF, geometry and validation	Blender; geometry extra for reconstruction
binary	authorized isolated Ghidra analysis	Ghidra 11.2.1 and JDK 21+
ocular	recorded streams, tracking, world state, next-view	.[ocular]; EXPERIMENTAL
full	accepted public profiles	profile-specific runtimes
dev	evaluators, probes, attack fixtures, diagnostics	.[dev]; never the default

visionmcp serve --profile core
visionmcp serve --profile compiler
visionmcp capabilities --profile compiler --json

Core exposes 15 high-level MCP tools—inside the 12–20 target—and does not load a browser, Blender, Java adapter, model backend, or plugin at startup.

Studio

visionmcp studio
# prints and opens http://127.0.0.1:7741/

Studio binds only to 127.0.0.1, has no account or telemetry, lazy-loads heavy evidence, draws correspondence graphs on a bounded canvas, supports keyboard navigation, and exports a static report. It refuses 0.0.0.0.

Demos

visionmcp demo compiler
visionmcp demo verify
visionmcp demo binary   # physical Ghidra or structured BLOCKED + exact fix
visionmcp demo 3d       # physical Blender or structured BLOCKED + exact fix
visionmcp demo ocular   # EXPERIMENTAL recorded fixture

demo binary analyzes a source-known fixture without executing it or giving the analyzer its source. Decompiler output is labelled approximation. demo 3d produces an editable BLEND, desktop/mobile GLBs, a fixed Cycles render, an authority/uncertainty map, reopen validation, and a receipt. Neither demo silently substitutes a fallback PASS.

Receipts and benchmarks

visionmcp receipt explain path/to/receipt.json
visionmcp receipt verify path/to/receipt.json
visionmcp benchmark escrow doctor --escrow path/to/escrow
visionmcp benchmark escrow rehearse --escrow path/to/escrow --public-only

A receipt says what physically ran, what was inferred, what was blocked or substituted, and which claims remain experimental. Integrity verification is not fidelity verification.

Evaluator escrow binds corpus splits, metrics, thresholds, environment, canaries, counters, commands, schemas, rights, and digests. Hidden execution is opaque and policy-gated; Apple Parity 05 hidden remains untouched until every frozen public case passes.

Local-first and safe by default

• Telemetry is off.
• Core doctor is offline.
• No model or browser is downloaded automatically.
• Studio is loopback-only.
• Plugin discovery reads data manifests and imports no third-party code.
• Optional workers are bounded and checked for leaks.
• Public export audits reject creator-local paths and private benchmark data.

See SECURITY.md, PRIVACY.md, docs/security/THREAT_MODEL.md, and docs/LIMITATIONS.md.

Honest failure history

The Apple work is valuable because it failed loudly. Three Parity 04 experiments produced zero complete passes over 297 scored cases and exposed false-pass mechanisms around identity, observability, containment, assets, and evaluator authority. Those failures are preserved in the capability ledger and launch notes. The public alpha is useful independently of Apple Parity 05.

Contributing

Run the focused public gates:

python scripts/check_capability_ledger.py
pytest -q
ruff check .
python -m build

Start with CONTRIBUTING.md, docs/ARCHITECTURE.md, and docs/PLUGIN_API.md. Security reports follow SECURITY.md; do not open a public issue for an undisclosed vulnerability.

Apache-2.0. Demo and model asset licenses are enumerated separately.