🪄 ImageSorcery MCP

这些依赖通常包含在 OpenCV 安装中，无需单独安装。但在某些虚拟环境（如 Docker）中可能缺失。

对于 Ubuntu/Debian 系统：

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

对于 Docker 容器： 将这一行添加到 Dockerfile 中：

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

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.

0. 安装 pipx（如果尚未安装）：

   # 在 macOS 上使用 Homebrew：
   brew install pipx
   
   # 在 Ubuntu/Debian 上：
   sudo apt update && sudo apt install pipx
   
   # 在其他使用 pip 的系统上：
   pip install --user pipx
   pipx ensurepath
   

为了可靠地安装所有组件，尤其是通过安装后脚本安装的 clip 包，强烈建议使用 Python 内置的 venv 模块，而不是 uv venv。

1. 创建并激活虚拟环境：

   python -m venv imagesorcery-mcp
   source imagesorcery-mcp/bin/activate  # 适用于 Linux/macOS
   # source imagesorcery-mcp\Scripts\activate    # 适用于 Windows
   

2. 将软件包安装到已激活的虚拟环境中： 可以使用 pip 或 uv pip。

   pip install imagesorcery-mcp
   # OR, 如果你更倾向于使用 uv 在虚拟环境中安装：
   # uv pip install imagesorcery-mcp
   

3. 运行安装后脚本： 这一步至关重要。它会下载所需的模型，并尝试将 clip Python 包从 GitHub 安装到当前激活的虚拟环境中。

   imagesorcery-mcp --post-install
   

**注意：**使用此方法时，需要在 MCP 客户端配置中提供可执行文件的完整路径（例如，/full/path/to/venv/bin/imagesorcery-mcp）。

• 在当前目录中创建 config.toml 配置文件，方便用户自定义默认工具参数。
• 创建 models 目录（通常位于虚拟环境的 site-packages 目录中；如果是全局安装，则位于用户专属位置），用于存储预训练模型。
• 在该目录中生成初始的 models/model_descriptions.json 文件。
• 将 detect 工具所需的默认 YOLO 模型（yoloe-11l-seg-pf.pt、yoloe-11s-seg-pf.pt、yoloe-11l-seg.pt、yoloe-11s-seg.pt）下载到此 models 目录中。
• 尝试从 Ultralytics 的 GitHub 仓库将 clip Python 包安装到当前 Python 环境中。find 工具的文本提示词功能需要此包。
• 将 find 工具所需的 CLIP 模型文件下载到 models 目录中。

你可以随时运行此流程，以恢复默认模型并尝试安装 clip。

• 使用 uv venv 创建虚拟环境： 根据测试，使用 uv venv 创建的虚拟环境可能未以适当方式包含 pip，导致 imagesorcery-mcp --post-install 脚本无法自动从 GitHub 安装 clip 包（安装 clip 时可能出现 “No module named pip” 错误）。 如果选择使用 uv venv：

  1. 创建并激活 uv venv。
  2. 安装 imagesorcery-mcp：uv pip install imagesorcery-mcp。
  3. 手动将 clip 包安装到当前激活的 uv venv 中：

     uv pip install git+https://github.com/ultralytics/CLIP.git
     

  4. 运行 imagesorcery-mcp --post-install。此操作会下载模型，但可能无法安装 clip Python 包。 若要通过安装后脚本更顺利地自动安装 clip，建议使用 python -m venv（如上文步骤 1 所述）创建虚拟环境。

• 使用 uvx imagesorcery-mcp --post-install： 直接使用 uvx 运行安装后脚本（例如 uvx imagesorcery-mcp --post-install）很可能无法安装 clip Python 包。这是因为 uvx 创建的临时环境通常没有可供脚本使用的 pip。模型会下载，但此命令不会安装 clip 包。 如果你打算使用 uvx 运行主要的 imagesorcery-mcp 服务，并且需要 clip 功能，则需要确保 clip 包已安装在 uvx 可找到的 Python 环境中；或者考虑将 imagesorcery-mcp 安装到使用 python -m venv 创建的持久环境中。

"mcpServers": {
    "imagesorcery-mcp": {
      "url": "http://127.0.0.1:8000/mcp", // Use your custom host, port, and path if specified
      "transportType": "http",
      "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"],
      "timeout": 100
    }
}

适用于 pipx 安装（推荐）：

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe",
      "transportType": "stdio",
      "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"],
      "timeout": 100
    }
}

适用于手动 venv 安装：

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe",
      "transportType": "stdio",
      "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"],
      "timeout": 100
    }
}

下载模型时，脚本会自动更新 models/model_descriptions.json 文件：

• 对于 Ultralytics 模型：描述预先定义在 src/imagesorcery_mcp/scripts/create_model_descriptions.py 中，其中包含每个模型的用途、大小和特征等详细信息。

• 对于 Hugging Face 模型：描述会自动从 Hugging Face Hub 上的模型卡提取。脚本会尝试使用模型索引中的模型名称或描述的第一行。

下载模型后，建议检查 models/model_descriptions.json 中的描述，并根据需要进行调整，以便更准确或详细地说明模型的功能和使用场景。

1. STDIO 模式（默认） - 这是本地 MCP 客户端的标准模式：

   imagesorcery-mcp
   

2. Streamable HTTP 模式 - 用于基于 Web 的部署：

   imagesorcery-mcp --transport=streamable-http
   

   使用自定义主机、端口和路径：

   imagesorcery-mcp --transport=streamable-http --host=0.0.0.0 --port=4200 --path=/custom-path
   

可用的传输选项：

• --transport：在 "stdio"（默认）、"streamable-http" 或 "sse" 之间选择
• --host：指定基于 HTTP 的传输所用的主机（默认：127.0.0.1）
• --port：指定基于 HTTP 的传输所用的端口（默认：8000）
• --path：指定基于 HTTP 的传输所用的端点路径（默认：/mcp）

目录结构

此代码库的组织结构如下：

.
├── .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.
│       ├── README.md            # High-level overview of the core architecture (server and middleware).
│       ├── __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.
│       ├── middleware.py        # Custom middleware for improved validation error handling.
│       ├── 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      # Makes `tools` a Python package.
│       │   └── *.py           # Implements the tool.
│       ├── prompts/             # Contains the implementation of individual MCP prompts.
│       │   ├── README.md        # Documentation for the prompts.
│       │   ├── __init__.py      # Makes `prompts` a Python package.
│       │   └── *.py           # Implements the prompt.
│       └── resources/           # Contains the implementation of individual MCP resources.
│           ├── README.md        # Documentation for the resources.
│           ├── __init__.py      # Makes `resources` a Python package.
│           └── *.py           # Implements the resource.
└── 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.
    ├── prompts/               # Contains tests for individual prompts.
    └── resources/             # Contains tests for individual resources.

开发环境设置

1. 克隆仓库：

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

2. （推荐）创建并激活虚拟环境：

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

3. 以可编辑模式安装软件包及开发依赖：

pip install -e ".[dev]"

这将安装 imagesorcery-mcp，以及 [project.dependencies] 和 [project.optional-dependencies].dev 中的所有依赖（包括 build 和 twine）。

规则

以下规则适用于所有贡献者：人类和 AI。

0. 阅读项目中的所有 README.md 文件。了解项目结构和用途，并熟悉贡献指南。仔细思考这些内容与任务的关系，以及如何据此进行修改。

1. 阅读 pyproject.toml。 请特别关注以下部分：[tool.ruff]、[tool.ruff.lint]、[project.optional-dependencies] 和 [project]dependencies。 严格遵循 pyproject.toml 中定义的代码风格。 使用 pyproject.toml 依赖项中定义的技术栈，除非有充分理由，否则不要添加新依赖。

2. 在新建或现有文件中编写代码。 如果需要新依赖，请更新 pyproject.toml，并通过 pip install -e . 或 pip install -e ".[dev]" 安装。不要直接通过 pip install 安装依赖。 查看现有源代码以获取示例（例如 src/imagesorcery_mcp/server.py、src/imagesorcery_mcp/tools/crop.py）。遵循现有代码的风格、命名约定、输入和输出数据格式、代码结构、架构等。

3. 根据所做更改更新相关的 README.md 文件。 遵循现有 README.md 文件的格式和结构。

4. 为代码编写测试。 查看现有测试以获取示例（例如 tests/test_server.py、tests/tools/test_crop.py）。 遵循现有测试的风格、命名约定、输入和输出数据格式、代码结构、架构等。

5. 运行测试和代码检查工具，确保一切正常：

pytest
ruff check .

如果失败，请修复代码和测试。必须确保所有新增代码符合代码检查规则并通过所有测试。

编码提示

• 适当使用类型提示
• 使用 pydantic 进行数据验证和序列化