vision-bridge-mcp

Verleihen Sie Ihrem reinen Text-OpenCode-Agenten Augen.

OpenCodes reine Textmodelle (z. B. DeepSeek V4) können keine Bilder lesen – wenn Sie also einen Screenshot einer Fehlermeldung, eine Whiteboard-Skizze oder ein Foto eines UI-Entwurfs anhängen, hat der Agent keine Ahnung, was darauf zu sehen ist. vision-bridge-mcp ist ein kleiner MCP-Server, der sich direkt in OpenCode einfügt und ihm zwei neue Werkzeuge zur Verfügung stellt: analyze_image (allgemeine Beschreibung / visuelle Fragen & Antworten) und ocr_image (exakte Texttranskription), beide unterstützt von der Gemini-API (gemini-3.6-flash standardmäßig – überschreibbar mit GEMINI_MODEL, falls Google es später einstellt; aktuelle Modell-IDs finden Sie unter https://ai.google.dev/gemini-api/docs/models).

Ist es erst einmal konfiguriert, brauchen Sie dem Agenten nur noch zu sagen, er solle sich eine Datei ansehen:

Look at ./screenshots/error.png and tell me what's failing.

und er ruft selbstständig analyze_image auf – kein manuelles Kopieren und Einfügen in ein Chat-Fenster, kein separater CLI-Schritt.

Voraussetzungen

• Node.js 18 oder höher

• Ein kostenloser Gemini-API-Schlüssel – einen erhalten Sie unter https://aistudio.google.com/apikey (kostenlose Stufe: 1.500 Anfragen/Tag, keine Kreditkarte erforderlich)

Related MCP server: Vision MCP Server

Installation

Kein Klonen erforderlich. Fügen Sie Folgendes zu Ihrer OpenCode-Konfiguration hinzu (opencode.json im Projektstamm oder ~/.config/opencode/opencode.json für eine globale Einrichtung):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision-bridge": {
      "type": "local",
      "command": ["npx", "-y", "vision-bridge-mcp"],
      "environment": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Starten Sie OpenCode neu (oder führen Sie opencode mcp zum erneuten Verbinden aus), und die Werkzeuge analyze_image und ocr_image erscheinen automatisch. npx lädt das Paket beim ersten Ausführen herunter und speichert es zwischen – nichts muss von Hand erstellt oder installiert werden.

Ziehen Sie eine Umgebungsvariable vor, anstatt den Schlüssel in der Konfigurationsdatei fest zu kodieren? Setzen Sie stattdessen GEMINI_API_KEY in Ihrem Shell-Profil und entfernen Sie den Block "environment" – der Server liest ihn so oder so aus der Prozessumgebung.

Eigenständig ausführen (für Entwicklung oder Tests)

git clone https://github.com/YOUR_GITHUB_USERNAME/vision-bridge-mcp.git
cd vision-bridge-mcp
npm install
cp .env.example .env   # then fill in GEMINI_API_KEY
npm start

Der Server spricht MCP über stdio, also wartet er für sich allein nur darauf, dass sich ein Client (wie OpenCode) verbindet – das ist normal.

Werkzeuge

analyze_image

Allgemeines Bildverständnis. Geben Sie einen Pfad und optional eine benutzerdefinierte Eingabeaufforderung an.

ocr_image

Transkribiert sichtbaren Text wörtlich – nützlich für Fehlerdialoge, Terminal-Screenshots oder abfotografierte Notizen.

Beide Werkzeuge unterstützen PNG, JPEG, WEBP, GIF und HEIC/HEIF, standardmäßig bis zu 20 MB.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen (setzen Sie sie direkt, in einer .env-Datei für den eigenständigen Gebrauch oder im Block "environment" Ihres opencode.json-MCP-Eintrags):

Der Server startet auch ohne gesetztes GEMINI_API_KEY (damit opencode mcp die Werkzeuge weiterhin auflisten kann) – er meldet erst dann einen Fehler mit einer klaren Meldung, wenn ein Werkzeug tatsächlich ohne konfigurierten Schlüssel aufgerufen wird.

Fehlerbehandlung

Jeder Werkzeugaufruf endet entweder mit einem Textergebnis oder schlägt mit isError: true und einer spezifischen, umsetzbaren Meldung fehl – bei einer fehlenden Datei, einem nicht unterstützten Format, einer Datei über dem Größenlimit, einem fehlenden/ungültigen API-Schlüssel oder einem vorgelagerten Gemini-Fehler. Der Server stürzt bei einem fehlerhaften Aufruf nie ab.

Entwicklung

npm install
npm test    # unit tests (node's built-in test runner, no network needed)
npm run lint

Die Testsuite deckt Pfadauflösung, MIME-Typ-Erkennung und Dateivalidierung ab (fehlende Dateien, Verzeichnisse, leere Dateien, zu große Dateien) – also die Eingabeverarbeitungslogik, die im realen Einsatz am ehesten bricht. Der Gemini-API-Aufruf selbst wird hier nicht gemockt/getestet, da er einen echten Schlüssel erfordert; wenn Sie diesen Pfad überprüfen möchten, setzen Sie GEMINI_API_KEY und führen Sie npm start aus, und verbinden Sie sich dann mit einem beliebigen MCP-Client (oder dem MCP Inspector).

Veröffentlichung (Maintainer)

npm login
npm publish --access public

Erhöhen Sie zuerst die version in package.json – npx -y vision-bridge-mcp löst immer die neueste veröffentlichte Version auf.

Mitwirken

Siehe CONTRIBUTING.md.

Lizenz

MIT – siehe LICENSE.