HugoBiotech Vision Bridge

Vision Bridge is a local MCP server for non-textual visual analysis of local image files through the governed Qwen3-VL-Plus gateway route. It reads image bytes only for the current request and never writes image bytes, extracted content, thumbnails, caches, or temporary files.

It deliberately does not offer OCR, text extraction, table-cell reading, or document parsing. Configure a separate OCR MCP when the task is OCR.

Do not send patient-identifying screenshots unless the user has deliberately accepted that exposure. The configured gateway receives the image unredacted.

Install and prepare

Vision Bridge requires Node.js 20+ and uv. First prepare the pinned Python environment outside an MCP startup window:

npx --yes @hugobiotech/[email protected] --prepare

That explicit one-time command may download dependencies. Normal MCP startup is offline and locked, so it either starts promptly from the prepared environment or fails before the client handshake with an actionable preparation message.

For a persistent installation:

npm install --global @hugobiotech/[email protected]
vision-bridge --prepare

Configuration

Paste the complete configuration generated by Model API Keys. The required values are:

VISION_BRIDGE_GATEWAY_URL=https://gateway.example.test
VISION_BRIDGE_API_KEY=the-user's-vision-key
VISION_BRIDGE_CONFIG_REVISION=vl-plus-only-v2
VISION_BRIDGE_REQUEST_TIMEOUT_MS=120000

VISION_BRIDGE_CONFIG_REVISION prevents a new package from silently using an old generated configuration. VISION_BRIDGE_REQUEST_TIMEOUT_MS is the one wall-clock deadline propagated from the Node proxy to the Python gateway. It replaces separate backend, gateway, and tool-call timeout settings.

VISION_BRIDGE_ALLOWED_DIRS is an optional JSON array of permitted local directory roots. If omitted, the bridge can read allowed image extensions from any local directory. A 20 MB per-image cap and known-secret filename checks are always enforced.

Tool contract

The static tools/list contract is published in contract/manifest.json. It contains exactly one tool:

vision_analyze_image(image_path)

The tool is fixed to Qwen3-VL-Plus and returns a visual description. It never selects an OCR model or falls back to a document parser.

After changing a tool name, description, input, or output, regenerate and commit the contract:

npm run generate:mcp-contract
npm run check:mcp-contract

Safe telemetry

The proxy writes compact JSON telemetry to stderr for backend readiness and request outcomes. It records only event names, generated request IDs, tool names, durations, and normalized error classes. The Python audit log contains only the same request ID, model alias, image dimensions, and truncated path and content hashes; it never logs image paths, image bytes, prompts, or API keys.