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

```bash
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. <!-- 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 -->

![VisionMCP public-alpha walkthrough](artifacts/release/media/public-alpha-demo.gif)

## 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`](artifacts/capability-ledger.json); the
human view is [`docs/CAPABILITY_LEDGER.md`](docs/CAPABILITY_LEDGER.md). README
claims are checked against that ledger in CI.

## Try it from a clone

```bash
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 |

```bash
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

```bash
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

```bash
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

```bash
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/SECURITY.md), [`docs/PRIVACY.md`](docs/PRIVACY.md),
[`docs/security/THREAT_MODEL.md`](docs/security/THREAT_MODEL.md), and
[`docs/LIMITATIONS.md`](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:

```bash
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`](.github/CONTRIBUTING.md),
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), and
[`docs/PLUGIN_API.md`](docs/PLUGIN_API.md). Security reports follow
[`docs/SECURITY.md`](docs/SECURITY.md); do not open a public issue for an undisclosed
vulnerability.

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