MCP Server Image Selector

Dieses Projekt stellt einen MCP-kompatiblen Server bereit, mit dem sich interaktiv Bildausschnitte aus Bildern (z.B. JPEG, PNG) und PDF-Dateien auswählen und als separate Dateien exportieren lassen.

Übersicht

Der MCP Server Image Selector ermöglicht es, mehrere Bilder in einer Session zu bearbeiten und gezielt Bereiche als separate Dateien zu exportieren. Perfekt für Workflows, bei denen aus verschiedenen Dokumenten oder Scans bestimmte Bereiche extrahiert werden müssen.

Features

• Interaktive GUI zur Auswahl von Bild- und Textregionen
• Auto-Load: Ohne Bildpfad werden automatisch die ersten 4 Bilder aus dem Bildverzeichnis geladen
• Multi-Bild-Unterstützung: Mehrere Bilder in einer GUI-Sitzung bearbeiten
• Unterstützung für verschiedene Bildformate (JPEG, PNG, BMP, GIF)
• PDF-Unterstützung: Automatische Extraktion von eingebetteten Bildern oder Rendering der ersten Seite
• Bild-Rotation: Bilder können um 90°, -90° oder 180° gedreht werden
• OCR-Integration: Automatische Texterkennung mit Tesseract für Text-Bereiche (optional)
• Automatische Textzusammenfassung: Alle erkannten Texte werden alphabetisch konkateniert und als full_recipe_text zurückgegeben
• Export der ausgewählten Regionen als Bild- und/oder Textdateien
• Automatische Benennung und Ablage der Exportdateien im tmp-Verzeichnis
• Integration in MCP-Workflows

Voraussetzungen

• Python 3.8+
• Virtuelle Umgebung empfohlen (python -m venv venv)
• Abhängigkeiten aus pyproject.toml installieren (z.B. mit pip install -e .)

Optionale OCR-Unterstützung

Für automatische Texterkennung in Text-Bereichen ist Tesseract OCR optional verfügbar. Die Software funktioniert auch ohne OCR - in diesem Fall wird ein Hinweis in den Text-Dateien ausgegeben.

Installation (optional)

1. Tesseract OCR installieren:

   • Windows: Tesseract Installer herunterladen und installieren
     • Bei Installation unbedingt die deutschen Sprachpakete mit auswählen!
   • Linux: sudo apt-get install tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng
   • macOS: brew install tesseract tesseract-lang

2. Python-Package installieren:

   # Mit optional dependencies aus pyproject.toml:
   pip install -e ".[ocr]"
   
   # Oder direkt:
   pip install pytesseract
   

3. Sprachpakete prüfen: Die OCR-Funktion nutzt standardmäßig Deutsch + Englisch (deu+eng). Ohne diese Sprachpakete funktioniert die OCR nicht korrekt.

   Verfügbare Sprachen prüfen:

   tesseract --list-langs
   

OCR-Funktionalität

• Wird automatisch bei Text-Bereichen (Modus "Text") angewendet
• Erkennt deutschen und englischen Text
• Schreibt erkannten Text in die .txt-Dateien
• Ohne Tesseract: Platzhalter-Text mit Installationshinweis wird eingefügt

Starten des Servers

MCP-Server-Modus (Default)

1. Virtuelle Umgebung aktivieren:

   • Windows: venv\Scripts\activate
   • Linux/Mac: source venv/bin/activate

2. Server starten:

   # MCP-Server-Modus (default)
   python src/mcp_server_image_selector/server.py
   

3. Server starten (mit venv automatisch):

   # MCP-Server-Modus (default)
   `....mcp_server_image_selector\venv\Scripts\mcp-server-image-selector.exe`
   

Standalone-Modus (nur GUI, ohne MCP)

# Ohne Bildpfad - lädt automatisch die ersten 4 Bilddateien aus dem Bildverzeichnis
python -m mcp_server_image_selector.server --standalone

# Mit Bildpfad
python -m mcp_server_image_selector.server --standalone pfad/zum/bild.jpg

# Alternative: Beispiel-Script verwenden
python example_standalone.py

Benutzung

Grundfunktionen

1. Bild öffnen: Ohne Bildpfad werden automatisch die ersten 4 Bilder aus dem Bildverzeichnis geladen. Optional kann ein expliziter Bildpfad angegeben werden.
2. Weitere Bilder hinzufügen: Über den Button "+ Bild hinzufügen" können weitere Bilder zur Session hinzugefügt werden
   • Standardverzeichnis: working_dir/Eingang (falls vorhanden)
3. Zwischen Bildern wechseln: Klick auf ein Bild in der Bildliste wechselt zum entsprechenden Bild
4. Regionen auswählen:
   • Modus wählen: "Foto" oder "Text"
   • Mit der Maus einen Bereich aufziehen
   • "Auswahl speichern" klicken
5. Bild rotieren: Buttons zum Drehen um 90° links, 90° rechts oder 180°
6. Export: "Fertig & Exportieren" exportiert alle Regionen von allen Bildern

Details

• Bei PDF-Dateien wird automatisch das erste eingebettete Bild extrahiert oder die erste Seite als Bild gerendert
• Jedes Bild kann unabhängig bearbeitet werden (eigene Regionen, Rotation)
• Die Bildliste zeigt den aktuellen Status: ▶ dateiname.jpg [3 Bereiche]
• Alle exportierten Dateien werden im tmp-Verzeichnis des Working Directory abgelegt
• Dateinamen enthalten den Bildnamen, Timestamp und Region-Nummer für eindeutige Identifikation

Beispiel-Workflow

1. MCP-Tool aufrufen: select_image_regions() (ohne Parameter) oder select_image_regions("dokument1.jpg") (mit Bild)
2. GUI öffnet sich - bei Auto-Load mit den ersten 4 Bildern aus dem Bildverzeichnis
3. Bereiche auswählen und speichern (Modus "Foto" oder "Text")
4. Optional: "+ Bild hinzufügen" für weitere Bilder
5. "Fertig & Exportieren" klicken
6. Alle Bereiche werden exportiert, Text-Bereiche per OCR erkannt
7. Die Antwort enthält eine Zusammenfassung sowie full_recipe_text mit allen erkannten Texten

Ergebnis im tmp-Verzeichnis:

dokument1_20250122_143022_region01_foto.png
dokument1_20250122_143022_region02_text.png
dokument1_20250122_143022_region02_text.txt
dokument2_20250122_143022_region01_foto.png

Beispiel-Antwort (Auszug):

✓ Erfolgreich 3 Bereiche von 2 Bild(ern) exportiert:
  ...

--- full_recipe_text ---
Textbereich 1
...

Textbereich 2
...

MCP Tools

Der Server stellt folgende MCP-Tools bereit:

select_image_regions

Öffnet die GUI zur interaktiven Auswahl von Bildausschnitten.

Parameter:

• image_path (string, optional): Pfad zum Bild oder PDF (relativ zum Working Directory oder absolut). Ohne Angabe werden automatisch die ersten 4 Bilder aus dem Bildverzeichnis geladen.

Funktionalität:

• Ohne image_path: Lädt automatisch die ersten 4 Bilder aus dem Bildverzeichnis (IMAGE_SUBDIRECTORY)
• Mit image_path: Startet mit dem angegebenen Bild
• Ermöglicht das Hinzufügen weiterer Bilder während der Session
• Exportiert alle Regionen von allen bearbeiteten Bildern
• Alle _text.txt-Dateien werden alphabetisch konkateniert und als full_recipe_text in der Antwort zurückgegeben
• Gibt eine Zusammenfassung der exportierten Dateien zurück

list_exported_regions

Listet alle exportierten Bildausschnitte aus dem tmp-Verzeichnis auf.

get_working_directory

Zeigt das aktuelle Working Directory an.

Projektstruktur

Das Projekt ist modular aufgebaut für bessere Wartbarkeit:

src/mcp_server_image_selector/
├── server.py          # MCP-Server und Tool-Definitionen
├── gui.py             # GUI-Komponente (ImageSelectorGUI)
├── utils.py           # Utility-Funktionen (Verzeichnisse, Koordinaten)
├── pdf_utils.py       # PDF-Verarbeitung und Bildextraktion
└── export.py          # Export-Funktionen inkl. OCR

tests/
├── test_export.py         # Export-Funktionalität
├── test_export_errors.py  # Export-Fehlerbehandlung
├── test_gui.py            # GUI-spezifische Tests
├── test_pdf.py            # PDF-Verarbeitung
├── test_rotation.py       # Bild-Rotation
├── test_server.py         # Server/GUI-Initialisierung
└── test_utils.py          # Utility-Funktionen

Konfiguration

MCP-Integration

Die Datei claude_desktop_config.json enthält die Konfiguration für die Integration in MCP-Umgebungen.

Umgebungsvariablen

• IMAGE_SELECTOR_WORKING_DIR: Optionales Working Directory (Standard: aktuelles Verzeichnis)
• IMAGE_SUBDIRECTORY: Optionales Unterverzeichnis für Bilder relativ zum Working Directory (Standard: Working Directory selbst)

Entwicklung

Tests ausführen

Alle Tests mit pytest:

# Aktiviere virtuelle Umgebung
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Installiere Dev-Dependencies
pip install -e ".[dev]"

# Führe Tests aus
pytest -q              # Kurze Ausgabe
pytest -v              # Verbose
pytest -xvs            # Stop bei erstem Fehler, verbose

Test-Organisation

• 28 Tests decken alle Hauptfunktionen ab
• Tests sind nach Modulen organisiert
• Verwendet pytest mit fixtures für Isolation
• Monkeypatch für Umgebungsvariablen

CI/CD

Ein GitHub Actions Workflow (.github/workflows/ci.yml) führt Tests automatisch bei Push/PR auf main aus.

Lizenz

MIT License