vision-bridge-mcp

Vision-Sidecar-MCP-Server – ermöglicht textbasierten LLMs das Sehen von Bildern. Unterstützt nativ OpenAI- UND Anthropic-API-Formate. Inklusive Modell-Fähigkeits-Routing-Funktion.

Warum?

Die meisten LLMs sind reine Textmodelle – sie können keine Bilder sehen. Dieser MCP-Server schließt diese Lücke, indem er Bilder an ein visionsfähiges Modell weiterleitet und Textergebnisse zurückgibt. Er funktioniert mit jedem OpenAI-kompatiblen oder Anthropic-kompatiblen API-Endpunkt.

In Kombination mit der vision-sidecar-Fähigkeit erfolgt das Routing automatisch basierend auf den Fähigkeiten des Hostmodells:

Ausnahme: Wenn die Systemzwischenablage ein Bild enthält und die Konversation keinen Pfad/URL/Anhang hat, können auch multimodale Hostmodelle image="clipboard" übergeben.

Related MCP server: Vision MCP Server

Funktionen

• ✅ Drei Werkzeuge: analyze_image, ocr_image, compare_images

• ✅ Duales Protokoll: OpenAI chat/completions UND Anthropic messages-Format

• ✅ Zwischenablage-Unterstützung: Windows (PowerShell) + macOS (Swift)

• ✅ SHA256-Dateicache mit konfigurierbarer TTL

• ✅ URL-Download-Wiederholung: Lädt Remote-URLs automatisch als Base64 herunter, wenn die direkte Übergabe fehlschlägt

• ✅ Reasoning-Modell-Fallback: Extrahiert reasoning_content, wenn content null ist

• ✅ Full-Chain-Timeout: Verbindung + Header + Body-Lesen

• ✅ Sicherheitsgrenzen: 16MB Antwort / 20MB Bild / 1MB Fehlerdetails

• ✅ Typisierte Fehler: VisionInputError / VisionApiError / VisionTimeoutError

• ✅ Umfassende Tests: 30+ Unit-Tests + End-to-End-Smoke-Tests

• ✅ Keine neuen npm-Abhängigkeiten (verwendet workspace node_modules)

Schnellstart

1. Stellen Sie sicher, dass sich node ≥ 18 in Ihrem PATH befindet.

2. Setzen Sie Umgebungsvariablen:

export VISION_API_BASE_URL=https://api.example.com/v1   # OpenAI: ends with /v1; Anthropic: base without /v1
export VISION_API_KEY=sk-...                             # API key
export VISION_MODEL=gpt-4o                               # Vision model name
# Optional: export VISION_API_FORMAT=anthropic            # openai (default) or anthropic

3. Registrieren Sie in Ihrer MCP-Client-Konfiguration:

{
  "id": "vision-bridge-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["server.js"],
  "cwd": "/path/to/vision-bridge-mcp",
  "env": {
    "VISION_API_BASE_URL": "https://api.example.com/v1",
    "VISION_API_KEY": "your-key",
    "VISION_MODEL": "gpt-4o"
  },
  "enabled": true
}

Konfiguration

Der Start validiert die ersten drei Variablen; fehlende Variablen führen zu einem lesbaren Fehler und Beenden (Code 1).

Werkzeuge

analyze_image

Voraussetzung: Nur aufrufen, wenn das Hostmodell nicht über multimodales Sehen verfügt. Wenn das Hostmodell multimodal ist, verwenden Sie dessen natives Bildverständnis.

• image (erforderlich, string): Lokaler Dateipfad / http(s)-URL / base64-dataURL / clipboard.

  • Lokaler Pfad: Leitet MIME aus der Erweiterung ab (png/jpg/jpeg/gif/webp/bmp), konvertiert in base64-dataURL.

  • http(s)-URL: Wird direkt als image_url übergeben.

  • dataURL: Nur image/* base64-Kodierung akzeptiert.

  • clipboard / clip / pasteboard: Liest aktuelles Systemzwischenablage-Bild (Windows: scripts/clipboard.ps1, macOS: scripts/clipboard.swift), schreibt in temporäres PNG, normalisiert dann. Linux nicht unterstützt.

• prompt (optional, string): Benutzerdefinierte Erkennungsanweisung. Standard: "Describe this image in detail."

• Rückgabe: Erfolg { content: [{ type: "text", text }] }; Fehler { content: [{ type: "text", text: "[vision_error] ..." }], isError: true }.

Interne Anfrage (aufgeteilt nach VISION_API_FORMAT):

• OpenAI: POST {base}/chat/completions, Bild als image_url-Teil, Auth Authorization: Bearer.

• Anthropic: POST {base}/v1/messages, Bild als image-Block (source: {type: base64, media_type, data} oder {type: url, url}), Auth x-api-key + anthropic-version: 2023-06-01 (sendet auch Authorization: Bearer aus Kompatibilitätsgründen).

Standard-Timeout: 60s (umfasst Verbindung + Body-Lesen).

Sicherheitsgrenzen: API-Antwort 16MB, Bild-Download 20MB (Vorabprüfung des Content-Length + erneute Größenprüfung).

Verhaltensnotizen (aus Tests mit echten Modellen):

• Reasoning-Modelle können content: null mit der Antwort in reasoning_content zurückgeben – automatischer Fallback.

• Fehlgeschlagene http(s)-URL-Direktübergabe mit Medien-/Download-Fehler → automatischer Download als base64 und einmaliger Wiederholungsversuch.

ocr_image

• image (erforderlich, string): Gleiche Normalisierung wie bei analyze_image.

• languages (optional, string): Sprachhinweise (z. B. zh,en).

• format (optional, enum): plain (Standard, Klartext unter Beibehaltung des Layouts) / markdown (behält Überschriften/Listen/Tabellen bei) / json (gibt blocks-Array mit text + type zurück).

• Verwendet intern image_url.detail = "high"; Prompt wird pro Format eingefügt.

compare_images

• images (erforderlich, array, 2–4): Jedes unterstützt lokalen Pfad / http(s)-URL / dataURL / clipboard.

• prompt (optional, string): Benutzerdefinierte Vergleichsanweisung. Standard: "Compare these images and describe their differences and similarities."

• Einzelne Benutzernachricht mit Text + mehreren image_url-Teilen (detail = "auto").

• Wenn eine URL mit einem Medien-/Download-Fehler fehlschlägt, werden alle URLs als base64 heruntergeladen und einmal wiederholt.

Vision-Sidecar-Fähigkeit

Die vision-sidecar-Fähigkeit bietet ein Modell-Fähigkeits-Routing. Wenn sie in Ihrem MCP-Client aktiviert ist:

• Hostmodell hat multimodale Fähigkeiten → verwendet natives Bildverständnis (kein MCP-Aufruf)

• Hostmodell ist rein textbasiert → ruft analyze_image dieses MCP auf

• Ausnahme: Zwischenablage-Lesen ist für multimodale Hostmodelle verfügbar

Ohne diese Fähigkeit bleibt das Verhalten des Hostmodells völlig unverändert – null Eingriff.

Siehe skill/vision-sidecar.md für die Fähigkeitsdatei.

Caching

Standardmäßig aktiviert. Zwischenspeichert Vision-API-Ergebnisse für identische "Bild + Prompt"-Kombinationen.

• Schlüssel: SHA256(Bildkennung + "::" + Prompt). Lokale Dateien/dataURLs werden nach base64-Inhalt gehasht; http(s)-URLs werden nach URL-String gehasht.

• Speicherung: Eine JSON-Datei pro Schlüssel ({ result, cachedAt }), gespeichert im Cache-Verzeichnis.

• TTL: Standard 1 Stunde. Abgelaufene Einträge werden beim nächsten Zugriff automatisch gelöscht.

• Deaktivieren: VISION_CACHE_TTL=0 (oder negativ).

• Hinweis: Der Schlüssel enthält nicht den Modellnamen. Nach dem Wechsel von VISION_MODEL können innerhalb der TTL-Periode zwischengespeicherte Ergebnisse des alten Modells zurückgegeben werden – leeren Sie das Cache-Verzeichnis beim Wechseln der Modelle.

Testen

cd vision-bridge-mcp
node --test

• test/vision.test.js: Unit-Tests der Kernbibliothek (Eingabenormalisierung / Nachrichtenrumpf / API-Aufrufe / Fehlerzuordnung / Timeout / Cache / URL-Wiederholung / OCR / Zwischenablage).

• test/cache.test.js: Cache-Modultests (Schlüsselstabilität / Treffer / Ablauf / beschädigtes JSON / Abwärtskompatibilität).

• test/smoke.test.mjs: End-to-End-Smoke-Test – startet echten server.js über stdio, verwendet lokalen HTTP-Stub zur Simulation des Vision-Modells, validiert tools/list und Werkzeugaufrufe.

Vergleich mit anderen Vision-MCPs

Siehe docs/COMPARISON.md für einen detaillierten Vergleich mit anderen Vision-MCP-Projekten.

Lizenz

MIT