atx-mcp

English | 日本語 | 简体中文

汎用AIエージェント向けの、決定的（非生成）アセット変換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. SNS/CMS向けの複数サイズ

   「この写真のOGP、Instagramスクエア、サムネイル版を生成して。」 1つの元画像から、OGP 1200×630、Instagram 1080スクエア、400pxサムネイルが並列で生成されます。同じレシピ=同じリビジョンという冪等性により、再実行しても出力が二重に作成されることはありません。1語のプリセット名でも機能します。

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はBefore/Afterを並べて表示するか、mean_abs_diffなどの統計情報とともに差分ヒートマップを返します。すべてのリビジョンは系統（lineage）を保持するため、記事で使われた画像の完全な編集履歴を追跡・再現できます。しかもどのマシンでもバイト単位で同一です。

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

手動でダウンロードする場合は、Releasesから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_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、1つの操作の完全なスキーマ・例・落とし穴は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はサイズなしを意味します — ルートの<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. render_preview に overlay:"mask" と mask_revision_id を指定すると、重みが 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 モードの 1 つです。分離可能な 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 は依然として最後で、最大 1 回だけ出現する必要があります）。

• 完全なリファレンスは explain_operation {"operation":"layers"} を呼び出してください。

プリセット

apply_transform と render_preview は recipe（生の DSL）または preset（presets/ にある組み込みの名前付きレシピ）のいずれかを受け取ります — 2 つのうち正確に 1 つです:

プリセットは単なる糖衣構文です。プリセットは自身のレシピに解決され、通常のパイプラインを通ります。recipe_hash（冪等性キー）は解決後のレシピに対して計算されるため、プリセット呼び出しと同等の生レシピは同じリビジョンになります。

保証

• 決定的: 同じ入力 + 同じレシピは常にバイト単位で同一の出力を生成します（ゴールデンテストで回帰チェック済み）

• 冪等: レシピは正規化され（キーをソート、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 フォームファクタや Markdown の ATX スタイル見出しとは関係ありません。

ライセンス

MIT。 LICENSE を参照してください。

atx-mcp が時間の節約になったなら、コーヒーを一杯ごちそうしてください ☕