atx-mcp

English | 日本語 | 简体中文

Детерминированный (не-генеративный) MCP-сервер преобразования ассетов для универсальных ИИ-агентов, написанный на Rust.

Он исполняет редакторское намерение — «выровняй горизонт, обрежь до 16:9, сделай немного ярче» — как декларативный рецепт преобразования и отслеживает каждый результат как неизменяемую ревизию. Оригинальный ассет никогда не изменяется.

Коррекция наклона + автоуровни + применённый стиль (полностью детерминированный рецепт) — слева: вход / справа: выход.

Полное описание см. в docs/DESIGN.md.

Варианты использования

1. Привлекающее изображение для статьи

   «Выровняй это фото и обрежь до 16:9, 1600px, для обложки. WebP.» import_asset → detect_tilt (ИИ пропускает коррекцию, если изображение уже почти ровное) → apply_transform (rotate → crop → resize → encode) → export_asset. Оригинал никогда не затрагивается, и один и тот же рецепт каждый раз воспроизводит один и тот же результат.

2. Несколько размеров для соцсетей/CMS

   «Сгенерируй OGP, квадратную версию для Instagram и миниатюру этого фото.» Один оригинал расходится параллельно на OGP 1200×630, квадрат 1080 для Instagram и миниатюру 400px. Идемпотентность «один и тот же рецепт — одна и та же ревизия» означает, что повторный запуск никогда не создаёт вывод дважды; достаточно и однословного имени пресета.

3. Безопасно для публикации

   «Точно удали данные о местоположении, но не трогай цвета.» strip_metadata (exif) удаляет EXIF, включая GPS, сохраняя ICC-профиль нетронутым. ИИ также может предупредить заранее, проверив has_gps через inspect_image.

4. Цветовые и стилевые корректировки

   «Сделай только небо синее, всё остальное не трогай.» Охватывает curves / levels / hsl / white_balance, пресет film_soft, а также импорт собственного .cube LUT через import_asset и его применение через lut.

5. Локальные (маскированные) корректировки

   «Немного затемни только небо, а землю оставь как есть.» generate_mask создаёт маску (градиент, диапазон яркости или диапазон оттенка); после подключения маски к корректировке render_preview с overlay:"mask" покажет точно, где изменение подействует, прежде чем вы его примените.

6. Композитинг слоёв

   «Размой копию этого фото и смешай её в режиме screen на 50% для мягкого свечения.» Стек layers объединяет 16 режимов наложения, непрозрачность и маски для создания воспроизводимых композиций, например мягкого фокуса.

7. Водяные знаки, ретушь и перспектива

   «Впечатай мой логотип в угол, убери линии электропередач и исправь сходящиеся вертикали.» svg_overlay впечатывает логотип, clone/heal удаляют дефекты или провода, компонуя текстуру и тон, а perspective исправляет сходящиеся вертикали.

8. Проверка и подотчётность

   «Покажи это изображение до и после правок, бок о бок.» compare_revisions размещает до/после бок о бок или возвращает тепловую карту различий со статистикой вроде mean_abs_diff. Каждая ревизия сохраняет свою родословную, поэтому полную историю правок любого изображения, использованного в статье, можно проследить и воспроизвести — побайтно идентично на любой машине.

Чего atx не делает — генеративного редактирования, RAW-конвертации, ML-автокадрирования — это вне области применения; дорожную карту см. в docs/DESIGN.md.

Related MCP server: img-convert MCP Server

Установка

Инструментарий Rust не требуется. Выберите один из вариантов.

1. npx (проще всего, рекомендуется)

Достаточно Node.js 18+. Готовый нативный бинарник для вашей платформы подтягивается автоматически через 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

Или добавьте его напрямую в конфиг вашего MCP-клиента:

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

2. Готовый бинарник

Скрипты установки (по умолчанию устанавливается в ~/.local/bin или в %LOCALAPPDATA%\Programs\atx-mcp на Windows; архив проверяется по SHA256SUMS перед распаковкой):

# 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

Для ручной загрузки возьмите atx-mcp-<version>-<target>.tar.gz (.zip на Windows) со страницы Releases. Поддерживаемые целевые платформы:

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

3. Сборка из исходников (любая другая платформа)

Нужны только инструментарий Rust и C-компилятор (для сборки libwebp из его приложенного исходного кода).

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) — это каталог, используемый как хранилище ассетов. Он создаётся автоматически, если его нет.

Инструменты (11)

Пример рецепта

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

Поддерживаемые операции (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. Словарь операций намеренно не включён в схемы инструментов: вызывайте list_operations для актуального каталога и explain_operation для полной схемы, примеров и подводных камней конкретной операции.

LUT (.cube)

.cube 3D/1D LUT — это ассет, а не изображение: сначала импортируйте его, затем укажите рецепту на созданную им ревизию.

1. Импортируйте файл .cube через import_asset. Он сохраняется как неизменяемая ревизия с mime_type: "application/x-cube" (inspect_image намеренно отказывается его обрабатывать — это не изображение).

2. Используйте возвращённый revision_id в рецепте:

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

strength (0..1, по умолчанию 1.0) линейно смешивается с оригиналом. Поскольку ревизии неизменяемы, включение указанного id в recipe_hash делает преобразование полностью детерминированным — но это также означает, что рецепт воспроизводим только внутри рабочего пространства, где хранится этот LUT, поэтому при переносе стиля между машинами переносите .cube вместе с рецептом. Обращение к неизвестному id завершается структурированной ошибкой до начала какой-либо работы с пикселями.

Наложения SVG (логотипы и водяные знаки)

.svg — это векторный ассет, как и .cube LUT: сначала импортируйте его, затем впечатывайте его в растровое изображение из рецепта.

1. Импортируйте файл .svg через import_asset. Он сохраняется как неизменяемая ревизия с mime_type: "image/svg+xml", а в сводке сообщается собственный размер SVG (0x0 означает, что его нет — нет viewBox и абсолютных width/height у корневого <svg>). inspect_image намеренно отказывается его обрабатывать: это векторный ассет, а не растровое изображение.

2. Используйте возвращённый revision_id в рецепте:

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

x/y — это левый верхний угол оверлея в координатах изображения на этом этапе конвейера (поэтому размещайте оверлей после изменения размера/кадрирования); отрицательные значения допустимы, а выходящее за границы обрезается. Если опустить width и height, растеризация выполняется в собственном размере SVG; укажите одно значение, чтобы масштабировать с сохранением пропорций, или оба, чтобы растянуть до точного прямоугольника — SVG без собственного размера является структурированной ошибкой, если не заданы оба. Композитинг использует ту же формулу W3C и те же 16 значений blend_mode, что и слои.

Текст никогда не отрисовывается. atx не загружает системные шрифты, потому что установленные шрифты отличаются от машины к машине и нарушили бы побайтовую воспроизводимость. SVG, содержащий <text>, отображает его фигуры, но не глифы, и выдаёт предупреждение — преобразуйте текст в кривые (контуры) в своём векторном редакторе перед импортом, и результат будет идентичным на любой машине.

Маски (локальные корректировки)

Маска — это ревизия изображения в градациях серого: её яркость BT.709 является весом, поэтому белый означает «применить эту операцию в полную силу», а чёрный — «оставить пиксель без изменений». Любая из 14 операций тона/фильтра (adjust, color_matrix, curves, levels, hsl, lut, white_balance, blur, median, unsharp_mask, convolve, grain, gradient_map, auto_levels) принимает её.

1. generate_mask детерминированно создаёт её на основе эталонного изображения, с точностью до размеров этого изображения:

Вместо этого вы также можете импортировать собственное изображение в градациях серого через import_asset.

2. Прикрепите возвращённый revision_id к операции:

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

invert (по умолчанию false) инвертирует вес в 1-w; feather_px (по умолчанию 0.0) размывает край маски на эту сигму гауссова размытия в пикселях текущего изображения.

3. render_preview с overlay:"mask" и mask_revision_id окрашивает предпросмотр в красный там, где вес превышает 0.5, и затемняет его в остальных местах, чтобы покрытие можно было проверить до фиксации.

Маски, как и LUT, ссылаются на идентификатор ревизии, поэтому действует та же оговорка: хэш рецепта включает идентификатор, и рецепт воспроизводится только внутри рабочего пространства, содержащего эту маску.

Слои

Рецепт может содержать стек layers вместо плоского списка operations (или в дополнение к нему). Слои компонуются снизу вверх: ops каждого слоя выполняются над его собственным источником, прежде чем слой будет смешан с текущим композитом:

{
  "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 — это либо "base" (входная ревизия, переданная в apply_transform / render_preview), либо {"revision_id": "rev_..."} (любая другая ревизия, уже находящаяся в рабочем пространстве). Источник каждого слоя должен точно совпадать по размерам с базовым изображением, иначе рецепт завершается структурированной ошибкой до начала работы с пикселями.

• ops — обычный список операций, применяемый только к источнику этого слоя.

• mask, blend_mode (по умолчанию "normal") и opacity (по умолчанию 1.0) управляют тем, как слой компонуется со слоями под ним.

• Режим наложения — один из 16 режимов W3C: 12 разделимых режимов normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, плюс 4 неразделимых режима hue, saturation, color, luminosity.

• Когда присутствует layers, верхнеуровневый operations становится финишным проходом, применяемым один раз к результату композитинга — именно сюда относятся resize и финальный encode (encode по-прежнему должен быть последним и встречаться не более одного раза).

• Вызовите explain_operation {"operation":"layers"} для получения полного справочника.

Пресеты

apply_transform и render_preview принимают либо recipe (непосредственно DSL), либо preset (встроенный именованный рецепт из presets/) — ровно одно из двух:

Пресет — это просто синтаксический сахар: он разворачивается в свой рецепт и проходит обычный конвейер, а recipe_hash (ключ идемпотентности) вычисляется от разрешённого рецепта — поэтому вызов пресета и эквивалентный «сырой» рецепт приводят к одной и той же ревизии.

Гарантии

• Детерминированность: один и тот же вход + один и тот же рецепт всегда дают побайтово идентичный результат (проверяется регрессионными golden-тестами)

• Идемпотентность: рецепты нормализуются (ключи сортируются, значения f64 квантуются до сетки 1e-6) и хэшируются с помощью sha256. Если пара (входная ревизия, хэш рецепта) совпадает с существующей, возвращается существующая ревизия, а не новая

• Оригиналы защищены: objects/ — это хранилище, доступное только для добавления и адресуемое по содержимому: API удаления или перезаписи не существует

Разработка

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

Структура крейтов: atx-core (движок рецептов/трансформаций) / atx-geometry (обнаружение наклона) / atx-store (неизменяемое хранилище ресурсов) / atx-mcp (rmcp stdio-сервер).

Процесс релиза описан в RELEASING.md.

Название

«atx» расшифровывается как Asset Transform; завершающая x следует привычному сокращению для «transform» (как в xform / tx). Это имя было выбрано как короткое и удобное для ввода имя бинарного файла и префикс крейтов (atx-core и т.д.), и оно не связано ни с форм-фактором PC ATX, ни с ATX-заголовками в стиле Markdown.

Лицензия

MIT. См. LICENSE.

Если atx-mcp экономит ваше время, вы можете угостить меня кофе ☕