• Creates a models directory to store pre-trained models.
• Generates the initial models/model_descriptions.json file.
• Downloads default YOLO models (yoloe-11l-seg-pf.pt, yoloe-11s-seg-pf.pt, yoloe-11l-seg.pt, yoloe-11s-seg.pt) required by the detect tool.
• Installs the clip Python package from Ultralytics' GitHub repository (required for text prompts with the find tool).
• Downloads the CLIP model file required by the find tool.

You can run this process anytime to restore the default models.

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

When downloading models, the script automatically updates the models/model_descriptions.json file:

• For Ultralytics models: Descriptions are predefined in src/imagesorcery_mcp/scripts/create_model_descriptions.py and include detailed information about each model's purpose, size, and characteristics.

• For Hugging Face models: Descriptions are automatically extracted from the model card on Hugging Face Hub. The script attempts to use the model name from the model index or the first line of the description.

After downloading models, it's recommended to check the descriptions in models/model_descriptions.json and adjust them if needed to provide more accurate or detailed information about the models' capabilities and use cases.

Directory Structure

This repository is organized as follows:

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

Development Setup

1. Clone the repository:

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

2. (Recommended) Create and activate a virtual environment:

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

3. Install the package in editable mode along with development dependencies:

pip install -e ".[dev]"

This will install imagesorcery-mcp and all dependencies from [project.dependencies] and [project.optional-dependencies].dev (including build and twine).

Rules

These rules apply to all contributors: humans and AI.

0. Read all the README.md files in the project. Understand the project structure and purpose. Understand the guidelines for contributing. Think through how it's relate to you task, and how to make changes accordingly.

1. Read pyproject.toml. Make attention to sections: [tool.ruff], [tool.ruff.lint], [project.optional-dependencies] and [project]dependencies. Strictly follow code style defined in pyproject.toml. Stick to the stack defined in pyproject.toml dependencies and do not add any new dependencies without a good reason.

2. Write your code in new and existing files. If new dependencies needed, update pyproject.toml and install them via pip install -e . or pip install -e ".[dev]". Do not install them diirectly via pip install. Check out exixisting source codes for examples (e.g. src/imagesorcery_mcp/server.py, src/imagesorcery_mcp/tools/crop.py). Stick to the code style, naming conventions, input and outpput data formats, codeode structure, arcchitecture, etc. of the existing code.

3. Update related README.md files with your changes. Stick to the format and structure of the existing README.md files.

4. Write tests for your code. Check out existing tests for examples (e.g. tests/test_server.py, tests/tools/test_crop.py). Stick to the code style, naming conventions, input and outpput data formats, codeode structure, arcchitecture, etc. of the existing tests.

5. Run tests and linter to ensure everything works:

pytest
ruff check .

In case of fails - fix the code and tests. It is strictly required to have all new code to comply with the linter rules and pass all tests.

Coding hints

• Use type hints where appropriate
• Use pydantic for data validation and serialization