atx-mcp 是一个用 Rust 编写的确定性（非生成式）资产变换 MCP 服务器，面向通用 AI 智能体。它把“调平地平线、裁剪成 16:9、稍微提亮”这类编辑意图当作声明式变换配方来执行，并把每个结果追踪为不可变修订。原始资产永远不会被修改。
用途 它用于让 AI 智能体以可复现、可审计的方式处理图像：导入素材 → 检测 → 应用变换（旋转、裁剪、缩放、编码）→ 导出。同一配方每次都能复现相同结果。
主要能力
- 多尺寸输出：一张原图可并行扇出为 OGP 1200×630、Instagram 1080 方形和 400px 缩略图；同配方同修订的幂等性保证重复运行不会重复创建输出，也可使用单词预设名。
- 安全发布：strip_metadata 可移除包括 GPS 在内的 EXIF，同时保留 ICC 配置文件；AI 还可通过 inspect_image 的 has_gps 提前预警。
- 颜色与风格调整：覆盖 curves / levels / hsl / white_balance、film_soft 预设，并可通过 import_asset 导入自有 .cube LUT 后用 lut 应用。
- 局部（蒙版）调整：generate_mask 可生成渐变、亮度范围或色相范围蒙版；接入调整后，render_preview 配合 overlay:"mask" 可在提交前显示蒙版影响的精确位置。
- 图层合成：layers 栈结合 16 种混合模式、不透明度和蒙版，可构建如柔焦这样可复现的合成效果。
- 水印、修图与透视：svg_overlay 烧入 logo，clone / heal 通过合成纹理与色调移除瑕疵或电线，perspective 校正汇聚的垂直线。
- 文档读取（OCR 预处理）：detect_document 找到页面或屏幕并返回可直接粘贴的透视四边形；ocr_document 预设（灰度、自动色阶、轻度锐化）和 trim 把像素预算集中在文字上；render_preview 配合 long_edge:1568 交给模型可读的图像。不捆绑 OCR 引擎——模型负责阅读，atx 只让像素可读且可复现。detect_text_blocks 返回阅读顺序的文本块和可直接粘贴的裁剪条带。threshold（Otsu / Sauvola）和 ocr_binarize 可供外部 OCR 引擎使用。
- 验证与问责：compare_revisions 可将修改前后并排，或返回带 mean_abs_diff 等统计的差异热图。每个修订都保留其血统，因此文章中任何图像的完整编辑历史都可追踪、可复现，在任何机器上字节一致。
- 拆分扫描：没有专门的 split 操作时，模型可针对同一源修订对每一部分各运行一次 apply_transform（裁剪左/右半，再用 trim 吸附到纸张边缘并保留一些装裱边距），export_asset 一次写出两份；render_preview 不带配方并 overlay:"grid" 可先读取坐标。
使用方式 atx-mcp 是单个自包含二进制文件，无运行时依赖，可通过以下方式安装：cargo binstall（预编译二进制）、cargo install（从源码构建，需要 C 编译器，libwebp 从 vendored 源码构建）、预编译二进制（安装脚本默认位置 ~/.local/bin 或 Windows 的 %LOCALAPPDATA%\Programs\atx-mcp，压缩包在解压前用 SHA256SUMS 校验）、容器镜像 ghcr.io/gridhra/atx-mcp（FROM scratch，仅含静态链接的二进制，linux/amd64 和 linux/arm64），或 npx（Node.js 18+，无需安装，通过 optionalDependencies 自动拉取平台预编译原生二进制）。也可直接加入 MCP 客户端配置。--workspace（环境变量 ATX_WORKSPACE）是作为资产库的目录，不存在时会自动创建。
容器使用有两个注意点：必须加 -i，因为服务器使用 MCP stdio 传输且需要 stdin 保持打开；路径是容器路径，绑定的目录在容器内显示为 /workspace，因此 import_asset 和 export_asset 接受 /workspace/photos/shot.jpg 这类路径，而非宿主路径。
支持的操作（29 个）：auto_orient / rotate / perspective / crop（crop、pad）/ trim / resize（cover、contain、fill）/ adjust / color_matrix / curves / levels / lut / white_balance / hsl / blur / median / unsharp_mask / convolve / threshold / 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、示例和注意事项。
.cube LUT 和 .svg 都是资产而非图像：先用 import_asset 导入（LUT 存为 mime_type: "application/x-cube" 的不可变修订，SVG 存为 "image/svg+xml"），再在配方中引用其 revision_id。strength（0..1，默认 1.0）与原始线性混合。由于修订不可变，把引用的 id 纳入 recipe_hash 可保持变换完全确定，但也意味着配方只有在持有该 LUT 的工作区内才能复现，跨机器移动风格时要把 .cube 一起移动。引用未知 id 会在任何像素操作前以结构化错误失败。
SVG 叠加中 x / y 是该管线阶段图像坐标中的叠加左上角（所以把叠加放在 resize/crop 之后），允许负值，溢出部分会被裁剪。省略 width 和 height 按 SVG 固有尺寸栅格化，只给一个则保持宽高比缩放，两个都给则拉伸到精确盒子；没有固有尺寸的 SVG 必须给两个，否则是结构化错误。合成使用与 layers 相同的 W3C 公式和相同的 16 个 blend_mode 值。atx 从不读取系统字体，因此默认跳过 <text>（render_text 默认为 false，图形渲染而字形不渲染并带警告）。render_text:true 时使用一个内置字体 Roboto Regular（嵌入二进制）加上 font_revision_ids 传入的字体（最多 4 个），输出在所有机器上完全相同。字体也是资产：import_asset 一个 .ttf / .otf 文件，summary 会报告 font-family 中可写的族名。日语等 CJK 文字需要导入字体，Roboto 没有 CJK 字形，所有已加载字体中缺失的字符渲染为方框并计入警告。inspect_image 会刻意拒绝字体修订，因为它是资产而非图像。
蒙版（局部调整）是灰度图像修订：其 BT.709 亮度即权重，白色表示“全强度应用此操作”，黑色表示“不动该像素”。14 个色调/滤镜操作（adjust、color_matrix、curves、levels、hsl、lut、white_balance、blur、median、unsharp_mask、convolve、grain、gradient_map、auto_levels）都可接受一个蒙版。generate_mask 针对参考图像确定性构建一个尺寸完全一致的蒙版，也可 import_asset 自己的灰度图像。把返回的 revision_id 附加到操作上；invert（默认 false）翻转权重为 1-w；feather_px（默认 0.0）用当前图像像素中的高斯 sigma 模糊蒙版边缘。render_preview 配合 overlay:"mask" 和 mask_revision_id 会在权重超过 0.5 处把预览染红，其他位置变暗，以便提交前检查覆盖范围。蒙版像 LUT 一样按 revision id 引用，因此同样注意：配方哈希包含该 id，配方只在持有该蒙版的工作区内可复现。
配方可以携带 layers 栈而非（或额外于）扁平 operations 列表。图层自下而上合成，每层的 ops 先针对其自身 source 运行，再混合到正在构建的合成上；source 要么是 "base"（传入 apply_transform / render_preview 的输入修订），要么是 {"revision_id": "rev_..."}。
适用场景 适合需要可复现、可追溯、非生成式图像处理的 AI 智能体工作流：文章配图制作、社交/CMS 多尺寸输出、安全发布前元数据清理、颜色与风格调整、局部蒙版调整、图层合成、水印与修图、扫描文档拆分以及 OCR 预处理等。
限制 atx 不做生成式编辑、RAW 开发、基于机器学习的自动裁剪和 OCR 本身，这些都在范围之外，详见 docs/DESIGN.md 的路线图。atx 从不读取系统字体，以保证跨机器的字节级可复现性。文中显示的安装命令、参数与操作目录以文档为准。
