atx-mcp

English | 日本語 | 简体中文

Ein deterministischer (nicht-generativer) MCP-Server zur Asset-Transformation für universelle KI-Agenten, geschrieben in Rust.

Er setzt Bearbeitungsabsichten – „den Horizont ausrichten, auf 16:9 zuschneiden, ein wenig aufhellen“ – als deklaratives Transformationsrezept um und zeichnet jedes Ergebnis als unveränderliche Revision auf. Das ursprüngliche Asset wird niemals verändert.

Kippkorrektur + automatische Levels + angewendeter Look (ein vollständig deterministisches Rezept) – links: Eingabe / rechts: Ausgabe.

Siehe docs/DESIGN.md für das vollständige Design.

Anwendungsfälle

1. Blickfang-Bild für einen Artikel

   „Richte dieses Foto gerade und schneide es als 16:9-Blickfang mit 1600px zu. WebP.“ import_asset → detect_tilt (die KI überspringt die Korrektur, wenn das Bild bereits annähernd gerade ist) → apply_transform (rotate → crop → resize → encode) → export_asset. Das Original wird nie angefasst, und dasselbe Rezept reproduziert jedes Mal dasselbe Ergebnis.

2. Mehrere Größen für Social Media/CMS

   „Erzeuge die OGP-, Instagram-Quadrat- und Thumbnail-Versionen dieses Fotos.“ Ein einziges Original wird parallel zu OGP 1200×630, Instagram-Quadrat 1080 und einer 400-px-Thumbnail aufgefächert. Die Idempotenz von gleichem Rezept und gleicher Revision bedeutet, dass eine erneute Ausführung nie doppelte Ausgaben erzeugt; auch ein einwortiger Preset-Name funktioniert.

3. Sicher zu veröffentlichen

   „Entferne auf jeden Fall die Standortdaten, aber fasse die Farben nicht an.“ strip_metadata (exif) entfernt EXIF einschließlich GPS, während das ICC-Profil erhalten bleibt. Die KI kann auch rechtzeitig warnen, indem sie has_gps aus inspect_image prüft.

4. Farb- und Look-Anpassungen

   „Mach nur den Himmel blauer, lass alles andere unverändert.“ Umfasst curves / levels / hsl / white_balance, das Preset film_soft sowie das Importieren einer eigenen .cube-LUT mit import_asset und anschließendes Anwenden mit lut.

5. Lokale (maskierte) Anpassungen

   „Verdunkle nur den Himmel ein wenig, lass den Boden unverändert.“ generate_mask erstellt eine Maske (Verlauf, Luminanzbereich oder Farbtonbereich); nachdem sie in die Anpassung eingebunden wurde, zeigt render_preview mit overlay:"mask" genau, wo sie greift, bevor du sie übernimmst.

6. Ebenen-Compositing

   „Verwische eine Kopie dieses Fotos und blende sie mit 50 % Screen für einen weichen Schein ein.“ Der layers-Stapel kombiniert 16 Mischmodi, Deckkraft und Masken, um reproduzierbare Composings wie Soft Focus zu erzeugen.

7. Wasserzeichen, Retusche und Perspektive

   „Stempel mein Logo in die Ecke, entferne die Stromleitungen und korrigiere die stürzenden Linien.“ svg_overlay brennt ein Logo ein, clone/heal entfernen Makel oder Leitungen, indem sie Textur und Tonwert per Compositing kombinieren, und perspective korrigiert stürzende Linien.

8. Verifikation und Nachvollziehbarkeit

   „Zeig mir dieses Bild vor und nach den Bearbeitungen nebeneinander.“ compare_revisions platziert Vorher/Nachher nebeneinander oder liefert eine Differenz-Heatmap mit Statistiken wie mean_abs_diff. Jede Revision behält ihre Abstammung, sodass die vollständige Bearbeitungshistorie hinter jedem in einem Artikel verwendeten Bild nachvollzogen und reproduziert werden kann – byteidentisch auf jeder Maschine.

Was atx nicht kann – generative Bearbeitung, RAW-Entwicklung, ML-basiertes automatisches Zuschneiden – liegt außerhalb des Anwendungsbereichs; die Roadmap findest du in docs/DESIGN.md.

Related MCP server: img-convert MCP Server

Installation

Keine Rust-Toolchain erforderlich. Wähle eine der folgenden Optionen.

1. npx (am einfachsten, empfohlen)

Node.js 18+ ist alles, was du brauchst. Die vorgefertigte native Binärdatei für deine Plattform wird automatisch über optionalDependencies bezogen.

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

Oder füge es direkt in deine MCP-Client-Konfiguration ein:

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

2. Vorgefertigte Binärdatei

Installationsskripte (Standard-Installationsort ist ~/.local/bin, unter Windows %LOCALAPPDATA%\Programs\atx-mcp; das Archiv wird vor dem Entpacken gegen SHA256SUMS verifiziert):

# 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

Für den manuellen Download lade atx-mcp-<version>-<target>.tar.gz (unter Windows .zip) von Releases herunter. Unterstützte Zielplattformen:

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

3. Aus dem Quellcode bauen (jede andere Plattform)

Du brauchst nur eine Rust-Toolchain und einen C-Compiler (um libwebp aus dem mitgelieferten Quellcode zu bauen).

cargo build --release
# => target/release/atx-mcp
claude mcp add asset-transform -- "$PWD/target/release/atx-mcp" --workspace /path/to/asset-workspace

--workspace (Umgebungsvariable: ATX_WORKSPACE) ist das Verzeichnis, das als Asset-Store verwendet wird. Es wird automatisch erstellt, wenn es nicht existiert.

Tools (11)

Rezeptbeispiel

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

Unterstützte Operationen (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. Das Operations-Vokabular ist bewusst aus den Tool-Schemas herausgehalten: Rufe list_operations für den aktuellen Katalog auf und explain_operation für das vollständige Schema, Beispiele und Stolperfallen einer Operation.

LUT (.cube)

Eine .cube-3D/1D-LUT ist ein Asset, kein Bild: Importiere sie zuerst und richte dann ein Rezept auf die von ihr erzeugte Revision aus.

1. import_asset die .cube-Datei. Sie wird als unveränderliche Revision mit mime_type: "application/x-cube" gespeichert (inspect_image lehnt sie bewusst ab – sie ist kein Bild).

2. Referenziere die zurückgegebene revision_id in einem Rezept:

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

strength (0..1, Standard 1.0) mischt linear mit dem Original. Da Revisionen unveränderlich sind, hält die Aufnahme der referenzierten ID in den recipe_hash die Transformation vollständig deterministisch – das bedeutet aber auch, dass das Rezept nur in einem Workspace reproduzierbar ist, der diese LUT enthält. Verschiebe die .cube-Datei also zusammen mit dem Rezept, wenn du einen Look zwischen Maschinen überträgst. Das Referenzieren einer unbekannten ID schlägt mit einem strukturierten Fehler fehl, bevor irgendeine Pixelarbeit passiert.

SVG-Overlays (Logos und Wasserzeichen)

Eine .svg-Datei ist ein Vektor-Asset, ähnlich wie eine .cube-LUT: Importiere sie zuerst und stempel sie dann aus einem Rezept auf ein Rasterbild.

1. import_asset die .svg-Datei. Sie wird als unveränderliche Revision mit mime_type: "image/svg+xml" gespeichert, und die Zusammenfassung meldet die intrinsische Größe der SVG (0x0 bedeutet, dass sie keine hat – kein viewBox und keine absoluten width/height am Wurzel-<svg>). inspect_image lehnt sie bewusst ab: Es ist ein Vektor-Asset, kein Rasterbild.

2. Referenziere die zurückgegebene revision_id in einem Rezept:

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

x/y sind die obere linke Ecke des Overlays in den Koordinaten des Bildes an diesem Punkt der Pipeline (platzieren Sie das Overlay also nach Ihrer Größenänderung bzw. Ihrem Zuschnitt); negative Werte sind erlaubt und der Überlauf wird abgeschnitten. Lassen Sie width und height weg, um mit der intrinsischen Größe der SVG zu rastern; geben Sie einen davon an, um unter Beibehaltung des Seitenverhältnisses zu skalieren, oder beide, um auf eine exakte Box zu strecken – eine SVG ohne intrinsische Größe ist ein strukturierter Fehler, wenn Sie nicht beide angeben. Das Compositing verwendet dieselbe W3C-Formel und dieselben 16 blend_mode-Werte wie layers.

Text wird nie gerendert. atx lädt keine Systemschriftarten, weil sich die installierten Schriftarten von Maschine zu Maschine unterscheiden und die Byte-für-Byte-Reproduzierbarkeit brechen würden. Eine SVG, die <text> enthält, rendert ihre Formen, aber nicht ihre Glyphen und gibt eine Warnung aus – konvertieren Sie Text vor dem Import in Ihrem Vektor-Editor in Pfade (Konturen), und das Ergebnis ist auf jeder Maschine identisch.

Masken (lokale Anpassungen)

Eine Maske ist eine Graustufen-Bildrevision: Ihre BT.709-Luma ist der Gewichtswert, also bedeutet Weiß „diese Operation mit voller Stärke anwenden“ und Schwarz „das Pixel unverändert lassen“. Jede der 14 Tonwert-/Filteroperationen (adjust, color_matrix, curves, levels, hsl, lut, white_balance, blur, median, unsharp_mask, convolve, grain, gradient_map, auto_levels) akzeptiert eine.

1. generate_mask erstellt eine deterministisch anhand eines Referenzbildes, mit exakt den Abmessungen dieses Bildes:

Sie können stattdessen auch import_asset mit einem eigenen Graustufenbild verwenden.

2. Hängen Sie die zurückgegebene revision_id an eine Operation an:

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

invert (Standard false) kehrt den Gewichtswert zu 1-w um; feather_px (Standard 0.0) weicht die Maskenkante mit dieser Gauß-Sigma in Pixeln des aktuellen Bildes auf.

3. render_preview mit overlay:"mask" und mask_revision_id färbt die Vorschau rot, wo der Gewichtswert 0.5 überschreitet, und dimmt sie andernorts, sodass die Abdeckung vor dem Übernehmen überprüft werden kann.

Masken werden genau wie LUTs über die Revisions-ID referenziert, daher gilt dieselbe Einschränkung: Der Rezept-Hash enthält die ID, und das Rezept reproduziert nur in einem Workspace, der diese Maske enthält.

Layers

Ein Rezept kann einen layers-Stapel anstelle von (oder zusätzlich zu) einer flachen operations-Liste enthalten. Ebenen werden von unten nach oben zusammengesetzt; die ops jeder Ebene laufen gegen ihre eigene Quelle, bevor sie in das laufende Composite übergeblendet wird:

{
  "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 ist entweder "base" (die an apply_transform / render_preview übergebene Eingaberevision) oder {"revision_id": "rev_..."} (eine andere, bereits im Workspace vorhandene Revision). Die Quelle jeder Ebene muss exakt den Abmessungen des Basisbildes entsprechen, sonst schlägt das Rezept mit einem strukturierten Fehler fehl, bevor irgendeine Pixelarbeit stattfindet.

• ops ist eine normale Liste von Operationen, die nur auf die Quelle dieser Ebene angewendet wird.

• mask, blend_mode (Standard "normal") und opacity (Standard 1.0) steuern, wie die Ebene mit den darunterliegenden Ebenen zusammengesetzt wird.

• Der Mischmodus ist einer von 16 W3C-Modi: die 12 separierbaren Modi normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion sowie die 4 nicht separierbaren Modi hue, saturation, color, luminosity.

• Wenn layers vorhanden ist, wird die übergeordnete operations-Liste zum Enddurchgang, der einmal auf das zusammengesetzte Ergebnis angewendet wird – hier gehören resize und das finale encode hin (encode muss weiterhin zuletzt kommen und darf höchstens einmal vorkommen).

• Rufen Sie explain_operation {"operation":"layers"} auf, um die vollständige Referenz zu erhalten.

Presets

apply_transform und render_preview akzeptieren entweder recipe (das rohe DSL) oder preset (ein eingebautes, benanntes Rezept aus presets/) – genau eines von beidem:

Ein Preset ist reiner Zucker: Es wird zu seinem Rezept aufgelöst und durchläuft die normale Pipeline, und der recipe_hash (der Idempotenzschlüssel) wird für das aufgelöste Rezept berechnet – ein Preset-Aufruf und das äquivalente rohe Rezept landen also auf derselben Revision.

Garantien

• Deterministisch: Dieselbe Eingabe + dasselbe Rezept erzeugen immer byte-identische Ausgabe (mit Golden-Tests regressionsgeprüft)

• Idempotent: Rezepte werden normalisiert (Schlüssel sortiert, f64-Werte auf ein 1e-6-Raster quantisiert) und mit sha256 gehasht. Wenn (input revision, recipe hash) mit einem vorhandenen Paar übereinstimmt, wird die vorhandene Revision statt einer neuen zurückgegeben

• Originale sind geschützt: objects/ ist ein nur-anhängbarer, inhaltsadressierter Speicher – es gibt keine Lösch- oder Überschreib-API

Entwicklung

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

Crate-Aufbau: atx-core (Rezept-/Transform-Engine) / atx-geometry (Neigungserkennung) / atx-store (unveränderlicher Asset-Speicher) / atx-mcp (rmcp-stdio-Server).

Siehe RELEASING.md für den Release-Prozess.

Name

„atx“ steht für Asset Transform; das nachgestellte x folgt der vertrauten Kurzform für „transform“ (wie in xform / tx). Es wurde als kurzer, leicht tippbarer Binärname und Crate-Präfix (atx-core usw.) gewählt und hat keinen Bezug zum PC-ATX-Formfaktor oder zu ATX-Überschriften im Markdown-Stil.

Lizenz

MIT. Siehe LICENSE.

Wenn atx-mcp Ihnen Zeit spart, können Sie mir einen Kaffee spendieren ☕