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.2' \
  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.

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.

What works

• A 15-tool lightweight core for projects, local evidence, artifact lookup, comparison, verification, progress, and review.

• Versioned, paginated, content-addressed MCP resources for captures, states, motion, correspondence, residuals, source bindings, repairs, receipts, benchmarks, models, and binary analyses.

• 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.

• Portable receipt verification that rejects changed payloads and artifacts.

• Optional physical Ghidra and Blender lanes with governed authorization and honest blockers when runtimes are absent.

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.

Related MCP server: Witnessed

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

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 docs/SECURITY.md, docs/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 tools/scripts/check_capability_ledger.py
pytest -q
ruff check .
python -m build                                  # core wheel
uv build tools/packaging/visionmcp-ocular-kernels # companion wheel

Both wheels are required. Every extra except imaging pins visionmcp-ocular-kernels, and python -m build does not produce it — a core wheel alone gives ModuleNotFoundError on roughly forty subpackages.

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

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