atx-mcp

Apply a transform recipe at full resolution and issue a new revision. Pass either `recipe` ({"operations": [...]}, applied in order, at most one "encode" and it must be last) or `preset` (a built-in named recipe) - exactly one of the two - and either `revision_id` (one image) or `revision_ids` (the same recipe over a batch of up to 64; one failure does not abort the rest). Call list_operations for the operation catalog and the preset names, explain_operation for one operation's full schema. Idempotent: the same (revision_id, resolved recipe) returns the existing derived revision; a preset hashes identically to the equivalent raw recipe. Note: if the recipe's encode format is png, webp, or avif, any ICC color profile on the source is dropped (embedding is only supported for jpeg output); this is reported as a warning, not an error.

Scale two revisions to a long edge of 640px each and compose them on one canvas (side by side, or stacked) with an 8px gap, returned inline as a JPEG. A is placed left/top, B is placed right/bottom. Useful for before/after or A/B visual checks. layout="diff" instead requires A and B to share the exact same dimensions and returns a single pixel-difference heatmap plus mean_abs_diff/max_abs_diff/changed_pixel_ratio and an `ssim` score (structural similarity, 1.0 = identical). Every layout also reports `perceptual_hash_distance`: the Hamming distance between the two dHash values (0..=64), where 5 or less usually means the same picture re-encoded or resized and 20 or more means two different pictures.

Detect the dominant quadrilateral (a sheet of paper, a screen, a whiteboard, a sign) in a revision with a contour-based search, and return it as a ready-to-paste perspective operation. This is to `perspective` what detect_tilt is to `rotate`: read-only, it never modifies the image, and a null quad means "do not correct". The quad is in post-EXIF-orientation pixel coordinates, ordered tl, tr, br, bl, and `output_size_hint` is exactly the size `perspective` will produce from it. Optional `min_area_ratio` (0.05..=1.0, default 0.2) is the smallest fraction of the frame a candidate may cover. When quad is null the reason is the first warning: no_quad_found, already_rectified (the page already fills the frame) or low_confidence.

Find the text-like blocks (headline, paragraphs, table, caption) of a revision with a binarize + run-length smearing + connected-components pass, and report whether the text will survive a preview downscale. Read-only: it never modifies the image. Blocks come back in reading order (top to bottom, then left to right) in post-EXIF-orientation pixel coordinates, each with its line_count, median_line_height_px and ink_ratio. `legibility.line_height_at_1568_px` is the median line height once the whole image is shrunk to long edge 1568 (below ~16 the text is usually unreadable), and `legibility.recommended_bands` splits the image into crops that clear that bar - each entry is already a `crop` operation, so paste one into a recipe before render_preview `long_edge: 1568` and read them in order. `legibility.strategy` says how it split: "whole" (no split needed), "bands" (full-width horizontal bands) or "blocks" (per-block crops, used when the image is too wide for full-width bands to help). Optional `max_blocks` (1..=128, default 32) and `min_block_area_ratio` (0.0..=1.0, default 0.00005) bound how many and how small the blocks may be. No block found means the image has no text-like structure, not an error.

Detect the tilt (roll) of a revision: Canny + Hough dominant lines for coarse candidates, refined below 0.1 degree with an edge projection-profile search. Horizontal-only and vertical-only estimates are reported separately so a disagreement can be read as perspective/camera position rather than roll, Set include_score_curve=true to also get the whole search range as a score curve (omitted by default to keep the answer small). Read-only: it never modifies the image. A null recommended angle means "do not correct".

Full reference for one recipe operation: every parameter with its type, range, required/default status and semantics, one or two ready-to-paste JSON examples, and the gotchas worth knowing before using it. A built-in preset name works too and returns its full operation list, so a preset can be read and copied as a raw recipe. An unknown name returns a structured error listing every valid operation and preset. Read-only.

Copy revisions' bytes out of the workspace. Pass either `revision_id` + `dest_path` (one file) or `revision_ids` + `dest_dir` (a batch of up to 64 into one existing directory; one failure does not abort the rest) - exactly one of the two forms. For a batch, `filename_template` (default "{revision_id}.{ext}") builds each file name from {revision_id} / {index} (1-based, zero-padded) / {ext} (from the MIME type) / {stem} (the file name the lineage was imported from); it must be a plain file name, and if two entries would collide nothing is written. Refuses to overwrite an existing file unless overwrite=true (ask the user first), and never writes inside the workspace store or through a symbolic link.

Generate a deterministic grayscale mask as a new PNG revision, with exactly the dimensions of `reference_revision_id`. `kind` is "linear_gradient" (angle_degrees, start, end), "radial_gradient" (center_x, center_y, radius, feather), "luminosity_range" (min, max, feather) or "color_range" (hue_center, hue_width, feather); the gradients use only the reference's dimensions, the other two compute weights from its pixels. White = the masked operation applies fully, black = not at all. Reference the returned revision_id from any tone/filter operation as "mask": {"revision_id": "rev_...", "invert": false, "feather_px": 0}, or visualise it with render_preview overlay="mask". Idempotent: the same params over the same reference produce byte-identical PNG bytes and return the existing revision.

Import a local image file into the workspace and issue an immutable revision. Pass either `path` (one file) or `paths` (a batch of up to 64; one bad file does not abort the batch, it lands in `failed`) - exactly one of the two. Idempotent: importing the same bytes again returns the existing revision. If the imported bytes are already the output of a recipe held in this workspace, the result carries a warning plus `already_derived_from` so the same recipe is not applied twice.

Inspect a revision: dimensions, MIME type, byte size, alpha/ICC presence, EXIF orientation and summary, whether GPS (PII) metadata is present, luma statistics, a `sharpness` score (variance of the Laplacian - relative, so compare it against a known-good capture rather than an absolute; for documents below ~30 usually means motion blur or defocus) and a `perceptual_hash` (dHash, 16 hex digits) for telling "is this the same picture?" without comparing pixels. Set include_exif=true to also get every EXIF field as {ifd, tag, value} entries; it is off by default because the full dump can carry GPS coordinates and names.

List revisions in the workspace ledger (lineage, recipe hash, dimensions, sizes).

Compact catalog of the recipe vocabulary: every operation with a one-line description and its parameter names with terse type/range hints, plus the built-in preset names. Optional `category` ("geometry" | "color" | "filter" | "output") narrows the list. Call explain_operation for the full schema of one operation. Read-only.

Render a recipe as a small JPEG preview (long edge <= 768 by default) and return it inline plus a file path, so the composition can be checked before committing to apply_transform. Takes either `recipe` or `preset`, exactly like apply_transform - or NEITHER, which previews the revision as it is (use this with overlay="grid" to read crop coordinates off an image before writing a recipe). Optional `long_edge` (256..=1568) sets the preview size: raise it to 1568 when the point of the preview is to READ text in the image; 768 is too small for that. Optional `overlay` ("grid" | "thirds" | "horizon") draws semi-transparent composition guide lines on the returned preview only (never on the apply_transform output). overlay="mask" instead visualises a mask: pass `mask_revision_id` (required for this overlay and rejected for the others) and the preview is tinted red where the mask weight exceeds 0.5 and dimmed elsewhere, so the coverage can be eyeballed. Note: if the recipe's encode format is png, webp, or avif, any ICC color profile on the source is dropped (embedding is only supported for jpeg output); this is reported as a warning, not an error.