atx-mcp

# atx-mcp

**English** | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)

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.

![Before/after: a tilted synthetic cityscape straightened, levels auto-corrected, and a subtle look applied](docs/assets/before-after.jpg)
Tilt correction + auto levels + a look applied (a fully deterministic recipe) — left: input / right: output.

See [docs/DESIGN.md](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. **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 — is out of scope; see [docs/DESIGN.md](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`.

```sh
# --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:

```json
{
  "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):

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

```powershell
# 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](https://github.com/gridhra/atx-mcp/releases).
Supported targets:

| Platform | Target triple |
|---|---|
| macOS (Apple Silicon) | `aarch64-apple-darwin` |
| macOS (Intel) | `x86_64-apple-darwin` |
| Linux x86_64 | `x86_64-unknown-linux-musl` (statically linked, no glibc required) |
| Linux arm64 | `aarch64-unknown-linux-musl` (statically linked, no glibc required) |
| Windows x86_64 | `x86_64-pc-windows-msvc` |

```sh
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).

```sh
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 (11)

| Tool | Role |
|---|---|
| `list_operations` | Compact catalog of the recipe vocabulary: every operation with a one-line description and terse parameter hints, plus the built-in preset names. Optional `category:"geometry"\|"color"\|"filter"\|"output"` narrows it (read-only) |
| `explain_operation` | Full reference for one operation: parameter table (type, range, required/default, semantics), ready-to-paste JSON examples and gotchas. A built-in preset name works too and returns its full operation list. An unknown name returns the valid operations and presets, grouped (read-only) |
| `import_asset` | Import a local image into the workspace (sha256-idempotent). Takes `path` for one file or `paths` for a batch of up to 64 (a failing file does not abort the batch). Warns via `already_derived_from` when the bytes are already the output of a recipe in this workspace |
| `inspect_image` | Inspect dimensions, EXIF, ICC profile, presence of GPS data, etc. (read-only) |
| `detect_tilt` | Estimate tilt angle via Canny+Hough (coarse) plus a projection profile (sub-0.1° refinement). Also returns horizontal/vertical family estimates; the full score curve is opt-in via `include_score_curve:true`. Returns "do not correct" when confidence is low (read-only) |
| `generate_mask` | Generate a deterministic grayscale mask (`linear_gradient` / `radial_gradient` / `luminosity_range` / `color_range`) as a PNG revision with the same dimensions as the reference image, to be referenced from an operation's `mask` field (idempotent) |
| `render_preview` | Apply a recipe (or a `preset`) at low resolution (long edge ≤768) and return it as an inline image. `overlay:"grid"\|"thirds"\|"horizon"` overlays composition guide lines, and `overlay:"mask"` (with `mask_revision_id`) tints the coverage of a mask (drawn on the preview only; it has no effect on the actual transform) |
| `apply_transform` | Apply a recipe (or a `preset`) at full resolution and produce a new revision (the same recipe always yields the same revision). Takes `revision_id` for one image or `revision_ids` to run the same recipe over a batch of up to 64 |
| `compare_revisions` | Downscale two revisions to long edge ≤640 and return them composited into a single inline image, arranged via `layout:"side_by_side"\|"stacked"` (for A/B and before/after visual comparison), or `layout:"diff"` for a single pixel-difference heatmap plus `mean_abs_diff`/`max_abs_diff`/`changed_pixel_ratio` stats (requires equal dimensions) |
| `list_assets` | Read the revision ledger (read-only) |
| `export_asset` | Write a revision out to a given path (an existing file is only overwritten when `overwrite:true` is explicitly set) |

## Recipe example

```json
{
  "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 (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`.
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:

```json
{ "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 `.c