🪄 ImageSorcery MCP

基于计算机视觉的图像识别和编辑工具，适用于AI助手

❌ 没有ImageSorcery MCP

AI助手在处理图像时存在以下限制：

• ❌ 无法直接修改或分析图像
• ❌ 无法裁剪、调整大小或处理图像
• ❌ 某些大语言模型（LLMs）无法检测对象或从图像中提取文本
• ❌ 仅限于口头描述，无法进行视觉操作

✅ 使用ImageSorcery MCP

🪄 ImageSorcery 赋予AI助手强大的图像处理能力：

• ✅ 精确裁剪、调整大小和旋转图像
• ✅ 在图像上绘制文本和形状
• ✅ 使用最先进的模型检测对象
• ✅ 使用OCR从图像中提取文本
• ✅ 获取详细的图像元数据
• ✅ 使用多种预训练模型进行对象检测、OCR等

只需让您的AI助手帮助您完成图像任务：

"将 photos 文件夹中包含宠物的照片复制到 pets 文件夹"

"在 photo.jpg 中找到一只猫，并将图像的高度和宽度裁剪为原来的一半，使猫居中"

😉 提示： 请使用文件的完整路径。

"使用 foduucom/web-form-ui-field-detection 模型对 form.jpg 中的表单字段进行编号，并将描述的字段列表填充到 form.md 中"

😉 提示： 请指定模型和置信度。

😉 提示： 添加 "use imagesorcery" 以确保使用正确的工具。

您的工具将结合以下列出的多个工具来实现您的目标。

🛠️ 可用工具

工具	描述	示例指令
crop	使用OpenCV的NumPy切片方法裁剪图像	"将我的图像 input.png 从坐标 (10,10) 到 (200,200) 裁剪并保存为 cropped.png"
resize	使用OpenCV调整图像大小	"将我的图像 photo.jpg 调整为 800x600 像素并保存为 resized_photo.jpg"
rotate	使用imutils.rotate_bound函数旋转图像	"将我的图像 photo.jpg 旋转45度并保存为 rotated_photo.jpg"
draw_texts	使用OpenCV在图像上绘制文本	"在我的图像 photo.jpg 上添加文本 Hello World 位于位置 (50,50)，并在右下角添加 Copyright 2023"
draw_rectangles	使用OpenCV在图像上绘制矩形	"在我的图像 photo.jpg 上绘制一个从 (50,50) 到 (150,100) 的红色矩形和一个从 (200,150) 到 (300,250) 的蓝色填充矩形"
get_metainfo	获取有关图像文件的元数据信息	"获取我的图像 photo.jpg 的元数据信息"
detect	使用Ultralytics的模型检测图像中的对象	"在我的图像 photo.jpg 中检测对象，置信度阈值为0.4"
find	根据文本描述在图像中查找对象	"在我的图像 photo.jpg 中查找所有狗，置信度阈值为0.4"
get_models	列出模型目录中的所有可用模型	"列出模型目录中的所有可用模型"
ocr	使用EasyOCR对图像进行光学字符识别（OCR）	"使用OCR和英语语言从我的图像 document.jpg 中提取文本"

😉 提示： 有关每个工具的详细信息和使用说明，请参阅工具的 /src/imagesorcery_mcp/tools/README.md。## 🚀 快速开始

要求

• Python 3.10 或更高版本
• Claude.app, Cline 或其他 MCP 客户端

安装

md

1. 如果你有相应的工具，请加载 MCP 文档。它将为你提供 MCP-配置文件 的路径及其他所需说明。
2. 运行命令 python -m venv imagesorcery-mcp
3. 运行命令 source imagesorcery-mcp/bin/activate
   对于 Windows Bash，运行命令 source imagesorcery-mcp/Scripts/activate
   对于 Windows CMD，运行命令 imagesorcery-mcpScriptsactivate
4. 运行命令 pip install imagesorcery-mcp
5. 运行命令 imagesorcery-mcp --post-install
6. 创建或修改 MCP-配置文件。
7. 将 imagesorcery-mcp 服务器配置添加到 MCP-配置文件 中的 mcpServers 对象
   "imagesorcery-mcp": {"command": "/full/path/to/venv/bin/imagesorcery-mcp","timeout": 100}
8. 使用 imagesorcery-mcp 中的 get_models 工具获取可用模型
9. 尝试完成，表明安装和配置已完成。

1. 创建并激活虚拟环境（强烈推荐）：
   为了可靠地安装所有组件，特别是通过 post-install 脚本安装的 clip 包，强烈建议使用 Python 内置的 venv 模块而不是 uv venv。
   bash
   python -m venv imagesorcery-mcp
   source imagesorcery-mcp/bin/activate # 对于 Linux/macOS

   source imagesorcery-mcpScriptsactivate # 对于 Windows

2. 将包安装到已激活的虚拟环境中：
   你可以使用 pip 或 uv pip。
   bash
   pip install imagesorcery-mcp

   或者，如果你更喜欢使用 uv 来安装到虚拟环境中：

   uv pip install imagesorcery-mcp

3. 运行安装后脚本：
   此步骤至关重要。它会下载所需的模型，并尝试将 clip Python 包从 GitHub 安装到活动的虚拟环境中。
   bash
   imagesorcery-mcp --post-install

• 创建一个 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 创建的虚拟环境可能不会以允许 imagesorcery-mcp --post-install 脚本自动从 GitHub 安装 clip 包的方式包含 pip（在 clip 安装步骤中可能会出现 "No module named pip" 错误）。
  如果你选择使用 uv venv：
  1. 创建并激活你的 uv venv。
  2. 安装 imagesorcery-mcp：uv pip install imagesorcery-mcp。
  3. 手动将 clip 包安装到你的活动 uv venv 中：
     bash
     uv pip install git+https://github.com/ultralytics/CLIP.git

• 使用 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 创建的持久环境中。

⚙️ 配置 MCP 客户端

在你的 MCP 客户端中添加以下设置。
如果安装后 imagesorcery-mcp 在系统的 PATH 中，你可以直接使用 imagesorcery-mcp 作为命令。否则，你需要提供可执行文件的完整路径。

json
"mcpServers": {
"imagesorcery-mcp": {
"command": "imagesorcery-mcp", // 或者如果你是在 venv 中安装的，则为 /full/path/to/venv/bin/imagesorcery-mcp
"transportType": "stdio",
"autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
"timeout": 100
}
}

json
"mcpServers": {
"imagesorcery-mcp": {
"command": "imagesorcery-mcp.exe", // 或者如果你是在 venv 中安装的，则为 C:\full\path\to\venv\Scripts\imagesorcery-mcp.exe
"transportType": "stdio",
"autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
"timeout": 100
}
}

📦 额外模型

某些工具需要在 models 目录下有特定的模型：

bash

为 detect 工具下载模型

download-yolo-models --ultralytics yoloe-11l-seg
download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt

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

• 对于 Ultralytics 模型：描述在 src/imagesorcery_mcp/scripts/create_model_descriptions.py 中预定义，并包括每个模型的目的、大小和特性的详细信息。

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

下载模型后，建议检查 models/model_descriptions.json 中的描述，并根据需要调整以提供关于模型功能和用例的更准确或详细的说明。

🤝 贡献

目录结构

此仓库按如下方式组织：

.
├── .gitignore # 指定 Git 应该忽略的未跟踪文件。
├── pyproject.toml # Python 项目的配置文件，包括构建系统、依赖项和工具设置。
├── pytest.ini # pytest 测试框架的配置文件。
├── README.md # 项目的主要文档文件。
├── setup.sh # 快速设置的 shell 脚本（遗留，供参考或本地使用）。
├── models/ # 此目录存储由 detect 和 find 等工具使用的预训练模型。由于文件体积较大，通常被 Git 忽略。
│ ├── model_descriptions.json # 包含可用模型的描述。
│ ├── settings.json # 包含与模型管理和训练运行相关的设置。
│ └── *.pt # 预训练模型。
├── src/ # 包含 🪄 ImageSorcery MCP 服务器的源代码。
│ └── imagesorcery_mcp/ # 服务器的主要包目录。
│ ├── init.py # 使 imagesorcery_mcp 成为一个 Python 包。
│ ├── main.py # 作为脚本运行包的入口点。
│ ├── logging_config.py # 配置服务器的日志记录。
│ ├── server.py # 主服务器文件，负责初始化 FastMCP 并注册工具。
│ ├── logs/ # 存储服务器日志的目录。
│ ├── scripts/ # 包含用于模型管理的实用脚本。
│ │ ├── README.md # 脚本文档。
│ │ ├── init.py # 使 scripts 成为一个 Python 包。
│ │ ├── create_model_descriptions.py # 生成模型描述的脚本。
│ │ ├── download_clip.py # 下载 CLIP 模型的脚本。
│ │ ├── post_install.py # 运行后安装任务的脚本。
│ │ └── download_models.py # 下载其他模型（如 YOLO）的脚本。
│ └── tools/ # 包含各个 MCP 工具的实现。
│ ├── README.md # 工具文档。
│ ├── init.py # 导入中心日志记录器。
│ └── *.py # 实现工具。
└── tests/ # 包含项目的测试文件。
├── test_server.py # 主服务器功能的测试。
├── data/ # 包含测试数据，可能是用于测试的图像文件。
└── tools/ # 包含各个工具的测试。

1. 克隆仓库：
   bash
   git clone https://github.com/sunriseapps/imagesorcery-mcp.git # 或者你的 fork
   cd imagesorcery-mcp

2. (推荐) 创建并激活虚拟环境：
   bash
   python -m venv venv
   source venv/bin/activate # 适用于 Linux/macOS

venvScriptsactivate # 适用于 Windows

1. 以可编辑模式安装包及其开发依赖项：
   bash
   pip install -e ".[dev]"

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

规则

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

1. 阅读项目中的所有 README.md 文件。理解项目的结构和目的。理解贡献指南。思考它们如何与你的任务相关，并相应地进行更改。

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

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

4. 更新相关的 README.md 文件以反映你的更改。
   遵循现有 README.md 文件的格式和结构。

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

6. 运行测试和 linter 以确保一切正常：
   bash
   pytest
   ruff check .

如果失败，请修复代码和测试。严格要求 所有新代码必须符合 linter 规则并通过所有测试。

编码提示

• 在适当的地方使用类型注解
• 使用 pydantic 进行数据验证和序列化

📝 问题？

如果你对该项目有任何问题、意见或建议，请随时联系：

• 项目作者：titulus 通过 LinkedIn
• Sunrise Apps CEO：Vlad Karm 通过 LinkedIn

你也可以在仓库中打开一个 issue 来报告 bug 或提出功能请求。

📜 许可证

本项目采用 MIT 许可证。这意味着你可以自由使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。