atx-mcp is a deterministic (non-generative) asset transformation MCP server written in Rust, aimed at general-purpose AI agents. It executes editing intents such as "level the horizon, crop to 16:9, brighten slightly" as declarative transformation recipes, and tracks each result as an immutable revision. Original assets are never modified.
Purpose It is used to let AI agents process images in a reproducible, auditable way: import material → detect → apply transformations (rotate, crop, scale, encode) → export. The same recipe reproduces the same result every time.
Main capabilities
- Multi-size output: one original image can be fanned out in parallel to OGP 1200×630, Instagram 1080 square, and a 400px thumbnail; idempotency for the same recipe and same revision guarantees that repeated runs do not create duplicate outputs, and single-word preset names can also be used.
- Safe publishing: strip_metadata can remove EXIF including GPS while preserving the ICC profile; AI can also give an early warning via has_gps in inspect_image.
- Color and style adjustments: covers curves / levels / hsl / white_balance, the film_soft preset, and you can import your own .cube LUT via import_asset and then apply it with lut.
- Local (masked) adjustments: generate_mask can create gradient, luminance range, or hue range masks; once connected to adjustments, render_preview with overlay:"mask" can show the exact locations affected by the mask before committing.
- Layer compositing: the layers stack combines 16 blend modes, opacity, and masks to build reproducible composite effects such as soft focus.
- Watermarks, retouching, and perspective: svg_overlay burns in a logo, clone / heal removes blemishes or wires by compositing texture and tone, and perspective corrects converging vertical lines.
- Document reading (OCR preprocessing): detect_document finds pages or screens and returns a perspective quadrilateral that can be pasted directly; the ocr_document preset (grayscale, auto levels, light sharpening) and trim focus the pixel budget on text; render_preview with long_edge:1568 produces an image readable by the model. OCR is not bundledQing——the model handles reading, while atx only makes pixels readable and reproducible. detect_text_blocks returns text blocks in reading order and crop strips that can be pasted directly. threshold (Otsu / Sauvola) and ocr_binarize can be used by external OCR engines.
- Verification and accountability: compare_revisions can place before and after side by side, or return a difference heatmap with statistics such as mean_abs_diff. Every revision retains its lineage, so the complete edit history of any image in an article is traceable, reproducible, and byte-identical on any machine.
- Split scanning: when there is no dedicated split operation, the model can run apply_transform once for each part against the same source revision (crop the left/right half, then use trim to snap to the paper edge while preserving some mounting margin), and export_asset writes both out at once; render_preview without a recipe and with overlay:"grid" can read the coordinates first.
How to use atx-mcp is a single self-contained binary with no runtime dependencies, and can be installed in the following ways: cargo binstall (precompiled binary), cargo install (build from source, requires a C compiler, libwebp is built from vendored source), precompiled binary (the install script defaults to ~/.local/bin or %LOCALAPPDATA%\Programs\atx-mcp on Windows, and the archive is verified with SHA256SUMS before extraction), container image ghcr.io/gridhra/atx-mcp (FROM scratch, containing only the statically linked binary, linux/amd64 and linux/arm64), or npx (Node.js 18+, no installation required, automatically pulls the platform precompiled native binary via optionalDependencies). It can also be added directly to the MCP client configuration. --workspace (environment variable ATX_WORKSPACE) is the directory used as the asset library, and it is created automatically if it does not exist.
There are two caveats for container use: -i must be added, because the server uses MCP stdio transport and needs stdin to remain open; paths are container paths, and the bound directory appears inside the container as /workspace, so import_asset and export_asset accept paths such as /workspace/photos/shot.jpg, not host paths.
Supported operations (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. The operation vocabulary is deliberately not placed in the tool schema: call list_operations to get the latest catalog, and call explain_operation to view the full schema, examples, and caveats for an operation.
.cube LUTs and .svg are both assets rather than images: first import them with import_asset (LUTs are stored as immutable revisions with mime_type: "application/x-cube", SVGs as "image/svg+xml"), then reference their revision_id in the recipe. strength (0..1, default 1.0) blends with the original linearly. Because revisions are immutable, including the referenced id in recipe_hash keeps the transformation fully deterministic, but it also means the recipe can only be reproduced in a workspace that holds that LUT, so when moving a style across machines, move the .cube along with it. Referencing an unknown id fails with a structured error before any pixel operation.
In SVG overlay, x / y are the top-left corner of the overlay in the image coordinates of that pipeline stage (so place the overlay after resize/crop), negative values are allowed, and overflow is clipped. Omitting width and height is rasterized according to the SVG intrinsic size; if only one is given, it is scaled while preserving the aspect ratio; if both are given, it is stretched to the exact box; an SVG without an intrinsic size must be given both, otherwise it is a structured error. Compositing uses the same W3C formula as layers and the same 16 blend_mode values. atx never reads system fonts, so by default it skips <text> (render_text defaults to false; graphics are rendered but glyphs are not, with a warning). When render_text:true, it uses one built-in font, Roboto Regular (embedded binary), plus the fonts passed in via font_revision_ids (at most 4), and the output is exactly the same on all machines. Fonts are also assets: import_asset a .ttf / .otf file, and summary reports the writable family name in font-family. CJK text such as Japanese requires importing a font; Roboto has no CJK glyphs, and characters missing from all loaded fonts are rendered as boxes and counted in warnings. inspect_image deliberately rejects font revisions because it is an asset rather than an image.
Masks (local adjustments) are grayscale image revisions: their BT.709 luminance is the weight, white means "apply this operation at full strength", black means "leave that pixel untouched". The 14 tone/filter operations (adjust, color_matrix, curves, levels, hsl, lut, white_balance, blur, median, unsharp_mask, convolve, grain, gradient_map, auto_levels) all accept a mask. generate_mask deterministically builds a mask of exactly the same size for a reference image, and you can also import_asset your own grayscale image. Attach the returned revision_id to the operation; invert (default false) flips the weight to 1-w; feather_px (default 0.0) blurs the mask edges with a Gaussian sigma in current image pixels. render_preview with overlay:"mask" and mask_revision_id tints the preview red where the weight exceeds 0.5 and darkens it elsewhere, so you can check coverage before committing. Masks, like LUTs, are referenced by revision id, so likewise note: the recipe hash includes that id, and the recipe is only reproducible within the workspace that holds that mask.
A recipe can carry a layers stack instead of (or in addition to) a flat operations list. Layers are composited bottom-up; each layer's ops first run against its own source, then blend into the composite being built; source is either "base" (the input revision passed to apply_transform / render_preview) or {"revision_id": "rev_..."}.
Use cases Suitable for AI agent workflows that need reproducible, traceable, non-generative image processing: article illustration production, multi-size social/CMS output, metadata cleanup before safe publishing, color and style adjustments, local mask adjustments, layer compositing, watermarks and retouching, scanned document splitting, and OCR preprocessing, etc.
Limitations atx does not do generative editing, RAW development, machine-learning-based automatic cropping, or OCR itself; these are out of scope, see the roadmap in docs/DESIGN.md. atx never reads system fonts, to guarantee byte-level reproducibility across machines. The installation commands, parameters, and working directories shown in the text are subject to the documentation.
