atx-mcp

English | 日本語 | 简体中文

一个用 Rust 编写的、面向通用 AI 代理的确定性（非生成式）资源变换 MCP 服务器。

它以声明式变换配方（recipe）来执行编辑意图——"把地平线调平、裁剪成 16:9、稍微提亮一点"——并将每个结果记录为不可变修订版本。原始资源永远不会被修改。

倾斜校正 + 自动色阶 + 应用一种风格（完全确定性的配方）——左：输入 / 右：输出。

完整设计参见 docs/DESIGN.md。

使用场景

1. 文章配图

   "把这张照片拉直并裁剪为 16:9、1600px 的配图。WebP。" import_asset → detect_tilt（AI 在已经接近水平时会跳过校正）→ apply_transform（rotate → crop → resize → encode）→ export_asset。原始文件永远不会被触碰，同一个配方每次都产生相同结果。

2. 为社交媒体/CMS 生成多种尺寸

   "生成这张照片的 OGP、Instagram 方形图和缩略图版本。" 一个原始文件并行扩展为 OGP 1200×630、Instagram 1080 方形图和 400px 缩略图。同一个配方生成同一个修订版本的幂等性意味着重复运行绝不会重复产生输出；使用单个词的预设名称也同样有效。

3. 可安全发布

   "务必去除位置数据，但不要改变颜色。" strip_metadata（exif）会移除包括 GPS 在内的 EXIF，同时保留 ICC 配置文件。AI 还可以通过 inspect_image 中的 has_gps 提前发出警告。

4. 颜色与风格调整

   "只让天空更蓝，其他一切保持不变。" 涵盖 curves / levels / hsl / white_balance、film_soft 预设，以及通过 import_asset 导入你自己的 .cube LUT，再用 lut 应用。

5. 局部（蒙版）调整

   "只把天空调暗一点，地面保持原样。" generate_mask 生成蒙版（渐变、亮度范围或色相范围）；将蒙版接入调整后，使用带 overlay:"mask" 的 render_preview 可在提交前精确显示其作用范围。

6. 图层合成

   "把这张照片的副本模糊一下，以 50% 的滤色（screen）混合进去，营造柔和光晕。" layers 栈组合 16 种混合模式、不透明度和蒙版，从而构建可复现的合成效果，比如柔焦。

7. 水印、修图与透视

   "把我的 Logo 印在角落，移除电力线，并校正汇聚的垂直线。" svg_overlay 烫印 Logo，clone/heal 通过合成纹理和色调来移除瑕疵或线条，perspective 校正汇聚垂直线。

8. 验证与可追溯

   "并排展示这张图像编辑前后的效果。" compare_revisions 将前后版本并排展示，或返回带 mean_abs_diff 等统计数据的差异热力图。每个修订版本都保留其谱系，因此文章中所用任何图像背后的完整编辑历史都可以追溯和复现——在任何机器上逐字节一致。

atx 不做什么——生成式编辑、RAW 处理、基于 ML 的自动裁剪——均不在范围内；路线图见 docs/DESIGN.md。

Related MCP server: img-convert MCP Server

安装

无需 Rust 工具链。选择以下方式之一。

1. npx（最简单，推荐）

只需要 Node.js 18+。预构建的适用于你平台的原生二进制会通过 optionalDependencies 自动引入。

# --scope user makes it available in every project (omit for current-project only)
claude mcp add --scope user asset-transform -- npx -y atx-mcp --workspace /path/to/asset-workspace

或者直接将其添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "asset-transform": {
      "command": "npx",
      "args": ["-y", "atx-mcp", "--workspace", "/path/to/asset-workspace"]
    }
  }
}

2. 预构建二进制

安装脚本（默认安装位置为 ~/.local/bin，Windows 上为 %LOCALAPPDATA%\Programs\atx-mcp；归档在解压前会对照 SHA256SUMS 进行校验）：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/gridhra/atx-mcp/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/gridhra/atx-mcp/main/scripts/install.ps1 | iex

如需手动下载，请从 Releases 获取 atx-mcp-<version>-<target>.tar.gz（Windows 为 .zip）。 支持的目标平台：

claude mcp add asset-transform -- ~/.local/bin/atx-mcp --workspace /path/to/asset-workspace

3. 从源码构建（其他任何平台）

你只需要 Rust 工具链和 C 编译器（用于从内置源码构建 libwebp）。

cargo build --release
# => target/release/atx-mcp
claude mcp add asset-transform -- "$PWD/target/release/atx-mcp" --workspace /path/to/asset-workspace

--workspace（环境变量：ATX_WORKSPACE）是用作资源存储的目录。如果该目录不存在，会自动创建。

工具（11）

配方示例

{
  "operations": [
    { "op": "rotate", "angle_degrees": -1.8 },
    { "op": "crop", "aspect_ratio": "16:9" },
    { "op": "resize", "width": 1600 },
    { "op": "encode", "format": "webp", "quality": 82 }
  ]
}

支持的操作（27）：auto_orient / rotate / perspective / crop（crop、pad） / resize（cover、contain、fill） / adjust / color_matrix / curves / levels / lut / white_balance / hsl / blur / median / unsharp_mask / convolve / clone / heal / svg_overlay / flip / vignette / grain / gradient_map / pixelate / auto_levels / encode（jpeg、png、webp、avif） / strip_metadata。 操作词汇表有意不放进工具 schema 中：调用 list_operations 获取最新目录，调用 explain_operation 获取某个操作的完整 schema、示例和注意事项。

LUT（.cube）

.cube 3D/1D LUT 是一种资源，不是图像：先导入它，然后让配方指向它生成的修订版本。

1. 用 import_asset 导入 .cube 文件。它会作为不可变修订版本存储，mime_type: "application/x-cube"（inspect_image 会刻意拒绝它——它不是图像）。

2. 在配方中引用返回的 revision_id：

{ "op": "lut", "lut_revision_id": "rev_...", "strength": 0.8 }

strength（0..1，默认 1.0）与原始图像线性混合。由于修订版本不可变，将引用的 id 包含在 recipe_hash 中可让变换完全保持确定性——但这也意味着该配方只能在持有该 LUT 的工作区内复现，因此当你在不同机器之间迁移某种风格时，请将 .cube 与配方一起移动。引用未知 id 会在任何像素处理开始之前以结构化错误失败。

SVG 叠加（Logo 与水印）

.svg 是矢量资源，类似 .cube LUT：先导入它，然后在配方中将它盖印到光栅图像上。

1. 用 import_asset 导入 .svg 文件。它会作为不可变修订版本存储，mime_type: "image/svg+xml"，摘要会报告 SVG 的固有尺寸（0x0 表示没有——根 <svg> 上没有 viewBox，也没有绝对的 width/height）。inspect_image 会刻意拒绝它：它是矢量资源，不是光栅图像。

2. 在配方中引用返回的 revision_id：

{ "op": "svg_overlay", "svg_revision_id": "rev_...",
  "x": 24, "y": 24, "width": 320, "opacity": 0.25, "blend_mode": "normal" }

x/y 是叠加层在图像坐标系中的左上角（在该流水线阶段——所以请把叠加层放在你的 resize/crop 之后）；允许负值，溢出部分会被裁剪。省略 width 和 height 时按 SVG 的固有尺寸进行栅格化；只给其中一个则按比例缩放并保持宽高比；两个都给则拉伸到精确的盒子——没有固有尺寸的 SVG 除非你两个都给，否则属于结构化错误。合成使用与 layers 相同的 W3C 公式和相同的 16 个 blend_mode 值。

文本永远不会被渲染。 atx 不加载任何系统字体，因为不同机器上安装的字体各不相同，会破坏逐字节的可复现性。包含 <text> 的 SVG 会渲染其形状但不会渲染其字形，并报告一条警告——在导入前，请在矢量编辑器中把文本转换为路径（轮廓），这样结果在每台机器上都是完全一致的。

蒙版（局部调整）

蒙版是一种灰度图像修订：其 BT.709 亮度即为权重，因此白色表示"以全强度应用此操作"，黑色表示"保持该像素不变"。14 种色调/滤镜操作（adjust、color_matrix、curves、levels、hsl、lut、white_balance、blur、median、unsharp_mask、convolve、grain、gradient_map、auto_levels）中的任意一种都可以接受蒙版。

1. generate_mask 针对参考图像确定性地构建蒙版，且尺寸与该图像完全一致：

你也可以改用 import_asset 导入自己的灰度图像。

2. 将返回的 revision_id 附加到某个操作上：

{ "op": "curves", "master": [[0,0],[128,168],[255,255]],
  "mask": { "revision_id": "rev_...", "invert": false, "feather_px": 8.0 } }

invert（默认 false）将权重翻转为 1-w；feather_px（默认 0.0）按当前图像的像素以该高斯 sigma 值模糊蒙版边缘。

3. 使用 overlay:"mask" 和 mask_revision_id 调用 render_preview，会在权重超过 0.5 的地方将预览染成红色，并在其他地方调暗，以便在提交前检查覆盖范围。

蒙版与 LUT 一样通过修订 id 引用，因此同样的注意事项也适用：配方哈希包含该 id，且配方只能在持有该蒙版的工作区内复现。

图层

配方可以携带 layers 堆栈，以替代（或补充）扁平的 operations 列表。图层自下而上合成，每个图层的 ops 先针对其自身源运行，然后再混合到运行中的合成结果上：

{
  "layers": [
    { "source": "base", "ops": [] },
    {
      "source": { "revision_id": "rev_..." },
      "ops": [{ "op": "blur", "sigma": 8 }],
      "blend_mode": "multiply",
      "opacity": 0.6
    }
  ],
  "operations": [
    { "op": "resize", "width": 1600 },
    { "op": "encode", "format": "webp", "quality": 82 }
  ]
}

• source 要么是 "base"（传递给 apply_transform / render_preview 的输入修订），要么是 {"revision_id": "rev_..."}（工作区中已有的任何其他修订）。每个图层的源必须与基础图像的尺寸完全一致，否则配方会在任何像素工作开始之前以结构化错误失败。

• ops 是一个普通的操作列表，仅应用于该图层自身的源。

• mask、blend_mode（默认 "normal"）和 opacity（默认 1.0）控制该图层如何合成到其下方的图层上。

• 混合模式是 16 种 W3C 模式之一：12 种可分离模式 normal、multiply、screen、overlay、darken、lighten、color_dodge、color_burn、hard_light、soft_light、difference、exclusion，外加 4 种不可分离模式 hue、saturation、color、luminosity。

• 当存在 layers 时，顶层 operations 成为收尾通道，对合成结果应用一次——resize 和最终的 encode 应放在这里（encode 仍然必须是最后一个，且最多出现一次）。

• 调用 explain_operation {"operation":"layers"} 获取完整参考。

预设

apply_transform 和 render_preview 接受 recipe（原始 DSL）或 preset（来自 presets/ 的内置命名配方）——两者恰好取其一：

预设纯粹是语法糖：它会解析为其配方并流经正常流水线，recipe_hash（幂等键）基于解析后的配方计算——因此预设调用与等效的原始配方会落在同一个修订上。

保证

• 确定性：相同的输入 + 相同的配方始终产生逐字节相同的输出（通过黄金测试进行回归检查）

• 幂等性：配方会被规范化（键排序，f64 值量化到 1e-6 网格）并使用 sha256 哈希。如果 (输入修订, 配方哈希) 与现有配对匹配，则返回现有修订而不是新修订

• 原始文件受到保护：objects/ 是一个仅追加、内容寻址的存储——没有删除或覆盖 API

开发

cargo test --workspace     # unit + integration + property (proptest) tests
cargo clippy --workspace --all-targets -- -D warnings

Crate 布局：atx-core（配方/变换引擎）/ atx-geometry（倾斜检测）/ atx-store（不可变资产存储）/ atx-mcp（rmcp stdio 服务器）。

发布流程请参阅 RELEASING.md。

名称

"atx" 代表 Asset Transform（资产变换）；末尾的 x 沿用了 "transform" 的常见简写（如 xform / tx）。选择它是因为它是一个简短、易于输入的可执行文件名和 crate 前缀（atx-core 等），并且它与 PC ATX 规格或 Markdown ATX 风格标题无关。

许可证

MIT。请参阅 LICENSE。

如果 atx-mcp 为你节省了时间，可以请我喝杯咖啡 ☕