ImageSorcery MCP

Magia de herramientas de reconocimiento y edición de imágenes basadas en ComputerVision para asistentes de IA

❌ Sin ImageSorcery MCP

Los asistentes de IA están limitados cuando trabajan con imágenes:

❌ No se pueden modificar ni analizar imágenes directamente
❌ No es posible recortar, redimensionar ni procesar imágenes
❌ Algunos LLM no pueden detectar objetos ni extraer texto de las imágenes
❌ Limitado a descripciones verbales sin manipulación visual.

✅ Con ImageSorcery MCP

🪄 ImageSorcery proporciona a los asistentes de IA potentes capacidades de procesamiento de imágenes:

✅ Recortar, redimensionar y rotar imágenes con precisión
✅ Dibujar texto y formas en imágenes
✅ Detectar objetos utilizando modelos de última generación
✅ Extraer texto de imágenes con OCR
✅ Obtenga metadatos detallados de la imagen
✅ Utilice una amplia gama de modelos previamente entrenados para detección de objetos, OCR y más

Simplemente pídale a su IA que le ayude con las tareas de imágenes:

Copiar fotos con mascotas de la carpeta " photos a la carpeta pets ".

"Busca un gato en la foto.jpg y recorta la imagen a la mitad, tanto en altura como en ancho, para que el gato quede centrado". 😉Sugerencia : utilice la ruta completa a sus archivos.

Numere los campos del formulario en este form.jpg con el modelo foduucom/web-form-ui-field-detection y complete el form.md con la lista de campos descritos. 😉Sugerencia : especifique el modelo y la confianza".

😉 Sugerencia: agregue "use imagesorcery" para asegurarse de que use la herramienta adecuada.

Su herramienta combinará varias herramientas enumeradas a continuación para lograr su objetivo.

🛠️ Herramientas disponibles

Herramienta	Descripción	Ejemplo de mensaje
`crop`	Recorta una imagen utilizando el método de corte NumPy de OpenCV	Recortar mi imagen 'input.png' de las coordenadas (10,10) a (200,200) y guardarla como 'cropped.png'
`resize`	Cambia el tamaño de una imagen usando OpenCV	Redimensiona mi imagen 'photo.jpg' a 800x600 píxeles y guárdala como 'resized_photo.jpg'
`rotate`	Gira una imagen usando la función imutils.rotate_bound	Girar mi imagen 'foto.jpg' 45 grados y guardarla como 'foto_rotada.jpg'
`draw_texts`	Dibuja texto en una imagen usando OpenCV	Añade el texto "Hola Mundo" en la posición (50,50) y "Copyright 2023" en la esquina inferior derecha de mi imagen "photo.jpg".
`draw_rectangles`	Dibuja rectángulos en una imagen usando OpenCV	Dibuja un rectángulo rojo de (50,50) a (150,100) y un rectángulo azul relleno de (200,150) a (300,250) en mi imagen 'photo.jpg'.
`get_metainfo`	Obtiene información de metadatos sobre un archivo de imagen	Obtener información de metadatos sobre mi imagen 'photo.jpg'
`detect`	Detecta objetos en una imagen utilizando modelos de Ultralytics	Detectar objetos en mi imagen 'photo.jpg' con un umbral de confianza de 0,4.
`find`	Encuentra objetos en una imagen basándose en una descripción de texto.	"Buscar todos los perros en mi imagen 'photo.jpg' con un umbral de confianza de 0,4"
`get_models`	Enumera todos los modelos disponibles en el directorio de modelos	"Enumerar todos los modelos disponibles en el directorio de modelos"
`ocr`	Realiza reconocimiento óptico de caracteres (OCR) en una imagen utilizando EasyOCR	Extraer texto de mi imagen 'document.jpg' mediante OCR en inglés

😉 Sugerencia: puede encontrar información detallada e instrucciones de uso para cada herramienta en el /src/imagesorcery_mcp/tools/README.md de la herramienta.

🚀 Primeros pasos

Requisitos

Python 3.10 o superior
Claude.app , Cline u otro cliente MCP

Instalación

 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.

Crear y activar un entorno virtual (muy recomendado): para una instalación confiable de todos los componentes, especialmente el paquete clip (instalado a través del script posterior a la instalación), se recomienda encarecidamente utilizar el módulo venv integrado de Python en lugar de uv venv .
python -m venv imagesorcery-mcp source imagesorcery-mcp/bin/activate # For Linux/macOS # source imagesorcery-mcp\Scripts\activate # For Windows
Instale el paquete en el entorno virtual activado: puede utilizar pip o uv pip .
pip install imagesorcery-mcp # OR, if you prefer using uv for installation into the venv: # uv pip install imagesorcery-mcp
Ejecutar el script posterior a la instalación: Este paso es crucial. Descarga los modelos necesarios e intenta instalar el paquete de Python clip desde GitHub en el entorno virtual activo.
imagesorcery-mcp --post-install

Crea un directorio models (generalmente dentro del directorio de paquetes del sitio de su entorno virtual, o una ubicación específica del usuario si se instala globalmente) para almacenar modelos previamente entrenados.
Genera allí un archivo models/model_descriptions.json inicial.
Descarga los modelos YOLO predeterminados ( yoloe-11l-seg-pf.pt , yoloe-11s-seg-pf.pt , yoloe-11l-seg.pt , yoloe-11s-seg.pt ) requeridos por la herramienta detect en este directorio models .
Intenta instalar el paquete de Python clip desde el repositorio de GitHub de Ultralytics directamente en el entorno de Python activo. Esto es necesario para la función de solicitud de texto en la herramienta find .
Descarga el archivo del modelo CLIP requerido por la herramienta find en el directorio models .

Puede ejecutar este proceso en cualquier momento para restaurar los modelos predeterminados e intentar la instalación clip .

Uso de uv venv para crear entornos virtuales: Según las pruebas, es posible que los entornos virtuales creados con uv venv no incluyan pip de forma que el script imagesorcery-mcp --post-install instale automáticamente el paquete clip desde GitHub (esto podría generar el error "No module named pip" durante la instalación clip ). Si decide usar uv venv :
1. Crea y activa tu uv venv .
2. Instalar imagesorcery-mcp : uv pip install imagesorcery-mcp .
3. Instale manualmente el paquete clip en su uv venv activo:
  uv pip install git+https://github.com/ultralytics/CLIP.git
4. Ejecute imagesorcery-mcp --post-install . Esto descargará los modelos, pero podría fallar al instalar el paquete de Python clip . Para una instalación automatizada y más fluida clip mediante el script posterior a la instalación, se recomienda usar python -m venv (como se describe en el paso 1 anterior) para crear el entorno virtual.
Uso de uvx imagesorcery-mcp --post-install : Ejecutar el script posterior a la instalación directamente con uvx (p. ej., uvx imagesorcery-mcp --post-install ) probablemente no instale el paquete de Python " clip ". Esto se debe a que el entorno temporal creado por uvx no suele tener pip disponible para el script. Se descargarán los modelos, pero este comando no instalará el paquete clip . Si pretende usar uvx para ejecutar el servidor principal imagesorcery-mcp y necesita la funcionalidad clip ", deberá asegurarse de que el paquete clip esté instalado en un entorno de Python accesible que uvx pueda encontrar, o bien, considere instalar imagesorcery-mcp en un entorno persistente creado con python -m venv .

⚙️ Configuración del cliente MCP

Agregue esta configuración a su cliente MCP. Si imagesorcery-mcp está en la ruta de su sistema después de la instalación, puede usar imagesorcery-mcp directamente como comando. De lo contrario, deberá proporcionar la ruta completa del ejecutable.

"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
    }
}

📦 Modelos adicionales

Algunas herramientas requieren que modelos específicos estén disponibles en el directorio models :

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

Al descargar modelos, el script actualiza automáticamente el archivo models/model_descriptions.json :

Para los modelos Ultralytics: las descripciones están predefinidas en src/imagesorcery_mcp/scripts/create_model_descriptions.py e incluyen información detallada sobre el propósito, el tamaño y las características de cada modelo.
Para los modelos Hugging Face: Las descripciones se extraen automáticamente de la tarjeta del modelo en Hugging Face Hub. El script intenta usar el nombre del modelo del índice o la primera línea de la descripción.

Después de descargar los modelos, se recomienda verificar las descripciones en models/model_descriptions.json y ajustarlas si es necesario para proporcionar información más precisa o detallada sobre las capacidades y los casos de uso de los modelos.

🤝 Contribuyendo

Estructura del directorio

Este repositorio está organizado de la siguiente manera:

.
├── .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.

Configuración de desarrollo

Clonar el repositorio:

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

(Recomendado) Crear y activar un entorno virtual:

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

Instale el paquete en modo editable junto con las dependencias de desarrollo:

pip install -e ".[dev]"

Esto instalará imagesorcery-mcp y todas las dependencias de [project.dependencies] y [project.optional-dependencies].dev (incluidos build y twine ).

Normas

Estas reglas se aplican a todos los contribuyentes: humanos e IA.

Lea todos los archivos README.md del proyecto. Comprenda la estructura y el propósito del proyecto. Entienda las pautas para contribuir. Analice cómo se relaciona con su tarea y cómo realizar los cambios correspondientes.
Lea pyproject.toml . Preste atención a las secciones: [tool.ruff] , [tool.ruff.lint] , [project.optional-dependencies] y [project]dependencies . Siga estrictamente el estilo de código definido en pyproject.toml . Respete la pila definida en las dependencias pyproject.toml y no agregue nuevas dependencias sin una buena razón.
Escriba su código en archivos nuevos y existentes. Si necesita nuevas dependencias, actualice pyproject.toml e instálelas mediante pip install -e . o pip install -e ".[dev]" . No las instale directamente mediante pip install . Consulte los códigos fuente existentes para obtener ejemplos (p. ej. src/imagesorcery_mcp/server.py o src/imagesorcery_mcp/tools/crop.py ). Respete el estilo del código, las convenciones de nomenclatura, los formatos de datos de entrada y salida, la estructura del código, la arquitectura, etc. del código existente.
Actualice los archivos README.md relacionados con los cambios. Respete el formato y la estructura de los archivos README.md existentes.
Escribe pruebas para tu código. Consulta ejemplos de pruebas existentes (p. ej., tests/test_server.py o tests/tools/test_crop.py ). Respeta el estilo del código, las convenciones de nomenclatura, los formatos de datos de entrada y salida, la estructura del código, la arquitectura, etc., de las pruebas existentes.
Ejecute pruebas y linter para asegurarse de que todo funciona:

pytest
ruff check .

En caso de fallos, corrija el código y las pruebas. Es estrictamente necesario que todo el código nuevo cumpla con las reglas del linter y supere todas las pruebas.

Consejos de codificación

Utilice sugerencias de tipo cuando sea apropiado
Utilice Pydantic para la validación y serialización de datos

¿Preguntas?

Si tiene alguna pregunta, problema o sugerencia con respecto a este proyecto, no dude en comunicarse con:

Autor del proyecto: titulus vía LinkedIn
Vlad Karm , director ejecutivo de Sunrise Apps, a través de LinkedIn

También puedes abrir un problema en el repositorio para informes de errores o solicitudes de funciones.

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Esto significa que usted tiene libertad de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT.

🪄 ImageSorcery MCP