🪄 ImageSorcery MCP

ComputerVision-basierte 🪄 Zauberei der Bilderkennungs- und Bearbeitungstools für KI-Assistenten

❌ Ohne ImageSorcery MCP

Bei der Arbeit mit Bildern sind KI-Assistenten eingeschränkt:

❌ Bilder können nicht direkt geändert oder analysiert werden
❌ Keine Möglichkeit zum Zuschneiden, Ändern der Größe oder Verarbeiten von Bildern
❌ Einige LLMs können keine Objekte erkennen oder Text aus Bildern extrahieren
❌ Beschränkt auf verbale Beschreibungen ohne visuelle Manipulation

✅ Mit ImageSorcery MCP

🪄 ImageSorcery stattet KI-Assistenten mit leistungsstarken Bildverarbeitungsfunktionen aus:

✅ Bilder präzise zuschneiden, skalieren und drehen
✅ Zeichnen Sie Text und Formen auf Bilder
✅ Erkennen Sie Objekte mit modernsten Modellen
✅ Extrahieren Sie Text aus Bildern mit OCR
✅ Erhalten Sie detaillierte Bildmetadaten
✅ Nutzen Sie eine breite Palette vortrainierter Modelle für Objekterkennung, OCR und mehr

Bitten Sie Ihre KI einfach um Hilfe bei Bildaufgaben:

"Fotos mit Haustieren aus dem Ordner photos " in den Ordner pets " kopieren"

„Suchen Sie eine Katze im Foto.jpg und schneiden Sie das Bild in der Höhe und Breite auf die Hälfte zu, damit die Katze zentriert wird.“ 😉 Tipp: Verwenden Sie den vollständigen Pfad zu Ihren Dateien".

„Nummerieren Sie die Formularfelder in diesem form.jpg mit dem Modell foduucom/web-form-ui-field-detection und füllen Sie die form.md mit einer Liste der beschriebenen Felder.“ 😉 Tipp: Geben Sie das Modell und die Konfidenz an.

😉 Tipp: Fügen Sie „Use Imagesorcery“ hinzu, um sicherzustellen, dass das richtige Tool verwendet wird.

Ihr Tool kombiniert mehrere der unten aufgeführten Tools, um Ihr Ziel zu erreichen.

🛠️ Verfügbare Tools

Werkzeug	Beschreibung	Beispiel-Eingabeaufforderung
`crop`	Beschneidet ein Bild mit dem NumPy-Slicing-Ansatz von OpenCV	„Beschneide mein Bild ‚input.png‘ von den Koordinaten (10,10) bis (200,200) und speichere es als ‚cropped.png‘.“
`resize`	Ändert die Größe eines Bildes mit OpenCV	„Ändern Sie die Größe meines Bilds ‚photo.jpg‘ auf 800 x 600 Pixel und speichern Sie es als ‚resized_photo.jpg‘.“
`rotate`	Dreht ein Bild mit der Funktion imutils.rotate_bound	„Drehe mein Bild ‚photo.jpg‘ um 45 Grad und speichere es als ‚rotated_photo.jpg‘“
`draw_texts`	Zeichnet mit OpenCV Text auf ein Bild	„Fügen Sie den Text ‚Hello World‘ an Position (50,50) und ‚Copyright 2023‘ in der unteren rechten Ecke meines Bildes ‚photo.jpg‘ hinzu.“
`draw_rectangles`	Zeichnet mit OpenCV Rechtecke auf ein Bild	„Zeichnen Sie auf meinem Bild ‚photo.jpg‘ ein rotes Rechteck von (50,50) bis (150,100) und ein ausgefülltes blaues Rechteck von (200,150) bis (300,250)“
`get_metainfo`	Ruft Metadateninformationen zu einer Bilddatei ab	„Metadateninformationen zu meinem Bild ‚photo.jpg‘ abrufen“
`detect`	Erkennt Objekte in einem Bild mithilfe von Modellen von Ultralytics	„Erkenne Objekte in meinem Bild ‚photo.jpg‘ mit einer Konfidenzschwelle von 0,4“
`find`	Findet Objekte in einem Bild basierend auf einer Textbeschreibung	„Finde alle Hunde in meinem Bild ‚photo.jpg‘ mit einer Konfidenzschwelle von 0,4“
`get_models`	Listet alle verfügbaren Modelle im Modellverzeichnis auf	"Alle verfügbaren Modelle im Modellverzeichnis auflisten"
`ocr`	Führt optische Zeichenerkennung (OCR) auf einem Bild mit EasyOCR durch	„Extrahieren Sie Text aus meinem Bild ‚document.jpg‘ mit OCR in englischer Sprache.“

😉 Hinweis: Detaillierte Informationen und Verwendungsanweisungen für jedes Tool finden Sie in der /src/imagesorcery_mcp/tools/README.md des Tools.

🚀 Erste Schritte

Anforderungen

Python 3.10 oder höher
Claude.app , Cline oder ein anderer MCP-Client

Installation

 Load MCP documentation if you have the tool for it. It will give you path to *MCP-configuration file* and other needed instructions.
 Run command `python -m venv imagesorcery-mcp`
 Run command `source imagesorcery-mcp/bin/activate`
    For windows bash run command `source imagesorcery-mcp/Scripts/activate`
    For windows cmd run command `imagesorcery-mcp\Scripts\activate`
 Run command `pip install imagesorcery-mcp`
 Run command `imagesorcery-mcp --post-install`
 Create or modify *MCP-configuration file*.
 Add the `imagesorcery-mcp` server configuration to the `mcpServers` object in the *MCP-configuration file*
    `"imagesorcery-mcp": {"command": "/full/path/to/venv/bin/imagesorcery-mcp","timeout": 100}`
 Get available models using `get_models` tool from `imagesorcery-mcp`
 Attempt completion, indicating that the installation and configuration are complete.

Erstellen und aktivieren Sie eine virtuelle Umgebung (dringend empfohlen): Für eine zuverlässige Installation aller Komponenten, insbesondere des clip Pakets (installiert über das Post-Install-Skript), wird dringend empfohlen, das in Python integrierte venv Modul anstelle von uv venv zu verwenden .
python -m venv imagesorcery-mcp source imagesorcery-mcp/bin/activate # For Linux/macOS # source imagesorcery-mcp\Scripts\activate # For Windows
Installieren Sie das Paket in der aktivierten virtuellen Umgebung: Sie können pip oder uv pip verwenden.
pip install imagesorcery-mcp # OR, if you prefer using uv for installation into the venv: # uv pip install imagesorcery-mcp
Führen Sie das Post-Installationsskript aus: Dieser Schritt ist entscheidend. Es lädt die erforderlichen Modelle herunter und versucht, das clip Python-Paket von GitHub in der aktiven virtuellen Umgebung zu installieren.
imagesorcery-mcp --post-install

Erstellt ein models (normalerweise im Site-Packages-Verzeichnis Ihrer virtuellen Umgebung oder an einem benutzerspezifischen Speicherort bei globaler Installation), um vortrainierte Modelle zu speichern.
Generiert dort eine erste Datei models/model_descriptions.json .
Lädt die vom detect benötigten Standard-YOLO-Modelle ( yoloe-11l-seg-pf.pt , yoloe-11s-seg-pf.pt , yoloe-11l-seg.pt , yoloe-11s-seg.pt ) in dieses models herunter.
Versucht, das Python-Paket „ clip “ aus dem GitHub-Repository von Ultralytics direkt in die aktive Python-Umgebung zu installieren . Dies ist für die Texteingabefunktion im find erforderlich.
Lädt die vom find benötigte CLIP-Modelldatei in das models herunter.

Sie können diesen Vorgang jederzeit ausführen, um die Standardmodelle wiederherzustellen und clip Installation zu versuchen.

Verwenden von uv venv zum Erstellen virtueller Umgebungen: Tests haben gezeigt, dass mit uv venv erstellte virtuelle Umgebungen pip möglicherweise nicht so enthalten, dass das Skript imagesorcery-mcp --post-install das clip Paket von GitHub automatisch installieren kann (während der clip -Installation kann die Fehlermeldung „Kein Modul mit dem Namen pip“ auftreten). Wenn Sie uv venv verwenden:
1. Erstellen und aktivieren Sie Ihr uv venv .
2. Installieren Sie imagesorcery-mcp : uv pip install imagesorcery-mcp .
3. Installieren Sie das clip -Paket manuell in Ihrem aktiven uv venv :
  uv pip install git+https://github.com/ultralytics/CLIP.git
4. Führen Sie imagesorcery-mcp --post-install aus. Dadurch werden Modelle heruntergeladen, die Installation des Python-Pakets für den clip schlägt jedoch möglicherweise fehl. Für eine reibungslosere automatisierte clip -Installation über das Post-Install-Skript empfiehlt sich die Verwendung python -m venv (wie in Schritt 1 oben beschrieben) zum Erstellen der virtuellen Umgebung.
Verwenden von uvx imagesorcery-mcp --post-install : Wenn Sie das Post-Installationsskript direkt mit uvx ausführen (z. B. uvx imagesorcery-mcp --post-install ), schlägt die Installation des Python-Pakets clip wahrscheinlich fehl. Dies liegt daran, dass die von uvx erstellte temporäre Umgebung normalerweise kein pip in einer vom Skript nutzbaren Weise zur Verfügung stellt. Modelle werden heruntergeladen, aber das clip Paket wird durch diesen Befehl nicht installiert. Wenn Sie uvx zum Ausführen des Hauptservers von imagesorcery-mcp verwenden möchten und clip -Funktionalität benötigen, müssen Sie sicherstellen, dass das clip Paket in einer zugänglichen Python-Umgebung installiert ist, die uvx finden kann, oder erwägen Sie die Installation imagesorcery-mcp in einer persistenten Umgebung, die mit python -m venv erstellt wurde.

⚙️ Konfiguration MCP-Client

Fügen Sie Ihrem MCP-Client diese Einstellungen hinzu. Wenn imagesorcery-mcp nach der Installation im Pfad Ihres Systems enthalten ist, können Sie imagesorcery-mcp direkt als Befehl verwenden. Andernfalls müssen Sie den vollständigen Pfad zur ausführbaren Datei angeben.

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp", // Or /full/path/to/venv/bin/imagesorcery-mcp if installed in a venv
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe", // Or C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe if installed in a venv
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

📦 Zusätzliche Modelle

Für einige Tools müssen bestimmte Modelle im models verfügbar sein:

# Download models for the detect tool
download-yolo-models --ultralytics yoloe-11l-seg
download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt

Beim Herunterladen von Modellen aktualisiert das Skript automatisch die Datei models/model_descriptions.json :

Für Ultralytics-Modelle: Beschreibungen sind in src/imagesorcery_mcp/scripts/create_model_descriptions.py vordefiniert und enthalten detaillierte Informationen zu Zweck, Größe und Eigenschaften jedes Modells.
Für Hugging Face-Modelle: Beschreibungen werden automatisch aus der Modellkarte im Hugging Face Hub extrahiert. Das Skript versucht, den Modellnamen aus dem Modellindex oder der ersten Zeile der Beschreibung zu verwenden.

Nach dem Herunterladen der Modelle wird empfohlen, die Beschreibungen in models/model_descriptions.json zu überprüfen und sie bei Bedarf anzupassen, um genauere oder detailliertere Informationen zu den Funktionen und Anwendungsfällen der Modelle bereitzustellen.

🤝 Beitragen

Verzeichnisstruktur

Dieses Repository ist wie folgt organisiert:

.
├── .gitignore                 # Specifies intentionally untracked files that Git should ignore.
├── pyproject.toml             # Configuration file for Python projects, including build system, dependencies, and tool settings.
├── pytest.ini                 # Configuration file for the pytest testing framework.
├── README.md                  # The main documentation file for the project.
├── setup.sh                   # A shell script for quick setup (legacy, for reference or local use).
├── models/                    # This directory stores pre-trained models used by tools like `detect` and `find`. It is typically ignored by Git due to the large file sizes.
│   ├── model_descriptions.json  # Contains descriptions of the available models.
│   ├── settings.json            # Contains settings related to model management and training runs.
│   └── *.pt                     # Pre-trained model.
├── src/                       # Contains the source code for the 🪄 ImageSorcery MCP server.
│   └── imagesorcery_mcp/       # The main package directory for the server.
│       ├── __init__.py          # Makes `imagesorcery_mcp` a Python package.
│       ├── __main__.py          # Entry point for running the package as a script.
│       ├── logging_config.py    # Configures the logging for the server.
│       ├── server.py            # The main server file, responsible for initializing FastMCP and registering tools.
│       ├── logs/                # Directory for storing server logs.
│       ├── scripts/             # Contains utility scripts for model management.
│       │   ├── README.md        # Documentation for the scripts.
│       │   ├── __init__.py      # Makes `scripts` a Python package.
│       │   ├── create_model_descriptions.py # Script to generate model descriptions.
│       │   ├── download_clip.py # Script to download CLIP models.
│       │   ├── post_install.py  # Script to run post-installation tasks.
│       │   └── download_models.py # Script to download other models (e.g., YOLO).
│       └── tools/               # Contains the implementation of individual MCP tools.
│           ├── README.md        # Documentation for the tools.
│           ├── __init__.py      # Import the central logger
│           └── *.py           # Implements the tool.
└── tests/                     # Contains test files for the project.
    ├── test_server.py         # Tests for the main server functionality.
    ├── data/                  # Contains test data, likely image files used in tests.
    └── tools/                 # Contains tests for individual tools.

Entwicklungs-Setup

Klonen Sie das Repository:

git clone https://github.com/sunriseapps/imagesorcery-mcp.git # Or your fork
cd imagesorcery-mcp

(Empfohlen) Erstellen und aktivieren Sie eine virtuelle Umgebung:

python -m venv venv
source venv/bin/activate # For Linux/macOS
# venv\Scripts\activate    # For Windows

Installieren Sie das Paket im bearbeitbaren Modus zusammen mit den Entwicklungsabhängigkeiten:

pip install -e ".[dev]"

Dadurch werden imagesorcery-mcp und alle Abhängigkeiten von [project.dependencies] und [project.optional-dependencies].dev (einschließlich build und twine ) installiert.

Regeln

Diese Regeln gelten für alle Mitwirkenden: Menschen und KI.

Lesen Sie alle README.md -Dateien im Projekt. Machen Sie sich mit der Projektstruktur und dem Zweck vertraut. Machen Sie sich mit den Richtlinien für Beiträge vertraut. Überlegen Sie, wie sich dies auf Ihre Aufgabe bezieht und wie Sie entsprechende Änderungen vornehmen können.
Lesen Sie pyproject.toml . Beachten Sie die Abschnitte: [tool.ruff] , [tool.ruff.lint] , [project.optional-dependencies] und [project]dependencies . Halten Sie sich strikt an den in pyproject.toml definierten Codestil. Halten Sie sich an den in pyproject.toml definierten Stack der Abhängigkeiten und fügen Sie ohne triftigen Grund keine neuen Abhängigkeiten hinzu.
Schreiben Sie Ihren Code in neue und bestehende Dateien. Falls neue Abhängigkeiten benötigt werden, aktualisieren Sie pyproject.toml und installieren Sie diese über pip install -e . oder pip install -e ".[dev]" . Installieren Sie sie nicht direkt über pip install . Beispiele finden Sie in vorhandenen Quellcodes (z. B. src/imagesorcery_mcp/server.py , src/imagesorcery_mcp/tools/crop.py ). Halten Sie sich an den Codestil, die Namenskonventionen, die Ein- und Ausgabedatenformate, die Codecode-Struktur, die Architektur usw. des bestehenden Codes.
Aktualisieren Sie die zugehörigen README.md Dateien mit Ihren Änderungen. Behalten Sie das Format und die Struktur der vorhandenen README.md Dateien bei.
Schreiben Sie Tests für Ihren Code. Sehen Sie sich vorhandene Tests als Beispiele an (z. B. tests/test_server.py , tests/tools/test_crop.py ). Halten Sie sich an den Codestil, die Namenskonventionen, die Ein- und Ausgabedatenformate, die Codecode-Struktur, die Architektur usw. der vorhandenen Tests.
Führen Sie Tests und Linter durch, um sicherzustellen, dass alles funktioniert:

pytest
ruff check .

Bei Fehlern korrigieren Sie den Code und die Tests. Es ist unbedingt erforderlich , dass der gesamte neue Code den Linter-Regeln entspricht und alle Tests besteht.

Codierungshinweise

Verwenden Sie gegebenenfalls Typhinweise
Verwenden Sie pydantic zur Datenvalidierung und -serialisierung

📝 Fragen?

Wenn Sie Fragen, Probleme oder Vorschläge zu diesem Projekt haben, können Sie sich gerne an folgende Adresse wenden:

Projektautor: titulus über LinkedIn
Sunrise Apps CEO: Vlad Karm über LinkedIn

Sie können im Repository auch ein Problem für Fehlerberichte oder Funktionsanfragen öffnen.

📜 Lizenz

Dieses Projekt steht unter der MIT-Lizenz. Das bedeutet, dass Sie die Software unter den Bedingungen der MIT-Lizenz frei verwenden, ändern und verbreiten dürfen.

🪄 ImageSorcery MCP