Compositor

compositor-mcp

一个 MCP 服务，让 Claude 和其他 AI Agent 能够读取和编辑 Compositor 项目。Compositor 是适用于 Mac 的开源 Photoshop 替代软件。

它基于有文档说明的 .comp 包格式（一个 manifest.json 加上每个图层对应一个 PNG），因此无需修改 Compositor 本身。使用 Agent 编辑项目，然后在 Compositor 中打开。也可以反过来：在 Compositor 中保存，再让 Agent 检查、润饰或渲染。

Agent 可以做什么

工具	用途
inspect_project	查看画布尺寸、分辨率，以及每个图层的文件夹深度、不透明度、混合模式、变换、蒙版和剪贴信息
list_layers	以紧凑的从上到下顺序查看图层，类似“图层”面板
render_preview	返回扁平化的 PNG 预览图，让模型能够看到合成效果
export_flattened	导出全分辨率 PNG 或 JPEG
export_layer	将图层的源像素或蒙版复制到文件
create_project	新建文档，可选择添加纯色背景图层
add_image_layer	将 PNG、JPEG、HEIC、TIFF、WebP……作为图层导入，并支持适配、填充、拉伸放置，设置不透明度、混合模式和文件夹
add_folder	创建图层文件夹
set_layer	重命名、显示/隐藏图层，设置不透明度、混合模式、位置、尺寸、旋转、翻转、采样方式，以及开启/关闭蒙版
move_layer	调整图层顺序或将图层移至其他文件夹
remove_layer	删除图层或整个文件夹
replace_layer_image	替换图层像素（通过其他工具或生成的图像往返处理）
set_layer_mask	添加灰度蒙版、反转蒙版或清除蒙版
resize_canvas	更改文档尺寸并设置锚点，不进行重采样
open_in_compositor	在 Compositor 应用中打开项目

该服务还提供 compositor://format 资源，用于说明文件格式。

相关项目

marcushorndt/compositor-mcp 采用了不同的方式：它以无头模式驱动 Compositor 自身的文档模型和渲染器（Swift），因此预览效果与应用中完全一致。此软件包是一个纯 Node 服务，基于有文档说明的文件格式运行，无需构建应用，并且只要能运行 Node 就能运行。根据你的配置选择即可；两者都能打开相同的 .comp 文件。

安装

需要 Node.js 20 或更高版本。只有查看结果时才需要 Compositor 本身。

Claude Code

claude mcp add compositor -- npx -y compositor-mcp

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "compositor": {
      "command": "npx",
      "args": ["-y", "compositor-mcp"]
    }
  }
}

从源代码安装

git clone https://github.com/Josusanz/compositor-mcp
cd compositor-mcp
npm install
npm run build
claude mcp add compositor -- node /path/to/compositor-mcp/dist/src/index.js

会话示例

在 ~/Desktop/poster.comp 创建一个 1920×1080 的项目，背景为白色，添加 photo.jpg 并缩放至填满画布，将 logo.png 放在右下角，设置不透明度为 80 %，混合模式为正片叠底，然后给我看预览并在 Compositor 中打开。

Agent 会调用 create_project、两次调用 add_image_layer，然后调用 set_layer、render_preview 和 open_in_compositor。Compositor 会打开文档，其中的图层已准备好，可继续编辑。

与 Compositor 格式的对应关系

• 图层像素以 8-bit sRGB PNG 原样存储；放置、缩放、旋转和翻转信息保存在图层变换中，因此编辑不会破坏原始内容。
• 蒙版按 Compositor 要求，以不带 alpha 通道的 8-bit 灰度 PNG 写入。
• 写入前会按照与 ProjectStore.swift 相同的规则验证清单，使用已排序的键写入，并以原子方式替换。
• 此工具无法识别的字段（调整、效果、文本、形状、参考线以及任何较新的字段）会在往返处理时保留。
• 项目以格式版本 9 保存（Compositor 1.2.6 写入的版本）；声明了更新版本的项目会在往返处理时保留其版本号和未知字段。较旧版本的 Compositor 无法打开较新版本的文件；如果文件无法打开，请更新应用。

限制

• 预览渲染器支持渲染图层顺序、文件夹、可见性、不透明度、变换、栅格蒙版以及 sharp 支持的混合模式。尚不支持渲染剪贴蒙版、调整图层和图层效果；工具会报告跳过了哪些内容。Compositor 自带的导出功能才是参考标准。
• Compositor 不会监视文件变化。Agent 编辑已打开的项目后，请关闭并重新打开文档（或调用 open_in_compositor）。
• 无法与正在运行的应用建立实时连接：选择状态、撤销历史和视口仅在 Compositor 会话中保留，无法在此处访问。

开发

npm install
npm test        # builds and runs the node:test suite
npm run dev     # runs the server from TypeScript with tsx

许可证

MIT。Compositor 的版权归 Robbie Tilton 所有，同样采用 MIT 许可证。