atx-mcp

English | 日本語 | 简体中文

A deterministic (non-generative) asset transformation MCP server for general-purpose AI agents, written in Rust.

It executes editing intent — "level the horizon, crop to 16:9, brighten it up a touch" — as a declarative transform recipe, and tracks every result as an immutable revision. The original asset is never modified.

Tilt correction + auto levels + a look applied (a fully deterministic recipe) — left: input / right: output.

See docs/DESIGN.md for the full design.

Use cases

1. Eye-catch image for an article

   "Straighten this photo and crop it to a 16:9, 1600px eye-catch. WebP." import_asset → detect_tilt (the AI skips correction when it's already near-level) → apply_transform (rotate → crop → resize → encode) → export_asset. The original is never touched, and the same recipe reproduces the same result every time.

2. Multiple sizes for social/CMS

   "Generate the OGP, Instagram square, and thumbnail versions of this photo." One original fans out into OGP 1200×630, Instagram 1080 square, and a 400px thumbnail in parallel. The same-recipe-same-revision idempotency means re-running never double-creates output; a one-word preset name works too.

3. Safe to publish

   "Strip the location data for sure, but don't touch the colors." strip_metadata (exif) removes EXIF including GPS while keeping the ICC profile intact. The AI can also warn ahead of time by checking has_gps from inspect_image.

4. Color and look adjustments

   "Make just the sky bluer, leave everything else alone." Covers curves / levels / hsl / white_balance, the film_soft preset, and importing your own .cube LUT with import_asset then applying it with lut.

5. Local (masked) adjustments

   "Darken just the sky a bit, keep the ground as is." generate_mask builds a mask (gradient, luminosity range, or hue range); after wiring it into the adjustment, render_preview with overlay:"mask" shows exactly where it will bite before you commit.

6. Layer compositing

   "Blur a copy of this photo and blend it in at 50% screen for a soft glow." The layers stack combines 16 blend modes, opacity, and masks to build reproducible composites like soft focus.

7. Watermarks, retouching, and perspective

   "Stamp my logo in the corner, remove the power lines, and fix the converging verticals." svg_overlay burns in a logo, clone/heal remove blemishes or wires by compositing both texture and tone, and perspective corrects converging verticals.

8. Reading documents (OCR pre-processing)

   "Read this receipt photo for me." / "What does this slide say?" detect_document finds the page or screen and returns a perspective quad ready to paste, the ocr_document preset (grayscale, auto levels, light sharpen) and trim concentrate the pixel budget on the text, and render_preview with long_edge:1568 hands the model an image it can actually read. No OCR engine is bundled: the model does the reading, atx only makes the pixels legible and reproducible. detect_text_blocks answers the question that decides the rest — "will this text survive the downscale, and where do I cut?" — by returning the text blocks in reading order plus ready-to-paste crop bands. threshold (Otsu / Sauvola) and ocr_binarize exist for external OCR engines.

9. Verification and accountability

   "Show me this image before and after the edits, side by side." compare_revisions places before/after side by side, or returns a difference heatmap with stats like mean_abs_diff. Every revision keeps its lineage, so the full edit history behind any image used in an article can be traced and reproduced — byte-identical on any machine.

10. Splitting one scan into separate images

"Two mounted sheets were scanned on one page. Save them as two files, keeping a little of the mount around each." There is no split operation: the model runs one apply_transform per piece against the same source revision (crop to the left/right half, then trim to snap to the paper's edges with padding to keep some mount), and export_asset writes both at once. render_preview with no recipe and overlay:"grid" is how it reads the coordinates first.

What atx doesn't do — generative editing, RAW development, ML-based auto-cropping, OCR itself — is out of scope; see docs/DESIGN.md for the roadmap.

Related MCP server: roundcut-mcp

Install

atx-mcp is a single self-contained binary with no runtime dependencies. Pick one of the following.

1. cargo binstall (prebuilt binary, no compilation)

cargo binstall atx-mcp
claude mcp add --scope user asset-transform -- atx-mcp --workspace /path/to/asset-workspace

cargo-binstall downloads the release archive built by this repository's CI instead of compiling, so this is the fastest route for anyone who already has a Rust toolchain. (--scope user makes the server available in every project; omit it for the current project only.)

2. cargo install (builds from source)

cargo install atx-mcp

Works on any platform a Rust toolchain supports, including ones without a prebuilt binary. Needs a C compiler as well (libwebp is built from its vendored source).

3. Prebuilt binary (no Rust toolchain)

Installer scripts (default install location is ~/.local/bin, or %LOCALAPPDATA%\Programs\atx-mcp on Windows; the archive is verified against SHA256SUMS before extraction):

# 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

To download manually, grab atx-mcp-<version>-<target>.tar.gz (.zip on Windows) from Releases. Supported targets:

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

4. Docker

ghcr.io/gridhra/atx-mcp is a FROM scratch image holding the statically linked binary and nothing else (linux/amd64 and linux/arm64).

claude mcp add asset-transform -- \
  docker run -i --rm -v "$PWD:/workspace" ghcr.io/gridhra/atx-mcp:0.6.7

Two things to keep in mind. -i is required: the server speaks the MCP stdio transport and needs stdin to stay open. And paths are container paths: the directory you bind-mount appears as /workspace inside the container, so import_asset and export_asset take paths like /workspace/photos/shot.jpg, not host paths.

5. npx (Node.js 18+, nothing to install)

The prebuilt native binary for your platform is pulled in automatically via optionalDependencies.

claude mcp add --scope user asset-transform -- npx -y atx-mcp --workspace /path/to/asset-workspace

Or add it directly to your MCP client config:

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

--workspace (env: ATX_WORKSPACE) is the directory used as the asset store. It is created automatically if it doesn't exist.

--max-concurrent-tools (env: ATX_MAX_CONCURRENT_TOOLS) caps how many pixel-processing tool calls (import / inspect / detect_* / apply / preview / compare / mask) run at the same time; the default is the CPU count. Lower it on memory-constrained hosts. Tool work runs on dedicated threads, so the stdio transport (ping, cancellation, the vocabulary tools) stays responsive while images are being processed.

Tools (13)

Recipe example

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

Supported ops (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 kept out of the tool schemas: call list_operations for the up-to-date catalog and explain_operation for one operation's full schema, examples and gotchas.

LUT (.cube)

A .cube 3D/1D LUT is an asset, not an image: import it first, then point a recipe at the revision it produced.

1. import_asset the .cube file. It is stored as an immutable revision with mime_type: "application/x-cube" (inspect_image refuses it on purpose — it is not an image).

2. Reference the returned revision_id from a recipe:

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

strength (0..1, default 1.0) blends linearly with the original. Because revisions are immutable, including the referenced id in the recipe_hash keeps the transform fully deterministic — but it also means the recipe is only reproducible inside a workspace that holds that LUT, so move the .cube alongside the recipe when you move a look between machines. Referencing an unknown id fails with a structured error before any pixel work happens.

SVG overlays (logos and watermarks)

An .svg is a vector asset, like a .cube LUT: import it first, then stamp it onto a raster image from a recipe.

1. import_asset the .svg file. It is stored as an immutable revision with mime_type: "image/svg+xml", and the summary reports the SVG's intrinsic size (0x0 means it has none — no viewBox and no absolute width/height on the root <svg>). inspect_image refuses it on purpose: it is a vector asset, not a raster image.

2. Reference the returned revision_id from a recipe:

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

x/y are the overlay's top-left corner in the coordinates of the image at that point in the pipeline (so put the overlay after your resize/crop); negative values are allowed and the overflow is clipped. Omit width and height to rasterize at the SVG's intrinsic size, give one to scale while preserving the aspect ratio, or give both to stretch to an exact box — an SVG with no intrinsic size is a structured error unless you give both. Compositing uses the same W3C formula and the same 16 blend_mode values as layers.

Text in an SVG

atx never reads system fonts: the installed fonts differ from machine to machine and would break byte-for-byte reproducibility. <text> is therefore skipped unless you ask for it:

{ "op": "svg_overlay", "svg_revision_id": "rev_...", "x": 120, "y": 80,
  "width": 48, "render_text": true, "font_revision_ids": ["rev_..."] }

• render_text defaults to false, which keeps the old behaviour exactly (the shapes render, the glyphs do not, and the result carries a warning). Converting text to paths in your vector editor still works and needs no font at all.

• render_text:true draws the text with one bundled font, Roboto Regular (embedded in the binary), plus any fonts you pass in font_revision_ids (up to 4). Nothing else is ever loaded, so the output is identical on every machine.

• A font is an asset like a LUT or an SVG: import_asset a .ttf / .otf file, and the summary reports the family names to write in font-family. Japanese and other CJK text needs an imported font — Roboto has no CJK glyphs, and characters missing from every loaded font render as boxes and are counted in a warning. inspect_image refuses a font revision on purpose: it is an asset, not an image.

Masks (local adjustments)

A mask is a grayscale image revision: its BT.709 luma is the weight, so white means "apply this operation at full strength" and black means "leave the pixel alone". Any of the 14 tone/filter ops (adjust, color_matrix, curves, levels, hsl, lut, white_balance, blur, median, unsharp_mask, convolve, grain, gradient_map, auto_levels) accepts one.

1. generate_mask builds one deterministically against a reference image, with exactly that image's dimensions:

You can also import_asset your own grayscale image instead.

2. Attach the returned revision_id to an operation:

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

invert (default false) flips the weight to 1-w; feather_px (default 0.0) blurs the mask edge by that gaussian sigma in pixels of the current image.

3. render_preview with overlay:"mask" and mask_revision_id tints the preview red where the weight exceeds 0.5 and dims it elsewhere, so the coverage can be checked before committing.

Masks are referenced by revision id exactly like LUTs, so the same caveat applies: the recipe hash includes the id, and the recipe only reproduces inside a workspace that holds that mask.

Layers

A recipe may carry a layers stack instead of (or in addition to) a flat operations list. Layers composite bottom-to-top, each layer's ops run against its own source before it is blended onto the running composite:

{
  "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 is either "base" (the input revision passed to apply_transform / render_preview) or {"revision_id": "rev_..."} (any other revision already in the workspace). Every layer's source must match the base image's dimensions exactly, or the recipe fails with a structured error before any pixel work happens.

• ops is a normal operations list, applied to that layer's source alone.

• mask, blend_mode (default "normal") and opacity (default 1.0) control how the layer composites onto the layers below it.

• Blend mode is one of 16 W3C modes: the 12 separable modes normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, plus the 4 non-separable modes hue, saturation, color, luminosity.

• When layers is present, the top-level operations becomes the finishing pass, applied once to the composited result — this is where resize and the final encode belong (encode must still be last and appear at most once).

• Call explain_operation {"operation":"layers"} for the full reference.

Presets

A preset can also be inlined inside a recipe as a single operation — {"op": "preset", "name": "ocr_document"} — so a named look can be combined with your own ops. The macro expands in place before anything runs, so the recipe hashes exactly as if you had written the preset's operations out by hand, and a preset that carries layers cannot be inlined (that is a structured error). Call explain_operation {"operation":"preset"} for the rules.

apply_transform and render_preview take either recipe (the raw DSL) or preset (a built-in named recipe from crates/atx-mcp/presets/) — exactly one of the two:

A preset is pure sugar: it resolves to its recipe and flows through the normal pipeline, and the recipe_hash (the idempotency key) is computed on the resolved recipe — so a preset call and the equivalent raw recipe land on the same revision.

Guarantees

• Deterministic: the same input + the same recipe always produces byte-identical output (regression-checked with golden tests)

• Idempotent: recipes are normalized (keys sorted, f64 values quantized to a 1e-6 grid) and hashed with sha256. If (input revision, recipe hash) matches an existing pair, the existing revision is returned instead of a new one

• Originals are protected: objects/ is an append-only, content-addressed store — there is no delete or overwrite API

Development

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

Crate layout: atx-core (recipe/transform engine) / atx-geometry (tilt detection) / atx-store (immutable asset store) / atx-mcp (rmcp stdio server).

The three libraries are published on crates.io under longer names, because atx-core there is an unrelated project:

So to use the transform engine as a library, depend on asset-transform-core = "0.6.7" and write use atx_core::….

Name

"atx" stands for Asset Transform; the trailing x follows the familiar shorthand for "transform" (as in xform / tx). It was chosen as a short, easy-to-type binary name and directory prefix (crates/atx-core, etc.), and it has no relation to the PC ATX form factor or Markdown ATX-style headings. The crates.io packages spell the name out in full (asset-transform-core, and so on).

License

MIT. See LICENSE.

Non-crate material shipped inside the binary (the bundled Roboto Regular font) is listed with its source and license in THIRD_PARTY_NOTICES.md.

If atx-mcp saves you time, you can buy me a coffee ☕