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. 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.

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.

Install

No Rust toolchain required. Pick one of the following.

1. npx (easiest, recommended)

Node.js 18+ is all you need. The prebuilt native binary for your platform is pulled in automatically via 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

Or add it directly to your MCP client config:

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

2. Prebuilt binary

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

3. Build from source (any other platform)

All you need is a Rust toolchain and a C compiler (for building libwebp from its vendored source).

cargo build --release
# => target/release/atx-mcp
claude mcp add asset-transform -- "$PWD/target/release/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.

Tools (12)

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 }
  ]
}