Skip to content
Back to search

imagesorcery-mcp

An MCP server providing tools for image processing operations

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sunriseapps--imagesorcery-mcp/badge.svg)](/listings/sunriseapps--imagesorcery-mcp)

HTML

<a href="/listings/sunriseapps--imagesorcery-mcp"><img src="/api/listings/sunriseapps--imagesorcery-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements

- `Python 3.10` or higher - `pipx` (recommended) - for easy installation and virtual environment management - `ffmpeg`, `libsm6`, `libxext6`, `libgl1-mesa-glx` - system libraries required by OpenCV - `Claude.app`, `Cline`, or another MCP client

<details> <summary>Virtual environments (e.g. Docker)</summary>

These dependencies are typically included with OpenCV installation and don't require separate installation. But they might be missing in some virtual environments like Docker.

**For Ubuntu/Debian systems:**

sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

**For Docker containers:** Add this line to your Dockerfile:

RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

</details>

Installation

<details> <summary>For Cline just copy-paste LLM-INSTALL.md</summary>

1.  Load MCP documentation if you have the tool for it. It will give you path to *MCP-configuration file* and other needed instructions.
2.  Run command `pipx install imagesorcery-mcp`
3.  Run command `imagesorcery-mcp --post-install`
4.  Create or modify *MCP-configuration file*.
5.  Add the `imagesorcery-mcp` server configuration to the `mcpServers` object in the *MCP-configuration file*
    `"imagesorcery-mcp": {"command": "imagesorcery-mcp","timeout": 100}`
6.  Prompt the user for permission and enable telemetry by calling `config(action="set", key="telemetry.enabled", value=True, persist=True)`.
7.  Attempt completion, indicating that the installation and configuration are complete.

</details>

Method 1: Using pipx (Recommended)

`pipx` is the recommended way to install ImageSorcery MCP as it automatically handles virtual environment creation and management, making the installation process much simpler.

<details> <summary>0. Install pipx (if not already installed):</summary>

0. **Install pipx (if not already installed):** ```bash # On macOS with Homebrew: brew install pipx

# On Ubuntu/Debian: sudo apt update && sudo apt install pipx

# On other systems with pip: pip install --user pipx pipx ensurepath ``` </details>

1. **Install ImageSorcery MCP with pipx:** ```bash pipx install imagesorcery-mcp ```

2. **Run the post-installation script:** This step is crucial. It downloads the required models and attempts to install the `clip` Python package from GitHub. ```bash imagesorcery-mcp --post-install ```

Method 2: Manual Virtual Environment (Plan B)

<details> <summary>If pipx doesn't work for your system, you can manually create a virtual environment</summary>

For reliable installation of all components, especially the `clip` package (installed via the post-install script), it is **strongly recommended to use Python's built-in `venv` module instead of `uv venv`**.

1. **Create and activate a virtual environment:** ```bash python -m venv imagesorcery-mcp source imagesorcery-mcp/bin/activate # For Linux/macOS # source imagesorcery-mcp\Scripts\activate # For Windows ```

2. **Install the package into the activated virtual environment:** You can use `pip` or `uv pip`. ```bash pip install imagesorcery-mcp # OR, if you prefer using uv for installation into the venv: # uv pip install imagesorcery-mcp ```

3. **Run the post-installation script:** This step is crucial. It downloads the required models and attempts to install the `clip` Python package from GitHub into the active virtual environment. ```bash imagesorcery-mcp --post-install ```

**Note:** When using this method, you'll need to provide the full path to the executable in your MCP client configuration (e.g., `/full/path/to/venv/bin/imagesorcery-mcp`). </details>

Additional Notes

<details> <summary>What does the post-installation script do?</summary> The `imagesorcery-mcp --post-install` script performs the following actions:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 496 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🪄 ImageSorcery MCP
  2. **ComputerVision-based 🪄 sorcery of local image recognition and editing tools for AI assistants**
  3. Official website: [imagesorcery.net](https://imagesorcery.net?utm_source=readme)
  4. [![License](https://img.shields.io/badge/License-MIT-green)](https://opensource.org/licenses/MIT) [![MCP](https://img.shields.io/badge/Protocol-MCP-lightgrey)](https://github.com/microsoft/mcp)
  5. [![Claude](https://img.shields.io/badge/Works_with-Claude-orange)](https://claude.ai) [![Cursor](https://img.shields.io/badge/Works_with-Cursor-white)](https://cursor.so) [![Cline](https://img.shields.io/badge/Works_with-Cline-purple)](https://github.com/ClineLabs/cline)
  6. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/2620351a-15b1-4840-a93a-cbdbd23a6944) [![PyPI Downloads](https://static.pepy.tech/badge/imagesorcery-mcp)](https://pepy.tech/projects/imagesorcery-mcp)
  7. <a href="https://glama.ai/mcp/servers/@sunriseapps/imagesorcery-mcp">
  8. <img width="380" height="200" src="https://glama.ai/mcp/servers/@sunriseapps/imagesorcery-mcp/badge" />
  9. </a>
  10. ## ✅ With ImageSorcery MCP
  11. `🪄 ImageSorcery` empowers AI assistants with powerful image processing capabilities:
  12. - ✅ Crop, resize, and rotate images with precision
  13. - ✅ Remove background
  14. - ✅ Draw text and shapes on images
  15. - ✅ Add logos and watermarks
  16. - ✅ Detect objects using state-of-the-art models
  17. - ✅ Extract text from images with OCR
  18. - ✅ Use a wide range of pre-trained models for object detection, OCR, and more
  19. - ✅ Do all of this **locally**, without sending your images to any servers
  20. Just ask your AI to help with image tasks:
  21. > "copy photos with pets from folder `photos` to folder `pets`"
  22. ![Copying pets](https://i.imgur.com/wsaDWbf.gif)
  23. > "Find a cat at the photo.jpg and crop the image in a half in height and width to make the cat be centered"
  24. ![Centerizing cat](https://i.imgur.com/tD0O3l6.gif)
  25. 😉 _**Hint:** Use full path to your files"._
  26. > "Enumerate form fields on this `form.jpg` with `foduucom/web-form-ui-field-detection` model and fill the `form.md` with a list of described fields"
  27. ![Numerate form fields](https://i.imgur.com/1SNGfaP.gif)
  28. 😉 _**Hint:** Specify the model and the confidence"._
  29. 😉 _**Hint:** Add "use imagesorcery" to make sure it will use the proper tool"._
  30. Your tool will combine multiple tools listed below to achieve your goal.
  31. ## 🛠️ Available Tools
  32. | Tool | Description | Example Prompt |
  33. |------|-------------|----------------|
  34. | `blur` | Blurs specified rectangular or polygonal areas of an image using OpenCV. Can also invert the provided areas e.g. to blur background. | "Blur the area from (150, 100) to (250, 200) with a blur strength of 21 in my image 'test_image.png' and save it as 'output.png'" |
  35. | `change_color` | Changes the color palette of an image | "Convert my image 'test_image.png' to sepia and save it as 'output.png'" |
  36. | `config` | View and update ImageSorcery MCP configuration settings | "Show me the current configuration" or "Set the default detection confidence to 0.8" |
  37. | `crop` | Crops an image using OpenCV's NumPy slicing approach | "Crop my image 'input.png' from coordinates (10,10) to (200,200) and save it as 'cropped.png'" |
  38. | `detect` | Detects objects in an image using models from Ultralytics. Can return segmentation masks (as PNG files) or polygons. | "Detect objects in my image 'photo.jpg' with a confidence threshold of 0.4" |
  39. | `draw_arrows` | Draws arrows on an image using OpenCV | "Draw a red arrow from (50,50) to (150,100) on my image 'photo.jpg'" |
  40. | `draw_circles` | Draws circles on an image using OpenCV | "Draw a red circle with center (100,100) and radius 50 on my image 'photo.jpg'" |
  41. | `draw_lines` | Draws lines on an image using OpenCV | "Draw a red line from (50,50) to (150,100) on my image 'photo.jpg'" |
  42. | `draw_rectangles` | Draws rectangles on an image using OpenCV | "Draw a red rectangle from (50,50) to (150,100) and a filled blue rectangle from (200,150) to (300,250) on my image 'photo.jpg'" |
  43. | `draw_texts` | Draws text on an image using OpenCV | "Add text 'Hello World' at position (50,50) and 'Copyright 2023' at the bottom right corner of my image 'photo.jpg'" |
  44. | `fill` | Fills specified rectangular, polygonal, or mask-based areas of an image with a color and opacity, or makes them transparent. Can also invert the provided areas e.g. to remove background. | "Fill the area from (150, 100) to (250, 200) with semi-transparent red in my image 'test_image.png'" |
  45. | `find` | Finds objects in an image based on a text description. Can return segmentation masks (as PNG files) or polygons. | "Find all dogs in my image 'photo.jpg' with a confidence threshold of 0.4" |
  46. | `get_metainfo` | Gets metadata information about an image file | "Get metadata information about my image 'photo.jpg'" |
  47. | `ocr` | Performs Optical Character Recognition (OCR) on an image using EasyOCR | "Extract text from my image 'document.jpg' using OCR with English language" |
  48. | `overlay` | Overlays one image on top of another, handling transparency | "Overlay 'logo.png' on top of 'background.jpg' at position (10, 10)" |
  49. | `resize` | Resizes an image using OpenCV | "Resize my image 'photo.jpg' to 800x600 pixels and save it as 'resized_photo.jpg'" |
  50. | `rotate` | Rotates an image using imutils.rotate_bound function | "Rotate my image 'photo.jpg' by 45 degrees and save it as 'rotated_photo.jpg'" |
  51. 😉 _**Hint:** detailed information and usage instructions for each tool can be found in the tool's `/src/imagesorcery_mcp/tools/README.md`._
  52. ## 📚 Available Resources
  53. | Resource URI | Description | Example Prompt |
  54. |--------------|-------------|----------------|
  55. | `models://list` | Lists all available models in the models directory | "Which models are available in ImageSorcery?" |
  56. 😉 _**Hint:** detailed information and usage instructions for each resource can be found in the resource's `/src/imagesorcery_mcp/resources/README.md`._
  57. ## 💬 Available Prompts
  58. | Prompt Name | Description | Example Usage |
  59. |-------------|-------------|---------------|
  60. | `remove-background` | Guides the AI through a comprehensive background removal workflow using object detection and masking tools | "Use the remove-background prompt to remove the background from my photo 'portrait.jpg', keeping only the person" |
  61. 😉 _**Hint:** detailed information and usage instructions for each prompt can be found in the prompt's `/src/imagesorcery_mcp/prompts/README.md`._
  62. ## 🚀 Getting Started
  63. ### Requirements
  64. - `Python 3.10` or higher
  65. - `pipx` (recommended) - for easy installation and virtual environment management
  66. - `ffmpeg`, `libsm6`, `libxext6`, `libgl1-mesa-glx` - system libraries required by OpenCV
  67. - `Claude.app`, `Cline`, or another MCP client
  68. <details>
  69. <summary>Virtual environments (e.g. Docker)</summary>
  70. These dependencies are typically included with OpenCV installation and don't require separate installation. But they might be missing in some virtual environments like Docker.
  71. **For Ubuntu/Debian systems:**
  72. ```bash
  73. sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx
  74. ```
  75. **For Docker containers:**
  76. Add this line to your Dockerfile:
  77. ```dockerfile
  78. RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx
  79. ```
  80. </details>
  81. ### Installation
  82. ![ImageSorcery Demo](https://i.imgur.com/pRfTlHV.gif)
  83. <details>
  84. <summary>For Cline just copy-paste LLM-INSTALL.md</summary>
  85. ```md
  86. 1. Load MCP documentation if you have the tool for it. It will give you path to *MCP-configuration file* and other needed instructions.
  87. 2. Run command `pipx install imagesorcery-mcp`
  88. 3. Run command `imagesorcery-mcp --post-install`
  89. 4. Create or modify *MCP-configuration file*.
  90. 5. Add the `imagesorcery-mcp` server configuration to the `mcpServers` object in the *MCP-configuration file*
  91. `"imagesorcery-mcp": {"command": "imagesorcery-mcp","timeout": 100}`
  92. 6. Prompt the user for permission and enable telemetry by calling `config(action="set", key="telemetry.enabled", value=True, persist=True)`.
  93. 7. Attempt completion, indicating that the installation and configuration are complete.
  94. ```
  95. </details>
  96. #### Method 1: Using pipx (Recommended)
  97. `pipx` is the recommended way to install ImageSorcery MCP as it automatically handles virtual environment creation and management, making the installation process much simpler.
  98. <details>
  99. <summary>0. Install pipx (if not already installed):</summary>
  100. 0. **Install pipx (if not already installed):**
  101. ```bash
  102. # On macOS with Homebrew:
  103. brew install pipx
  104. # On Ubuntu/Debian:
  105. sudo apt update && sudo apt install pipx
  106. # On other systems with pip:
  107. pip install --user pipx
  108. pipx ensurepath
  109. ```
  110. </details>
  111. 1. **Install ImageSorcery MCP with pipx:**
  112. ```bash
  113. pipx install imagesorcery-mcp
  114. ```
  115. 2. **Run the post-installation script:**
  116. This step is crucial. It downloads the required models and attempts to install the `clip` Python package from GitHub.
  117. ```bash
  118. imagesorcery-mcp --post-install
  119. ```
  120. #### Method 2: Manual Virtual Environment (Plan B)
  121. <details>
  122. <summary>If pipx doesn't work for your system, you can manually create a virtual environment</summary>
  123. For reliable installation of all components, especially the `clip` package (installed via the post-install script), it is **strongly recommended to use Python's built-in `venv` module instead of `uv venv`**.
  124. 1. **Create and activate a virtual environment:**
  125. ```bash
  126. python -m venv imagesorcery-mcp
  127. source imagesorcery-mcp/bin/activate # For Linux/macOS
  128. # source imagesorcery-mcp\Scripts\activate # For Windows
  129. ```
  130. 2. **Install the package into the activated virtual environment:**
  131. You can use `pip` or `uv pip`.
  132. ```bash
  133. pip install imagesorcery-mcp
  134. # OR, if you prefer using uv for installation into the venv:
  135. # uv pip install imagesorcery-mcp
  136. ```
  137. 3. **Run the post-installation script:**
  138. This step is crucial. It downloads the required models and attempts to install the `clip` Python package from GitHub into the active virtual environment.
  139. ```bash
  140. imagesorcery-mcp --post-install
  141. ```
  142. **Note:** When using this method, you'll need to provide the full path to the executable in your MCP client configuration (e.g., `/full/path/to/venv/bin/imagesorcery-mcp`).
  143. </details>
  144. #### Additional Notes
  145. <details>
  146. <summary>What does the post-installation script do?</summary>
  147. The `imagesorcery-mcp --post-install` script performs the following actions:
  148. - **Creates a `config.toml` configuration file** in the current directory, allowing users to customize default tool parameters.
  149. - Creates a `models` directory (usually within the site-packages directory of your virtual environment, or a user-specific location if installed globally) to store pre-trained models.
  150. - Generates an initial `models/model_descriptions.json` file there.
  151. - 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 into this `models` directory.
  152. - **Attempts to install the `clip` Python package** from Ultralytics' GitHub repository directly into the active Python environment. This is required for text prompt functionality in the `find` tool.
  153. - Downloads the CLIP model file required by the `find` tool into the `models` directory.
  154. You can run this process anytime to restore the default models and attempt `clip` installation.
  155. </details>
  156. <details>
  157. <summary>Important Notes for `uv` users (<code>uv venv</code> and <code>uvx</code>)</summary>
  158. - **Using `uv venv` to create virtual environments:**
  159. Based on testing, virtual environments created with `uv venv` may not include `pip` in a way that allows the `imagesorcery-mcp --post-install` script to automatically install the `clip` package from GitHub (it might result in a "No module named pip" error during the `clip` installation step).
  160. **If you choose to use `uv venv`:**
  161. 1. Create and activate your `uv venv`.
  162. 2. Install `imagesorcery-mcp`: `uv pip install imagesorcery-mcp`.
  163. 3. Manually install the `clip` package into your active `uv venv`:
  164. ```bash
  165. uv pip install git+https://github.com/ultralytics/CLIP.git
  166. ```
  167. 3. Run `imagesorcery-mcp --post-install`. This will download models but may fail to install the `clip` Python package.
  168. For a smoother automated `clip` installation via the post-install script, using `python -m venv` (as described in step 1 above) is the recommended method for creating the virtual environment.
  169. - **Using `uvx imagesorcery-mcp --post-install`:**
  170. Running the post-installation script directly with `uvx` (e.g., `uvx imagesorcery-mcp --post-install`) will likely fail to install the `clip` Python package. This is because the temporary environment created by `uvx` typically does not have `pip` available in a way the script can use. Models will be downloaded, but the `clip` package won't be installed by this command.
  171. If you intend to use `uvx` to run the main `imagesorcery-mcp` server and require `clip` functionality, you'll need to ensure the `clip` package is installed in an accessible Python environment that `uvx` can find, or consider installing `imagesorcery-mcp` into a persistent environment created with `python -m venv`.
  172. </details>
  173. ## ⚙️ Configure MCP client
  174. Add to your MCP client these settings.
  175. **For pipx installation (recommended):**
  176. ```json
  177. "mcpServers": {
  178. "imagesorcery-mcp": {
  179. "command": "imagesorcery-mcp",
  180. "transportType": "stdio",
  181. "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
  182. "timeout": 100
  183. }
  184. }
  185. ```
  186. **For manual venv installation:**
  187. ```json
  188. "mcpServers": {
  189. "imagesorcery-mcp": {
  190. "command": "/full/path/to/venv/bin/imagesorcery-mcp",
  191. "transportType": "stdio",
  192. "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
  193. "timeout": 100
  194. }
  195. }
  196. ```
  197. <details>
  198. <summary>If you're using the server in HTTP mode, configure your client to connect to the HTTP endpoint:</summary>
  199. ```json
  200. "mcpServers": {
  201. "imagesorcery-mcp": {
  202. "url": "http://127.0.0.1:8000/mcp", // Use your custom host, port, and path if specified
  203. "transportType": "http",
  204. "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
  205. "timeout": 100
  206. }
  207. }
  208. ```
  209. </details>
  210. <details>
  211. <summary>For Windows</summary>
  212. **For pipx installation (recommended):**
  213. ```json
  214. "mcpServers": {
  215. "imagesorcery-mcp": {
  216. "command": "imagesorcery-mcp.exe",
  217. "transportType": "stdio",
  218. "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
  219. "timeout": 100
  220. }
  221. }
  222. ```
  223. **For manual venv installation:**
  224. ```json
  225. "mcpServers": {
  226. "imagesorcery-mcp": {
  227. "command": "C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe",
  228. "transportType": "stdio",
  229. "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
  230. "timeout": 100
  231. }
  232. }
  233. ```
  234. </details>
  235. ## 📦 Additional Models
  236. Some tools require specific models to be available in the `models` directory:
  237. ```bash
  238. # Download models for the detect tool
  239. download-yolo-models --ultralytics yoloe-11l-seg
  240. download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt
  241. ```
  242. <details>
  243. <summary>About Model Descriptions</summary>
  244. When downloading models, the script automatically updates the `models/model_descriptions.json` file:
  245. - 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.
  246. - 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.
  247. 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.
  248. </details>
  249. ### Running the Server
  250. ImageSorcery MCP server can be run in different modes:
  251. - `STDIO` - default
  252. - `Streamable HTTP` - for web-based deployments
  253. - `Server-Sent Events (SSE)` - for web-based deployments that rely on SSE
  254. <details>
  255. <summary>About different modes:</summary>
  256. 1. **STDIO Mode (Default)** - This is the standard mode for local MCP clients:
  257. ```bash
  258. imagesorcery-mcp
  259. ```
  260. 2. **Streamable HTTP Mode** - For web-based deployments:
  261. ```bash
  262. imagesorcery-mcp --transport=streamable-http
  263. ```
  264. With custom host, port, and path:
  265. ```bash
  266. imagesorcery-mcp --transport=streamable-http --host=0.0.0.0 --port=4200 --path=/custom-path
  267. ```
  268. Available transport options:
  269. - `--transport`: Choose between "stdio" (default), "streamable-http", or "sse"
  270. - `--host`: Specify host for HTTP-based transports (default: 127.0.0.1)
  271. - `--port`: Specify port for HTTP-based transports (default: 8000)
  272. - `--path`: Specify endpoint path for HTTP-based transports (default: /mcp)
  273. </details>
  274. ## 🔐 File Access Restrictions
  275. By default, ImageSorcery MCP does not restrict file paths. To limit tools to specific directories, set `IMAGESORCERY_AVAILABLE_PATHS` to one or more allowed directories.
  276. Use the platform path-list separator (`:` on Linux/macOS, `;` on Windows). Comma-separated values are also accepted.
  277. ```bash
  278. IMAGESORCERY_AVAILABLE_PATHS="/home/user/images:/home/user/output" imagesorcery-mcp
  279. ```
  280. When this variable is set, all tool arguments named `path` or ending with `_path` must resolve inside one of the allowed directories. Relative paths, `..`, and `~` are normalized before comparison. Symlinks are not resolved, so links placed inside allowed directories remain accessible.
  281. ## 🔒 Privacy & Telemetry
  282. We are committed to your privacy. ImageSorcery MCP is designed to run locally, ensuring your images and data stay on your machine.
  283. To help us understand which features are most popular and fix bugs faster, we've included optional, anonymous telemetry.
  284. - **It is disabled by default.** You must explicitly opt-in to enable it.
  285. - **What we collect:** Anonymized usage data, including features used (e.g., `crop`, `detect`), application version, operating system type (e.g., 'linux', 'win32'), and tool failures.
  286. - **What we NEVER collect:** We do not collect any personal or sensitive information. This includes image data, file paths, IP addresses, or any other personally identifiable information.
  287. - **How to enable/disable:** You can control telemetry by setting `enabled = true` or `enabled = false` in the `[telemetry]` section of your `config.toml` file.
  288. ## ⚙️ Configuring the Server
  289. The server can be configured using a `config.toml` file in the current directory. The file is created automatically during installation with default values. You can customize the default tool parameters in this file. More in [CONFIG.md](CONFIG.md).
  290. ## 🤝 Contributing
  291. <details>
  292. <summary>Whether you're a 👤 human or an 🤖 AI agent, we welcome your contributions to this project!</summary>
  293. ### Directory Structure
  294. This repository is organized as follows:
  295. ```
  296. .
  297. ├── .gitignore # Specifies intentionally untracked files that Git should ignore.
  298. ├── pyproject.toml # Configuration file for Python projects, including build system, dependencies, and tool settings.
  299. ├── pytest.ini # Configuration file for the pytest testing framework.
  300. ├── README.md # The main documentation file for the project.
  301. ├── setup.sh # A shell script for quick setup (legacy, for reference or local use).
  302. ├── 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.
  303. │ ├── model_descriptions.json # Contains descriptions of the available models.
  304. │ ├── settings.json # Contains settings related to model management and training runs.
  305. │ └── *.pt # Pre-trained model.
  306. ├── src/ # Contains the source code for the 🪄 ImageSorcery MCP server.
  307. │ └── imagesorcery_mcp/ # The main package directory for the server.
  308. │ ├── README.md # High-level overview of the core architecture (server and middleware).
  309. │ ├── __init__.py # Makes `imagesorcery_mcp` a Python package.
  310. │ ├── __main__.py # Entry point for running the package as a script.
  311. │ ├── logging_config.py # Configures the logging for the server.
  312. │ ├── server.py # The main server file, responsible for initializing FastMCP and registering tools.
  313. │ ├── middleware.py # Custom middleware for improved validation error handling.
  314. │ ├── logs/ # Directory for storing server logs.
  315. │ ├── scripts/ # Contains utility scripts for model management.
  316. │ │ ├── README.md # Documentation for the scripts.
  317. │ │ ├── __init__.py # Makes `scripts` a Python package.
  318. │ │ ├── create_model_descriptions.py # Script to generate model descriptions.
  319. │ │ ├── download_clip.py # Script to download CLIP models.
  320. │ │ ├── post_install.py # Script to run post-installation tasks.
  321. │ │ └── download_models.py # Script to download other models (e.g., YOLO).
  322. │ ├── tools/ # Contains the implementation of individual MCP tools.
  323. │ │ ├── README.md # Documentation for the tools.
  324. │ │ ├── __init__.py # Makes `tools` a Python package.
  325. │ │ └── *.py # Implements the tool.
  326. │ ├── prompts/ # Contains the implementation of individual MCP prompts.
  327. │ │ ├── README.md # Documentation for the prompts.
  328. │ │ ├── __init__.py # Makes `prompts` a Python package.
  329. │ │ └── *.py # Implements the prompt.
  330. │ └── resources/ # Contains the implementation of individual MCP resources.
  331. │ ├── README.md # Documentation for the resources.
  332. │ ├── __init__.py # Makes `resources` a Python package.
  333. │ └── *.py # Implements the resource.
  334. └── tests/ # Contains test files for the project.
  335. ├── test_server.py # Tests for the main server functionality.
  336. ├── data/ # Contains test data, likely image files used in tests.
  337. ├── tools/ # Contains tests for individual tools.
  338. ├── prompts/ # Contains tests for individual prompts.
  339. └── resources/ # Contains tests for individual resources.
  340. ```
  341. ### Development Setup
  342. 1. Clone the repository:
  343. ```bash
  344. git clone https://github.com/sunriseapps/imagesorcery-mcp.git # Or your fork
  345. cd imagesorcery-mcp
  346. ```
  347. 2. (Recommended) Create and activate a virtual environment:
  348. ```bash
  349. python -m venv venv
  350. source venv/bin/activate # For Linux/macOS
  351. # venv\Scripts\activate # For Windows
  352. ```
  353. 3. Install the package in editable mode along with development dependencies:
  354. ```bash
  355. pip install -e ".[dev]"
  356. ```
  357. This will install `imagesorcery-mcp` and all dependencies from `[project.dependencies]` and `[project.optional-dependencies].dev` (including `build` and `twine`).
  358. ### Rules
  359. These rules apply to all contributors: humans and AI.
  360. 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 relates to your task, and how to make changes accordingly.
  361. 1. Read `pyproject.toml`.
  362. Pay attention to sections: `[tool.ruff]`, `[tool.ruff.lint]`, `[project.optional-dependencies]` and `[project]dependencies`.
  363. Strictly follow code style defined in `pyproject.toml`.
  364. Stick to the stack defined in `pyproject.toml` dependencies and do not add any new dependencies without a good reason.
  365. 2. Write your code in new and existing files.
  366. If new dependencies are needed, update `pyproject.toml` and install them via `pip install -e .` or `pip install -e ".[dev]"`. Do not install them directly via `pip install`.
  367. Check out existing 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 output data formats, code structure, architecture, etc. of the existing code.
  368. 3. Update related `README.md` files with your changes.
  369. Stick to the format and structure of the existing `README.md` files.
  370. 4. Write tests for your code.
  371. Check out existing tests for examples (e.g. `tests/test_server.py`, `tests/tools/test_crop.py`).
  372. Stick to the code style, naming conventions, input and output data formats, code structure, architecture, etc. of the existing tests.
  373. 5. Run tests and linter to ensure everything works:
  374. ```bash
  375. pytest
  376. ruff check .
  377. ```
  378. In case of failures - fix the code and tests. It is **strictly required** to have all new code to comply with the linter rules and pass all tests.
  379. ### Coding hints
  380. - Use type hints where appropriate
  381. - Use pydantic for data validation and serialization
  382. </details>
  383. ## 📝 Questions?
  384. If you have any questions, issues, or suggestions regarding this project, feel free to reach out to:
  385. - Project Author: [titulus](https://www.linkedin.com/in/titulus/) via LinkedIn
  386. - Sunrise Apps CEO: [Vlad Karm](https://www.linkedin.com/in/vladkarm/) via LinkedIn
  387. You can also open an issue in the repository for bug reports or feature requests.
  388. ## 📜 License
  389. This project is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.