imageport

imageport

imageport 使用 ImageMagick 在本地处理图像。它会读取图像文件的元数据——格式、尺寸、色彩空间和文件大小——在保持宽高比的同时调整图像大小，在常见的 Web 和印刷格式（png、jpg、webp、gif、avif、bmp、tiff）之间转换，从图像中裁剪出矩形区域，并按角度（单位为度）旋转。所有操作都只在本地处理文件：此软件包不生成图像、不使用托管 AI，也不会发起任何网络请求。

这五种工具都会构建 ImageMagick 参数数组，并通过一个可注入的执行器运行。默认执行器使用 node:child_process 的 execFile 启动 convert 和 identify——传入参数数组，而非 shell 字符串——因此宿主机必须安装 ImageMagick。如果找不到这些二进制文件，生成的错误（例如 ENOENT）会如实作为工具错误返回，不会伪造结果。单元测试通过一个记录参数数组的模拟执行器测试同一套核心逻辑，因此完全不需要 ImageMagick。

有一点值得提前了解：ImageMagick 会根据输出文件的扩展名判断输出格式，因此只要请求的输出路径扩展名与目标格式不同，convert_image 就会将其替换为目标格式（将 photo.png 转换为 webp 时会写入 photo.webp），并在结果中返回实际使用的路径。

安装

npx -y @reneturcios/imageport mcp

也可以运行容器镜像（注意：容器未捆绑 ImageMagick，因此只能通过 MCP 初始化 / CLI 使用冒烟测试；要实际处理图像，请在安装了 ImageMagick 的宿主机上运行）：

docker run -i ghcr.io/cloudcorprecords/imageport

CLI

imageport metadata <input>
imageport resize <input> <output> [--width n] [--height n]
imageport convert <input> <output> <format>
imageport crop <input> <output> <width> <height> <x> <y>
imageport rotate <input> <output> <angle>
imageport mcp
imageport --version

示例：

imageport metadata photo.png
imageport resize photo.png photo-small.png --width 800
imageport convert photo.png photo-out.png webp   # writes photo-out.webp
imageport crop photo.png tile.png 200 200 40 60
imageport rotate photo.png photo-upright.png 90

每条命令都会将结果以 JSON 格式输出。退出代码：成功时为 0，ImageMagick 执行失败时为 1（包括未安装时），用法错误时为 2。

MCP 服务

一个可执行文件支持两种用途。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/imageport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "imageport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/imageport", "mcp"]
    }
  }
}

工具

工具	输入	功能
get_image_metadata	input（必填）	通过 identify 读取格式、宽度、高度、色彩空间和文件大小。
resize_image	input、output（必填）；width、height（至少指定一项）	通过 convert -resize 在保持宽高比的同时调整图像大小。
convert_image	input、output、format（必填）	转换为 png、jpg、webp、gif、avif、bmp 或 tiff；扩展名不同时，会将输出文件扩展名替换为目标格式。
crop_image	input、output、width、height、x、y（必填）	通过 convert -crop ... +repage 裁剪位于偏移量 x、y 处的 width x height 区域。
rotate_image	input、output、angle（必填）	通过 convert -rotate 按 angle 度旋转图像。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake executor, no ImageMagick needed
npm run dev     # run the CLI from source via tsx

许可证

MIT——详见 LICENSE。