plain-sight

Version: 1.0.0

Eine KI beschreibt, was sie sieht. Generativer Bildbeschreiber — MCP-Server + CLI, das Florence-2 (MIT) für Fließtextbeschreibungen, OCR und LoRA-Datensatz-Beschriftungsdateien kapselt. Läuft lokal, standardmäßig deterministisch.

Das Geschwisterprojekt von ai-eyes-mcp:

Ehrlichkeitsvertrag

Beschreibungen sind generativ: flüssig, meist genau und in der Lage, Details zu erfinden. plain-sight macht die Ausgabe reproduzierbar (deterministisches Decoding – das gleiche Bild ergibt die gleiche Beschriftung), nicht garantiert korrekt. Wenn du eine spezifische Aussage über ein Bild überprüfen willst, verwende image_verify von ai-eyes-mcp – es misst, es erzählt nicht. Die zwei Tools basieren bewusst auf verschiedenen Modellfamilien, damit das eine das andere überprüfen kann.

Related MCP server: fm-mcp-comfyui-bridge

Tools (MCP)

Schnellstart

pip install -e .
plain-sight-mcp   # starts the STDIO MCP server

Oder als Modul ausführen: python -m plain_sight

CLI

# One image, full paragraph
plain-sight describe hero.png

# One short sentence
plain-sight describe hero.png --detail low

# OCR
plain-sight ocr screenshot.png

# The dataset lane: caption a directory into .txt sidecars with a trigger token
plain-sight batch ./dataset --prefix "mcpt_style, " --detail high

# Re-runs are idempotent — existing sidecars are skipped unless you --overwrite
plain-sight batch ./dataset --prefix "mcpt_style, " --overwrite

Claude Code Konfiguration

{
  "mcpServers": {
    "plain-sight": {
      "command": "plain-sight-mcp",
      "env": {
        "PLAIN_SIGHT_MODEL_DIR": "/path/to/model/cache"
      }
    }
  }
}

Der Beschriftungsvertrag (Datensatz-Spur)

Gebaut für LoRA-Trainingsdatensätze (style-dataset-lab und Verwandte):

• Exakte Basisnamenspaarung: img_0042.png → img_0042.txt. Kein Zähler-Suffix — im Gegensatz zum SaveText-Knoten von ComfyUI, der _00001 anhängt.

• Reine Verkettung: die Begleitdatei enthält prefix + caption + suffix ohne eingefügtes Trennzeichen. Du willst "mcpt_style, <caption>"? Setze das Komma-Leerzeichen in den Präfix.

• Idempotente Wiederholungen: Vorhandene Begleitdateien werden übersprungen (kosten nichts), außer mit --overwrite / overwrite=true.

• Deterministisch: do_sample=false + Beam-Suche – erneutes Beschriften eines unveränderten Bildes erzeugt denselben Text, also bedeuten Unterschiede etwas.

Detailebenen

Die native Aufgabenleiter von Florence-2:

high ist ein Absatz, kein Aufsatz – Florence-2 ist ein kompaktes (0,77B) Modell. Seine Stärke ist Durchsatz und Lizenz, nicht kunstkritische Tiefe. Wenn eine Beschreibung abgeschnitten aussieht, erhöhe max_new_tokens (Standard 1024, max. 4096).

Konfiguration

Logging: nur in stderr (stdout ist der MCP-Protokollkanal), Loggername plain_sight.

Erster Aufruf: Das Modell lädt träge – der erste describe/OCR-Aufruf lädt Florence-2 (~10–20 s auf GPU; der allererste Aufruf lädt ~1,5 GB herunter). Folgeaufrufe dauern auf einer modernen GPU bei Setzung high ca. 1–2 s pro Bild.

Lizenzpositionierung

• Dieses Werkzeug: MIT.

• Das Modell: auf florence-community/Florence-2-large festgepinnt – die offizielle native Native-Transformers-Konvertierung von Microsofts Florence-2-Release. MIT (Hub-Lizenz-Tag am 19.08.2026 verifiziert). Kommerzielle Nutzung problemlos.

• Warum nicht microsoft/Florence-2-large? Gleiche Gewichte, gleiche MIT-Lizenz, aber die Original-Repos liefern vor-native Konfigurationen, die nur über Python-Code von vertrauenswürdigen Quellen funktionieren. Dieses Werkzeug lehnt das grundsätzlich ab. Die Community-Konvertierung lädt mit den eingebauten Florence-2-Klassen von transformers.

• Bewusst nicht angeboten: der Florence-2-Feintuning-Zoo (MiaoshouAI PromptGen, CogFlorence, SD3/Flux-Captioner, Castollux). Die Lizenzen sind unverifiziert; sie bleiben draußen. PLAIN_SIGHT_MODEL_ID auf eines davon umzusetzen ist möglich, aber die Lizenzfrage in dem Fall geht auf dich über.

• Kein Remote-Code: Die Engine nutzt ausschließlich die native Florence-2-Unterstützung von transformers – trust_remote_code wird niemals verwendet, sodass niemals vom Hub abgerufener Python-Code ausgeführt wird. Das erfordert transformers >= 4.51.

Sicherheit und Vertrauen

Dieses Werkzeug arbeitet nur lokal.

• Berührte Daten: lokale Bilddateien (nur gelesen); der HuggingFace-Modell-Cache (einmal bei Erstdownload geschrieben); .txt-Beschriftungsdateien – die einzigen Dateien, die es schreibt, nur wo der Aufrufer verlangt (via out_dir oder nebem Bild), und vorhandene Seiten Dateien werden nur bei explizitem --overwrite ersetzt.

• Kein Netzwerk-Ausgang im Lauf beim Lauf – das Model wird einmal beim ersten ein heruntergeladen, alle Inferenzen sind dann lokal.

• Keine Remote-Codeausführung – nur native transformers-Klassen; trust_remote_code wird nie übergeben, sodass kein Hub-Python ausgeführt wird.

• Keine Geheimnisbehandlung, keine Telemetrie – nichts wird gelesen or gesendet.

• Nur strukturierte Fehler – rohe Stack-Traces erreichen niemals MCP-Clients oder CLI-Benutzer. CLI-Exit-Codes: 0 ok · 1 Benutzerfehler · 2 Laufzeitfehler · 3 teilweise Erfolg.

Vollständige Richtlinie: SECURITY.md. Aktiv gepflegt; dort aufgeführte Versionen sind unterstützt.

Anforderungen

• Python >= 3.10

• transformers >= 4.51 (heimisches Florence-2)

• CUDA-GPU empfohlen (~2 GB VRAM bei FP16); CPU-Fallback funktioniert (langsamer)

• Modell lädt bei der ersten Nutzung ~1,5 GB herunter

Entwicklung

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# CI-safe tests (no model, no GPU)
pytest tests/test_edge_cases.py -v

# Dogfood tests (real model + GPU)
pytest tests/test_dogfood.py -v

# Full verify: imports, edge tests, build
bash verify.sh

Architektur

engine.py    Standalone Florence-2 wrapper — no MCP dependency.
             Lazy-loads the model; validation runs BEFORE the load.
             Importable directly: from plain_sight.engine import Florence2Engine

sidecars.py  The training-data contract, pure stdlib: basename pairing,
             bare concatenation, directory expansion. Testable without torch.

server.py    FastMCP wrapper exposing engine methods as MCP tools.
             Thin layer: validation, error shaping, tool metadata.

cli.py       argparse CLI over the same engine (describe / ocr / batch /
             status / selftest). Structured errors, meaningful exit codes.

Die Architektur ist bewusst von ai-eyes-mcp übernommen – gleiche Engine/Server-Trennung, gleiche Fehlerformung, gleiches Selftest-Muster. Eine Cloud-Variante desselben Vertrags läuft auf Comfy Cloud als caption-florence2-v1-Workflow (ein Bild pro Auftrag, Metadaten-Rider; dieses Tool ist der Massenspur).

Lizenz

MIT

Erstellt von [MCP Tool Shop] (https://mcp-tool-shop.github.io/)