atx-mcp

English | 日本語 | 简体中文

범용 AI 에이전트를 위한 결정적(deterministic) (비생성적) 에셋 변환 MCP 서버로, Rust로 작성되었습니다.

편집 의도 — "지평선을 수평으로 맞추고, 16:9로 크롭하고, 살짝 밝게" — 를 선언적 변환 레시피로 실행하며, 모든 결과를 불변 리비전으로 추적합니다. 원본 에셋은 절대 수정되지 않습니다.

틸트 보정 + 자동 레벨 + 룩 적용(완전히 결정적인 레시피) — 왼쪽: 입력 / 오른쪽: 출력.

전체 설계에 대해서는 docs/DESIGN.md를 참조하세요.

사용 사례

1. 기사용 아이캐치 이미지

   "이 사진을 수평으로 맞추고 16:9, 1600px 아이캐치로 크롭해 줘. WebP로." import_asset → detect_tilt(이미 수평에 가까우면 AI가 보정을 건너뜀) → apply_transform(rotate → crop → resize → encode) → export_asset. 원본은 절대 건드리지 않으며, 동일한 레시피는 항상 동일한 결과를 재현합니다.

2. 소셜/CMS용 여러 크기

   "이 사진의 OGP, 인스타그램 정사각형, 썸네일 버전을 생성해 줘." 하나의 원본이 OGP 1200×630, 인스타그램 1080 정사각형, 400px 썸네일로 병렬로 분기됩니다. 동일 레시피-동일 리비전 멱등성 덕분에 다시 실행해도 출력이 중복 생성되지 않으며, 한 단어 프리셋 이름도 사용할 수 있습니다.

3. 게시해도 안전

   "위치 데이터는 반드시 제거하되, 색상은 건드리지 마." strip_metadata(exif)는 GPS를 포함한 EXIF를 제거하면서 ICC 프로파일은 유지합니다. AI는 inspect_image의 has_gps를 확인하여 사전에 경고할 수도 있습니다.

4. 색상 및 룩 조정

   "하늘만 더 파랗게 만들고, 나머지는 그대로 둬." curves / levels / hsl / white_balance, film_soft 프리셋, 그리고 import_asset으로 자신만의 .cube LUT를 가져온 뒤 lut로 적용하는 것을 지원합니다.

5. 로컬(마스크) 조정

   "하늘만 살짝 어둡게 하고, 지면은 그대로 둬." generate_mask는 마스크(그라디언트, 명도 범위 또는 색상 범위)를 생성합니다. 조정에 연결한 후 overlay:"mask"와 함께 render_preview를 실행하면 커밋하기 전에 정확히 어디에 적용될지 보여줍니다.

6. 레이어 합성

   "이 사진의 복사본을 블러 처리하고 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, Windows에서는 %LOCALAPPDATA%\Programs\atx-mcp이며, 압축 파일은 추출 전에 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(Windows에서는 .zip)를 받으세요.

지원 대상:

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_matix / curves / leves / lut / white_balance / hsl / blur / median / unsharp_mask / convolve / clone / heal / svg_overlay / flip / vignette / grain / gradient_map / pixelate / auto_leves / encode (jpeg, png, webp, avif) / strip_metadata.

작업 어휘는 의도적으로 도구 스키마에서 제외되어 있습니다. 최신 카탈로그는 list_operations를, 특정 작업의 전체 스키마, 예제 및 주의사항은 explain_operation을 호출하세요.

LUT (.cube)

.cube 3D/1D LUT는 이미지가 아니라 에셋입니다. 먼저 가져온 다음, 그 결과로 생성된 리비전을 레시피가 가리키게 하세요.

1. import_asset으로 .cube 파일을 가져옵니다. 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. import_asset으로 .svg 파일을 가져옵니다. mime_type: "image/svg+xml"인 불변 리비전으로 저장되며, 요약에는 SVG의 고유 크기가 보고됩니다(0x0은 고유 크기가 없음을 의미합니다 — 루트 <svg>에 viewBox가 없고 절대 width/height도 없음). 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는 둘 다 지정하지 않는 한 구조적 오류입니다. 합성은 layers와 동일한 W3C 공식과 동일한 16개 blend_mode 값을 사용합니다.

텍스트는 절대 렌더링되지 않습니다. atx는 시스템 폰트를 로드하지 않습니다. 설치된 폰트는 머신마다 다르며 바이트 단위 재현성을 깨뜨리기 때문입니다. <text>를 포함하는 SVG는 모양은 렌더링하지만 글리프는 렌더링하지 않고 경고를 보고합니다. — 가져오기 전에 벡터 편집기에서 텍스트를 패스(외곽선)로 변환하세요. 그러면 모든 머신에서 결과가 동일합니다.

마스크(로컬 조정)

마스크는 회색조 이미지 리비전입니다. 마스크의 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. overlay:"mask" 및 mask_revision_id를 사용한 render_preview는 가중치가 0.5를 초과하는 곳을 빨간색으로 표시하고 나머지 영역은 어둡게 하여, 커밋 전에 적용 범위를 확인할 수 있게 합니다.

마스크는 LUT와 정확히 동일하게 리비전 ID로 참조되므로 동일한 주의 사항이 적용됩니다. 레시피 해시에는 ID가 포함되며, 레시피는 해당 마스크를 보유한 작업 공간 안에서만 재현됩니다.

레이어

레시피는 평면 operations 목록 대신(또는 그에 더해) layers 스택을 가질 수 있습니다. 레이어는 아래에서 위로 합성되며, 각 레이어의 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(멱등성 키)는 해석된 레시피를 기준으로 계산됩니다. 따라서 프리셋 호출과 동등한 원시 레시피는 동일한 리비전에 도달합니다.

보장

• 결정적(Deterministic): 동일한 입력 + 동일한 레시피는 항상 바이트 단위로 동일한 출력을 생성합니다(골든 테스트로 회귀 검증됨)

• 멱등(Idempotent): 레시피는 정규화되고(키 정렬, f64 값은 1e-6 그리드로 양자화) sha256으로 해시됩니다. (input revision, recipe hash)가 기존 쌍과 일치하면 새 리비전 대신 기존 리비전이 반환됩니다

• 원본은 보호됩니다: 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 폼 팩터나 Markdown ATX 스타일 제목과는 관계가 없습니다.

라이선스

MIT. LICENSE를 참조하세요.

atx-mcp가 시간을 절약해 준다면 커피 한 잔 사주세요 ☕