Atlas Vision MCP

MCP vision bridge for text-only coding agents. Atlas reads local images, calls a dedicated vision provider, and returns markdown plus structured JSON evidence so agents can work from screenshots, diagrams, and UI mockups without native vision support.

Problem

Many coding agents use text-only or weak-vision models. Developers still reference image paths, screenshots, mockups, and error captures — but the main model cannot see them reliably.

How Atlas decides when to intercept

Atlas uses a multi-layer capability chain to decide whether a model needs vision bridge:

1. ctx.model.input (pi runtime)        → certain vision → skip
2. Hook supports_vision / input_modalities → runtime signal → skip or intercept
3. ATLAS_MODEL_CAPABILITIES_FILE       → user overrides
4. Proxy resolution (composer* patterns, hook model, MAIN_MODEL_REF fallback, upstream inference)
5. Provider heuristics (v0.4.0)        → openai/* = vision, deepseek/* = text-only
6. models.dev catalog                  → remote lookup
7. ATLAS_INTERCEPT_MODE                → policy fallback

Provider heuristics replace hardcoded model lists — no updates needed when new models release:

Proxy providers (cursor/*, opencode-go/*, opencode/*) route to arbitrary upstream models. Atlas resolves capabilities via:

1. Runtime signal from hooks (supports_vision, input_modalities) or pi (ctx.model.input)
2. Known proxy-native patterns (composer*, auto* → vision) — before env overrides
3. Hook model field — wins over MAIN_MODEL_REF when the agent sends it
4. MAIN_MODEL_REF — fallback when hook model is unknown (avoid global export; use per-agent config)
5. CURSOR_UNDERLYING_MODEL — alternative upstream override
6. Upstream inference from model id prefix (gpt-* → openai, deepseek-* → deepseek, …)
7. Safe default: intercept when unknown

Do not set MAIN_MODEL_REF globally if you switch between text-only models (Pi + DeepSeek) and vision models (Cursor Composer). Use per-agent config (~/.config/atlas-vision/env for Codex, project .env for Pi) or let hooks send the active model.