# abox.tools for agents

Published by **Abox Technologies**. Compress, resize and convert images; create
ICO icons, rasterize SVGs and compose image layouts; compress, watermark, merge,
split, reorder and rotate PDF pages; extract PDF tables to CSV; turn images into
PDFs; format JSON and XML; convert YAML and JSON; compare text files; encode or
decode Base64; embed images as data URIs; generate QR codes and barcodes; inspect
or remove image metadata; and calculate file checksums with the existing
[abox.tools](https://abox.tools/) code. An agent supplies local paths and receives
output paths and short JSON results. Offline file processing keeps bytes on your
computer and out of tool responses.

It also processes GIFs, admitted audio and supported video timelines; straightens
document photos; prepares custom ID photos and local previews; extracts receipt
fields with bundled OCR; inspects and renders a restricted DICOM subset; protects
and unlocks PDFs; redacts explicit image/PDF regions; and generates passwords into
local files. Codec and rendering operations expose documented subsets.

The public v0.11.0 release provides 66 offline file operations, six opt-in live
controls and one capabilities tool: 72 operations and 73 MCP tools.
Native and universal packages passed checks on all four target platforms.
See [tool coverage and concrete unsupported paths](docs/tool-coverage.md) for
the source engines reused by this adapter and the limits of each route.

Version 0.11.0 adds six live-session controls: a separate opt-in visible
companion for text/files, camera video and voice. Opening a window starts no
network or capture. The person clicks Start/Connect and handles permissions and
pairing there. Live mode uses the existing abox.tools pairing service and direct
encrypted WebRTC; the service sees negotiation metadata and keeps seven-day
Cloudflare metadata logs. There is no relay, discovery or recording. Read the
[live-session boundary](skills/abox-local-files/references/live-sessions.md).
The actual SHA-verified public Windows cache passed all 72 operations/73 tools
and all eight passive companion roles, with no capability absences or unrequested
pairing/capture. Public Gemini installation and the 15-file shared-skill copy also
passed. Real pairing-service and public-website interoperability checks used
temporary files and generated media in two isolated browsers on one computer.
Physical devices, native camera permission and desktop-client installation
remain unverified. See [v0.11.0 publication evidence](docs/publishing.md#v0110-publication-evidence).

Historically, version 0.10.0 added
HEIC/AVIF, flattened PDF redaction, sound extraction and admitted H.264 video
processing. It also expands audio and DICOM codec support. Publication and the
Registry readback were verified on 28 October 2026. The default Python installer
downloaded and checksum-verified the public Windows package. That actual cache
passed all 66 file operations and 67 MCP tools with its bundled runtime, without
capability absences or a local rebuild. Public Gemini CLI installation and the
shared skill's 14-file project installation also passed. The skill check
validated the installer contract offline; actual adapter installation was
proved separately by the public Python download and full MCP smoke. See the
[v0.10.0 publication evidence](docs/publishing.md#v0100-publication-evidence).

Historically, the public v0.9.0 Windows download passed all 55 file operations and 56 MCP tools
using its bundled runtime. Public Gemini CLI installation and the shared skill's
ten-file installation were also checked. See [publication evidence](docs/publishing.md),
including the historical v0.8.0 receipts.

**[Download the latest release](https://github.com/A-Box-of-Tools/abox-tools-plugin/releases/latest).**
Listed in the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.A-Box-of-Tools%2Fabox-tools/versions/0.11.0)
as `io.github.A-Box-of-Tools/abox-tools`. New tagged releases update the Registry
automatically after their downloads pass verification.

Release bundles include Node.js, production dependencies, pinned processing
code, and the shared skill. You do not need to install Node or npm, or type setup
commands. Image rendering/conversion, GIF creation/extraction, decoded audio,
receipt OCR, document scans, local previews, PDF raster redaction and video
decoding/encoding need an installed Edge, Chrome or Chromium. PDF page/security
operations, metadata operations, checksums, container inspection, audio/video
packet copying and text processing run without one.
QR codes and barcodes default to SVG without a browser; PNG output uses the
installed local browser. A native H.264 encoder is required for new MP4 encoding.

## Install in Codex

Download the matching `.zip` from the release's **Assets**:

| Release label | Computer |
| --- | --- |
| `windows-x64` | Windows with an Intel or AMD 64-bit processor |
| `macos-arm64` | Mac with Apple silicon |
| `macos-x64` | Mac with an Intel processor |
| `linux-x64` | Linux with an Intel or AMD 64-bit processor |

1. Extract the entire ZIP to a permanent folder. For example, a 0.11.0 Windows
   bundle extracts as `abox-tools-0.11.0-windows-x64`. Keep this folder in place
   because the local marketplace uses it for plugin refresh.
2. Open `START-HERE.html` inside the extracted folder. This page works offline.
   Select **Install in Codex**, allow your browser to open the desktop app, then
   select **Install** on the plugin's detail page.
3. Start a new local chat and ask for one of the operations below.

You need the desktop app installed with its `codex://` link handler available.
The button opens the app's supported local-plugin detail link; the app handles
installation. See the [official OpenAI deep-link documentation](https://learn.chatgpt.com/docs/app/commands).
If your browser blocks the link, use `Install in Codex.cmd` on Windows or
`Install in Codex.command` on macOS. Linux includes `Install in Codex.sh` for
file managers that support executing shell scripts. These launchers open the
same detail page and may briefly show a terminal; no commands need to be typed.

## Install the tools in Claude Desktop

Download the `universal.mcpb` from the same release, open it with Claude Desktop,
and follow its installation prompts. One file supports Windows x64, Linux x64,
and both Apple silicon and Intel Macs. It includes the runtimes and processing
dependencies. Smaller platform-specific MCPBs are also available. This installs
the MCP tools; the shared agent skill is part of the Codex ZIP.

If opening the file does not show an installer, go to **Settings → Desktop app →
Manage** beside Extensions, then **Advanced settings → Install Extension…** and
select the `.mcpb`. See [Claude's desktop extension instructions](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).
Bundle format and MCP execution are checked in CI on all four platforms. The
0.2.1 universal bundle was installed and enabled in Claude Desktop on Windows,
where the app reported its local MCP server Running. The macOS desktop interface
has not been checked. Download and install a new bundle when updating; custom
MCPB files do not update automatically.

Version 0.3.0 corrects the publisher to Abox Technologies. If your desktop host
shows both the earlier publisher entry and the new one, disable the older entry
to avoid duplicate tools.

## Install in Gemini CLI

With Gemini CLI installed, run:

```sh
gemini extensions install https://github.com/A-Box-of-Tools/abox-tools-plugin
```

Gemini selects the matching prebuilt archive from the latest GitHub Release.
The extension includes its runtime, dependencies and shared skill. Review the
installation prompt and allow its local MCP server. See the
[Gemini extension release guide](https://geminicli.com/docs/extensions/releasing/).

## Install tools in Cursor

Extract the matching native ZIP, open `START-HERE.html`, and select **Install
tools in Cursor**. Cursor shows the local server configuration before adding it.
Keep the extracted folder in place. This adds the MCP tools; the shared skill
can be installed separately. The repository's Cursor plugin route needs Node
and a one-time adapter setup; see [Cursor installation](docs/cursor.md).

## Install tools in VS Code

Extract the matching native ZIP, open `START-HERE.html`, and select **Install
tools in VS Code**. Review the local server configuration in VS Code and keep
the extracted folder in place. The button uses the bundled runtime; Node, npm
and a VSIX are not required. This installs MCP tools. Install the shared skill
separately if your agent supports it. See the
[official MCP installation-link documentation](https://code.visualstudio.com/api/extension-guides/ai/mcp#create-an-mcp-installation-url).

## Install the shared skill through skills.sh

For agents supported by the skills CLI (Node 22.20+):

```sh
npx skills add A-Box-of-Tools/abox-tools-plugin --skill abox-local-files
```

Then ask the agent to set up the abox.tools local adapter. The skill includes
a Python 3.9+ setup script that downloads the matching packaged release, verifies
its checksum and installs the bundled runtime. It does not require cloning or
building this project. See [standalone setup](skills/abox-local-files/references/installation.md).
The [skills.sh listing](https://www.skills.sh/a-box-of-tools/abox-tools-plugin/abox-local-files)
is public. Public v0.11.0 Gemini installation and skill copying were verified;
a Gemini gallery listing is unconfirmed.

## Ask the agent

- “Compress this photo below 500 KB and save a new copy.”
- “Resize this photo to fit within 1200 by 800 pixels.”
- “Convert this PNG to WebP.”
- “Merge these PDFs in this order.”
- “Split this PDF into one file per page.”
- “Extract pages 1–3 and 4–6 as two PDFs.”
- “Make one PDF containing pages 3, 1–2, and another copy of page 3.”
- “Rotate pages 2–4 clockwise by 90 degrees.”
- “Put these photos into one PDF, in this order.”
- “Check whether this image contains EXIF or XMP metadata.”
- “Remove location and other image metadata, keeping its orientation and colors.”
- “Calculate SHA-256 checksums for these files.”
- “Compress this scanned PDF for screen reading.”
- “Add a diagonal DRAFT watermark to every PDF page.”
- “Make an ICO with 16, 32, 48 and 256 pixel versions of this logo.”
- “Export this SVG as a transparent PNG, 1200 pixels wide.”
- “Arrange these photos into a two-column grid with transparent gaps.”
- “Extract the tables on pages 2–4 into a CSV I can review.”
- “Format this JSON without changing large numbers or key order.”
- “Decode this Base64 file into a new binary file.”
- “Convert this YAML configuration into JSON.”
- “Format this XML while preserving mixed text.”
- “Compare these two files and save a unified patch.”
- “Generate a QR code from the exact text in this local payload file.”
- “Make a Code 128 barcode from this local payload file.”
- “Embed this image as a CSS custom property without changing its bytes.”
- “Inspect the frame timings of this GIF without decoding its pictures.”
- “Extract GIF frames 1, 5 and 10 as composited PNGs.”
- “Trace this black-and-white logo into a single-color SVG.”
- “Average these aligned, opaque images into a new PNG.”
- “Black out the exact regions in my local JSON file and save a new PNG.”
- “Generate two six-word passphrases into a new local file without showing them.”

All input and output paths must be absolute. Existing outputs are never
overwritten. Image compression accepts an exact byte target; a result reports
whether the target was met.

| MCP tool | Required arguments | Useful options |
| --- | --- | --- |
| `abox_capabilities` | none | Lists formats, limits, and defaults. |
| `abox_image_compress` | `input_path`, `output_path`, `target_bytes` | `format`: `keep`, `auto`, `jpeg`, `png`, `webp`; `allow_resize` |
| `abox_image_resize` | `input_path`, `output_path`, `width` and/or `height` | `fit`: `contain` or `cover`; `allow_upscale`: false; `format`, `quality`, `background` |
| `abox_image_convert` | `input_path`, `output_path`, `format` | `jpeg`, `png`, or `webp`; `quality` from 0 to 1; JPEG `background` |
| `abox_pdf_split` | `input_path`, `output_dir` | `mode`: `each`, `every`, `ranges`; `pages_per_file`; `ranges`; `keep_bookmarks` |
| `abox_pdf_merge` | `input_paths`, `output_path` | 2–32 PDFs in input order; `keep_bookmarks` |
| `abox_pdf_select` | `input_path`, `output_path`, `pages` | Ordered terms such as `3,1-2,3`; `keep_bookmarks` |
| `abox_pdf_rotate` | `input_path`, `output_path`, `degrees` | Clockwise 90, 180, or 270; `pages` defaults to `all`; retains every page |
| `abox_images_to_pdf` | `input_paths`, `output_path` | One image per page; `page_size`, `orientation`, `fit`, `margin_mm`, `dpi`, `image_mode`, `quality`, `max_side`, `background` |
| `abox_exif_inspect` | `input_path` | Read-only metadata inventory; does not return private tag values |
| `abox_exif_remove` | `input_path`, `output_path` | `keep_orientation`; `keep_icc` |
| `abox_file_hash` | `input_path` | `algorithms`: MD5, SHA-1, SHA-256 (default), SHA-384, SHA-512 |
| `abox_pdf_compress` | `input_path`, `output_path` | `preset`: `smallest`, `screen`, `print`, `gentle`; optional `dpi`, `quality`, `strip_metadata` |
| `abox_pdf_watermark` | `input_path`, `output_path`, `text` | `size`, `color`, `opacity`, `diagonal`, `tiled`, `first_page_only` |
| `abox_image_to_ico` | `input_path`, `output_path` | `sizes`, `fit`: `pad`, `crop`, `stretch`; `storage`: `auto`, `png`, `bmp`; optional `background` |
| `abox_svg_to_image` | `input_path`, `output_path` | `format`: `png`, `jpeg`, `webp`; `width`, `height`, `fit`, `quality`, `background` |
| `abox_image_layout` | ordered `input_paths`, `output_path` | `layout`: `grid`, `horizontal`, `vertical`; `width`, grid `columns`, `ratio`, `gap`, `padding`, `fit`, `format`, `quality`, `background` |
| `abox_pdf_to_csv` | `input_path`, `output_path` | `pages`, `table_index`, `date_order`: `auto`, `dmy`, `mdy`; `include_headers`, `spreadsheet_safe` |
| `abox_json_format` | `input_path`, `output_path` | `minify`, `indent`: `2`, `4`, `tab`; `sort_keys` (opt-in natural sorting) |
| `abox_base64` | `input_path`, `output_path`, `mode` | `encode` or `decode`; `url_safe`; decoding `canonical` |
| `abox_image_data_uri` | `input_path`, `output_path` | `shape`: `uri`, `css-rule`, `css-var`, `html`, `markdown`; `svg_encoding`: `auto` or `base64`; optional CSS `identifier` |
| `abox_yaml_json` | `input_path`, `output_path`, `direction` | `yaml-to-json` or `json-to-yaml`; `indent`: `2` or `4`; YAML-to-JSON `sort_keys` |
| `abox_xml_format` | `input_path`, `output_path` | `minify`; `indent`: `2`, `4`, `tab` |
| `abox_qr_generate` | UTF-8 payload `input_path`, `output_path` | `format`: `svg` (default) or `png`; `level`: `L`, `M`, `Q`, `H`; `quiet`, `scale`, `foreground`, `background` |
| `abox_barcode_generate` | UTF-8 payload `input_path`, `output_path` | `symbology`: `code128`, `ean13`, `upca`, `ean8`, `itf14`, `itf`, `code39`; `format`, `scale`, `height`, `text`, `code39_check`, colors |
| `abox_text_diff` | `left_path`, `right_path`, `output_path` | `context_lines` (0–100, default 3); `ignore_whitespace`, `ignore_case`, `ignore_blank_lines` affect comparison summaries only |
| `abox_gif_inspect` | `input_path` | Header-only timing, rectangles and budgets; optional zero-based `frame_offset` and `frame_limit` (default 20) |
| `abox_gif_split` | `input_path`, new `output_dir` | `mode`: `composited` (default) or `stored`; optional unique 1-based `frames`; PNGs and local timing manifest |
| `abox_image_trace` | `input_path`, `.svg` `output_path` | Single-color shape trace; `threshold`, `invert`, `detail`, `corner_angle`, `min_area`, `fill` |
| `abox_image_stack` | ordered `input_paths`, `output_path` | `average`, `median`, `sigma`, `lighten`, `darken`, `add`; equal-size opaque frames; PNG/JPEG |
| `abox_image_redact` | `input_path`, `.png` `output_path`, `regions_path` | Local JSON with expected decoded dimensions and integer rectangles; permanent opaque black fill |
| `abox_password_generate` | `.txt` `output_path` | Optional local JSON `config_path`; passwords or EFF passphrases; secrets excluded from responses |

The six new tools' settings and JSON configuration examples are documented in
[the shared skill reference](skills/abox-local-files/references/additional-tools.md).

## Operations added in v0.9.0

These routes extend the earlier v0.8.0 operation set. Their full settings, local
JSON shapes and review requirements are in the shared skill's
[media and document reference](skills/abox-local-files/references/media-and-documents.md).
Use `capabilities` to check what your installed release exposes.

| MCP operation | CLI command | Result and important boundary |
|---|---|---|
| `abox_code_read` | `read-code-image` | One QR/barcode payload in a new local JSON report; never opens links or returns the payload |
| `abox_gif_create` | `create-gif` | Ordered still images to GIF with timing, palette and loop controls |
| `abox_pdf_protect` | `protect-pdf` | AES-256/AES-128 PDF security; exact passwords come from local files; viewer permission flags are advisory |
| `abox_pdf_unlock` | `unlock-pdf` | Supplied-password decryption to a new PDF; no password guessing |
| `abox_audio_edit` | `edit-audio` | Reverse, speed/pitch, gain or normalize an admitted PCM16/Float32 WAV |
| `abox_audio_trim` | `trim-audio` | Ordered kept ranges or cuts in WAV; configurable fades; encoded samples verified |
| `abox_video_inspect` | `inspect-video` | MP4/MOV sample tables and technical headers without decoding |
| `abox_video_trim` | `trim-video` | Copy admitted time ranges; hidden boundary packets can remain, so this is not redaction |
| `abox_video_join` | `join-videos` | Copy compatible MP4/MOV clips into a new MP4 without re-encoding |
| `abox_video_rotate` | `rotate-video` | Copy video packets with a clockwise display matrix; viewers must honor orientation |
| `abox_video_remux` | `remux-video` | Copy supported H.264/AAC MP4/MOV packets into MP4; no transcoding fallback |
| `abox_document_scan` | `scan-document` | Explicit local corner coordinates to cleaned PNG/PDF; no edge detection or OCR |
| `abox_id_photo` | `make-id-photo` | Custom rules and explicit landmarks to JPEG photo, print sheet and report; no official approval |
| `abox_business_profile` | `preview-business-profile` | Illustrative local SVG/PNG; does not access or publish a real listing |
| `abox_height_compare` | `compare-heights` | Locally configured silhouettes, names and measurements to SVG/PNG |
| `abox_receipt_extract` | `extract-receipt` | Bundled English OCR to local JSON/CSV; every suggested field needs review |
| `abox_dicom_inspect` | `inspect-dicom` | Technical headers without patient values for flat PS3.10 native/single-frame RLE files |
| `abox_dicom_render` | `render-dicom` | One technical PNG preview; burned-in identifiers remain possible |
| `abox_images_to_video` | `images-to-video` | Still images to silent H.264 MP4 with verified frames/timing |
| `abox_gif_to_mp4` | `gif-to-mp4` | One GIF cycle to silent H.264 MP4, with a solid background for transparency |
| `abox_exif_edit` | `edit-exif` | Explicit tag changes from local JSON; compressed picture and other metadata retained |
| `abox_code_format` | `format-code` | Format HTML/CSS/YAML or minify supported HTML/CSS; preserves active markup, not a sanitizer |
| `abox_xml_json` | `convert-xml-json` | Explicit lossy XML↔JSON mapping; verifies source mapping rather than semantic round-trip |
| `abox_markdown_html` | `markdown-to-html` | Small Markdown dialect to standalone passive HTML with CSP; links never opened |

In v0.9.0, audio inputs are simple mono/stereo PCM16/Float32 WAV. Version 0.10.0
expands the admitted codecs as described below. MP4 creation is limited
to 60 seconds, 1800 frames and a 2,073,600-pixel output, and needs a supported
installed browser encoder. Receipt OCR includes
its worker, WebAssembly and English data; no processing asset is downloaded.
These are operation-specific bounds, not a universal process-memory guarantee.
EXIF edits use a separate local `edits_path` with bounded `set`/`remove`
instructions; see [metadata editing](skills/abox-local-files/references/metadata-editing.md).
Editing retains the thumbnail and other metadata and does not anonymize an image.
See [additional text formatting](skills/abox-local-files/references/text-formatting.md)
for exact HTML/CSS/YAML options, XML/JSON mapping losses and the passive Markdown
dialect. Formatting existing HTML keeps its active content; it is distinct from
the Markdown renderer's escaped, restricted output.

## Operations added in v0.10.0

These additions are included in the public v0.10.0 release. Always check
the installed adapter's `capabilities` before choosing a new operation.

| MCP operation | CLI command | Result and important boundary |
|---|---|---|
| `abox_heic_convert` | `convert-heic` | Admitted HEVC still photos/grids to a new image directory; bundled offline codec and predecode coded/reference budgets |
| `abox_avif_convert` | `convert-avif` | One reduced-header AV1 still photo to JPEG/PNG/WebP; animation and unsupported geometry refused |
| `abox_pdf_redact` | `redact-pdf` | Explicit local point-coordinate masks to a fresh lossless image-only PDF; all pages flattened, no source objects copied |
| `abox_audio_extract` | `extract-audio` | Admitted sound to WAV, or exact AAC packet extraction from MP4/M4A/MOV to M4A without decoding video |
| `abox_video_compress` | `compress-video` | Re-encode admitted H.264 toward a byte target; report `fitted` honestly |
| `abox_video_crop` | `crop-video` | Exact displayed-image coordinates from local JSON to a re-encoded MP4 |
| `abox_video_frame` | `grab-video-frame` | Frame at or before the requested time to a lossless PNG; every output pixel checked |
| `abox_video_reverse` | `reverse-video` | Re-encode reversed frames; silent by default, optional bounded AAC reversal/re-encoding |
| `abox_video_timelapse` | `timelapse-video` | Faster silent MP4 with explicit frame selection, rate and size |
| `abox_video_to_gif` | `video-to-gif` | Sampled video range to a bounded palette GIF; sound omitted |
| `abox_video_rotate_bake` | `bake-video-rotation` | Apply source orientation and an additional quarter turn to re-encoded pixels; identity output display matrix |

Audio editing/trimming also accepts bounded MP3 Layer III, AAC-LC ADTS and an
ordinary unedited MP4/M4A/MOV AAC-LC track. Compressed WAV output needs a native
packet decoder; the adapter never falls back to unbounded whole-file decoding.
Check actual decoded duration because priming/padding can reduce sample counts.
See [audio codecs and extraction](skills/abox-local-files/references/audio-codecs.md).

DICOM now also admits a strict single-frame JPEG Lossless Process 14 subset,
with complete entropy admission and independent stored-sample checks. It remains
a technical preview and can retain burned-in identifiers. See
[DICOM details](skills/abox-local-files/references/media-and-documents.md#dicom).

Use exact user-provided geometry for
[PDF redaction](skills/abox-local-files/references/pdf-redaction.md); the adapter
does not find sensitive regions or erase the original. Searchable text,
signatures and interactive PDF features are lost. For image conversion, read
[HEIC/AVIF limits](skills/abox-local-files/references/heic-avif.md), including
8-bit SDR output and metadata omission. No route downloads a codec while
processing a file.

The seven new [video processing routes](skills/abox-local-files/references/video-processing.md)
admit stable progressive 8-bit 4:2:0 H.264 before native decoding; this is not
arbitrary codec support. Generated MP4 frames are decoded and checked for shape,
timing and count, while copied AAC packets are compared exactly. Lossy encoding,
color conversion and final-frame timing can change. Matrix-only video rotation
remains available separately without decoding or re-encoding.

## Operations added in v0.11.0

These controls open a separate visible browser and keep private content and
pairing secrets outside agent context. The person starts/connects and approves
capture/peers there. They require a graphical desktop and directly reachable
devices; host-candidate connections can require the same network. File operations
remain offline. These controls are included in the verified public v0.11.0
release; historical v0.10.0 receipts remain above.

| MCP operation | CLI command | Explicit role and important boundary |
|---|---|---|
| `abox_share_session` | `share-session` | `host` preloads selected local text/files; `reader` requests approval and explicitly saves into a new output directory |
| `abox_camera_session` | `camera-session` | `host` grants video-only camera permission and approves viewers; `viewer` receives live video, without recording |
| `abox_walkie_session` | `walkie-session` | Microphone-granted `host` holds Talk; `listener` receives without microphone capture |
| `abox_voice_oncall_session` | `voice-oncall-session` | `host` receives/moderates callers with an optional UI password; microphone-granted `sender` holds Talk |
| `abox_live_status` | `live-status` | Safe counts/state/expiry for this adapter process; no invitations, received text or media |
| `abox_live_stop` | `live-stop` | Close one companion and release devices/transports; unfinished saves removed and completed saves retained |

At most four windows run together. `ttl_minutes` defaults to 30 and ranges from
1 to 120. Share attachments are at most 16 files, 128 MiB each and 256 MiB
combined; text is at most 50,000 characters and 200,000 UTF-8 bytes. Peers' names
never select filesystem paths: explicit receive saves use generated `.bin` or
`.txt` names with exclusive writes. The synthetic loopback-looking address has
no actual HTTP listener or file server. See [live settings and CLI lifetime](skills/abox-local-files/references/live-sessions.md),
[Privacy](PRIVACY.md) and [Security](SECURITY.md).

For PDF protection, pass `open_password_file`/`owner_password_file`; for unlocking,
pass `password_file`. Their exact UTF-8 text, including BOM and final newline,
is used without trimming. Never put passwords or decoded code contents into a
tool request or conversation. Document scans and ID photos require dimensions
and source pixel coordinates from a local JSON file, supplied deliberately by
the user. The adapter does not infer sensitive regions or face landmarks.

## Use the CLI

The CLI provides the same operations without MCP. These commands use Node in a
source checkout. In a release bundle, replace `node` with `./runtime/node`, or
`.\runtime\node.exe` on Windows:

```sh
node bin/abox.mjs capabilities
node bin/abox.mjs doctor
node bin/abox.mjs compress-image --request-file /absolute/path/compress.json
node bin/abox.mjs resize-image --request-file /absolute/path/resize.json
node bin/abox.mjs convert-image --request-file /absolute/path/convert.json
node bin/abox.mjs split-pdf --request-file /absolute/path/split.json
node bin/abox.mjs merge-pdf --request-file /absolute/path/merge.json
node bin/abox.mjs select-pdf-pages --request-file /absolute/path/select.json
node bin/abox.mjs rotate-pdf --request-file /absolute/path/rotate.json
node bin/abox.mjs images-to-pdf --request-file /absolute/path/photos.json
node bin/abox.mjs inspect-exif --request-file /absolute/path/inspect.json
node bin/abox.mjs remove-exif --request-file /absolute/path/metadata.json
node bin/abox.mjs hash-file --request-file /absolute/path/hash.json
node bin/abox.mjs compress-pdf --request-file /absolute/path/compress-pdf.json
node bin/abox.mjs watermark-pdf --request-file /absolute/path/watermark.json
node bin/abox.mjs image-to-ico --request-file /absolute/path/icon.json
node bin/abox.mjs svg-to-image --request-file /absolute/path/svg.json
node bin/abox.mjs image-layout --request-file /absolute/path/layout.json
node bin/abox.mjs pdf-to-csv --request-file /absolute/path/tables.json
node bin/abox.mjs format-json --request-file /absolute/path/format.json
node bin/abox.mjs base64 --request-file /absolute/path/base64.json
node bin/abox.mjs image-to-data-uri --request-file /absolute/path/embedding.json
node bin/abox.mjs convert-yaml-json --request-file /absolute/path/conversion.json
node bin/abox.mjs format-xml --request-file /absolute/path/xml.json
node bin/abox.mjs generate-qr --request-file /absolute/path/qr.json
node bin/abox.mjs generate-barcode --request-file /absolute/path/barcode.json
node bin/abox.mjs diff-text --request-file /absolute/path/diff.json
node bin/abox.mjs inspect-gif --request-file /absolute/path/gif-info.json
node bin/abox.mjs split-gif --request-file /absolute/path/gif-frames.json
node bin/abox.mjs trace-image --request-file /absolute/path/trace.json
node bin/abox.mjs stack-images --request-file /absolute/path/stack.json
node bin/abox.mjs redact-image --request-file /absolute/path/redaction.json
node bin/abox.mjs generate-passwords --request-file /absolute/path/passwords.json
```

A compression request file contains:

```json
{
  "input_path": "/absolute/path/photo.jpg",
  "output_path": "/absolute/path/photo-small.jpg",
  "target_bytes": 500000,
  "format": "keep",
  "allow_resize": true
}
```

A page-range request file contains:

```json
{
  "input_path": "/absolute/path/document.pdf",
  "output_dir": "/absolute/path/document-parts",
  "mode": "ranges",
  "ranges": ["1-3", "4-6"],
  "keep_bookmarks": true
}
```

An image metadata request file contains:

```json
{
  "input_path": "/absolute/path/photo.jpg",
  "output_path": "/absolute/path/photo-clean.jpg",
  "keep_orientation": true,
  "keep_icc": true
}
```

`--request '<JSON>'` is also supported, subject to your shell's quoting rules.
Request files avoid those differences. The CLI prints JSON summaries; it never
prints file contents.

## Limits and behavior

- Image compression, resizing and conversion: JPEG, PNG, and static WebP.
  Animated images are refused. Resizing fits the full image (`contain`) or crops
  centrally (`cover`); upscaling is disabled by default. Re-encoding can change
  colors and removes source metadata. A no-op resize preserves original bytes.
- Metadata removal: JPEG, PNG, and WebP containers, including their animation.
- PDF page operations: unencrypted input, up to 5,000 pages and 1,000 output files.
  Merging accepts 2–32 PDFs, at most 128 MiB combined. Page selection preserves
  the order and repetition of comma-separated terms. Ranges expand ascending:
  `3,1-2,3` produces 3,1,2,3; use explicit terms for reverse order.
  Merging PDFs with colliding interactive form field names is currently
  unsupported by the source engine and fails before creating an output.
  Tool responses include at most 20 output entries. Larger splits also write a
  local `manifest.json` containing every output path and its source pages.
- Images to PDF: still JPEG, PNG or WebP, one image per page, up to 128 MiB
  combined and 80 megapixels per image. Defaults to A4, automatic orientation,
  contain, no margins. `keep` can embed original JPEG streams with their metadata;
  remove metadata first when a clean document is required. `lossless` preserves
  decoded image pixels; `jpeg` re-encodes using the requested quality.
- Checksums: read-only, streaming, supports empty files and up to 8 GiB.
- PDF compression: presets recompress supported images and rewrite structure.
  `smallest` uses 96 DPI / 0.55 quality, `screen` 130 / 0.68, `print` 220 / 0.82,
  and `gentle` keeps resolution with 0.90 quality. `dpi` and `quality` can override
  those settings. It does not search for a byte target; check `smaller` and actual
  savings. The output can be larger. Changed images can lose detail. CMYK and
  unsupported image encodings are retained where safely readable. Unusual
  filter-wrapped JPEG encodings and nonidentity EXIF orientation in JPEG streams
  are refused before processing to prevent unintended image rotation. Standard PDF
  metadata is removed by default; embedded images, attachments and visible
  content can still contain personal information.
- PDF watermarks: one rasterized line, up to 200 characters, centered or tiled,
  on all pages or only the first. Local fonts affect appearance. Up to 100,000
  stamps. Watermarks can be removed by editors and do not redact or protect data.
- ICO: still JPEG, PNG or WebP to one file with up to ten sizes from 16 to 256
  pixels. `auto` stores sizes up to 64 as DIB and larger sizes as PNG. Padding
  preserves aspect ratio and transparency; crop fills the square; stretch can
  distort. The directory, frame dimensions and rendered pixels are verified.
- SVG: uncompressed, self-contained static SVG to PNG, JPEG or WebP; up to
  16,384 pixels per side and 80 megapixels. Active content, foreign objects,
  external references, CSS imports/escapes and animations are refused. JPEG
  fills transparency with white by default. Fonts and colors can vary by browser.
- Image layouts: 2–32 still JPEG, PNG or WebP images, at most 128 MiB combined
  and 80 megapixels per input. Output is at most 8192 pixels per side and 32
  megapixels. Grids default to two square columns; horizontal/vertical strips
  preserve original aspect ratios. Contain retains the full image; cover crops.
  New pixels are rendered in 8-bit SDR and source metadata is not copied.
- PDF to CSV: selectable text only, no OCR. Tables, headings, dates and amounts
  are inferred and can be incomplete or wrong; review the CSV against the PDF.
  UTF-8 BOM, comma delimiter, CRLF lines. Multiple tables have a blank separator
  row. Year-bearing dates and inferred amounts are normalized; auto date order
  falls back to day-first when ambiguous. Formula-like text is escaped with an
  apostrophe by default. Up to 1000 tables, 64 columns per table, 100000 data
  rows, one million cells/glyphs and 16 MiB of output. Structural verification
  does not establish extraction accuracy.
- PDF table extraction currently accepts unfiltered and Flate streams without
  predictors. It conservatively refuses legacy LZW/RunLength, ASCII-armoured
  streams and predictors, even in unused images or xrefs. Blocked PDF names in
  printed text can also cause refusal. Stream expansion is limited to 16 MiB
  per Flate stream and 64 MiB cumulatively before buffering decoded data.
- JSON: UTF-8 input up to 8 MiB, nesting up to 256 levels, output up to 32 MiB.
  Preserves raw number and string tokens, duplicate keys and object key order.
  Sorting is opt-in. Both pretty and minified output end with a newline. The
  parser accepts at most 250000 syntax nodes, including object keys.
- Base64: arbitrary binary files, including empty files; input up to 8 MiB,
  output up to 32 MiB. Standard encoding is padded; URL-safe encoding is unpadded.
  Relaxed decoding accepts whitespace, missing padding and either alphabet.
  Canonical validation requires the exact requested spelling and zero unused
  bits. Encoded/decoded bytes are written locally and never returned to the agent.
- Image data URIs: input up to 8 MiB and output up to 32 MiB. Signature-based
  MIME recognition does not prove image validity or rendering. Original bytes,
  metadata and SVG markup are preserved; this is not a sanitizer. The five
  output shapes use `.txt` for `uri`, `.css` for `css-rule`/`css-var`, `.html`
  for `html`, and `.md` for `markdown`. Auto encoding uses readable percent
  encoding only for exact UTF-8 SVG in a standalone URI. SVG embedding envelopes
  use Base64 to avoid HTML, CSS or Markdown changing the URI's spelling.
- YAML/JSON conversion: UTF-8 input up to 2 MiB, output up to 16 MiB, 128 nesting
  levels and 100000 syntax nodes. Supports the website's YAML subset, not every
  YAML feature. Anchors, aliases, custom tags and multiple documents are refused.
  Ordered values, duplicate keys and large numeric tokens are retained;
  comments, formatting and string escape spelling can be lost. Optional natural
  key sorting applies only when converting YAML to JSON.
  Output must round-trip before it is written. The source printer cannot handle
  root multiline strings or some four-space lists of mappings; those requests
  are refused. Use the default two-space indentation for lists of mappings.
- XML formatting: the same 2 MiB input, 16 MiB output, 128 nesting levels and
  100000-node limits. UTF-8 only; DTDs and custom entities are refused, without
  fetching external resources. Predefined entities and valid numeric references
  are supported. Mixed content and `xml:space` follow the source engine's
  preservation rules; formatting may change insignificant whitespace and quotes.
- QR codes and barcodes: read payloads directly from UTF-8 files, including any
  final newline. Payloads and completed barcode digits are not returned to the
  agent. QR input is at most 4 KiB; barcode input at most 256 bytes. Actual
  encoder and verification capacity can be smaller. Retail check digits are
  computed or validated; invalid supplied digits fail. Code 39 can uppercase
  text and optionally add its checksum. SVG is the default and needs no browser;
  PNG uses the installed browser. Output is at most 8192 per side, 32 megapixels
  and 16 MiB. Barcode verification permits at most 400 alternating runs; plain
  ITF is limited to 4–40 digits. Check warnings and test the saved code with the
  intended scanner before printing or relying on it.
- Text comparison: two UTF-8 files, including empty files, at most 4 MiB and
  20000 logical lines combined; NUL-containing binary inputs are refused.
  Writes a new `.diff` or `.patch` up to 8 MiB. The patch always describes the
  original strings, including BOMs, line endings and final newline differences;
  ignore options affect `comparison_stats` only. Primary counts describe line
  content, with terminator changes reported separately. The adapter verifies
  that patch replay reconstructs the right input from the left. Header labels
  are fixed `a` and `b`. Large differences can produce coarse rewrite hunks;
  minimality is not guaranteed. Neither source is modified or patched.
- Each other input: at most 128 MiB.
- GIF inspection: 32 MiB, 1000 source frames, 8192 per side and 32 megapixels per
  screen or patch. Reads headers without verifying LZW or pixels. Frame results
  are paginated; comments, application text and palette colors are excluded.
- GIF extraction: at most 200 selected PNGs, 128 Mi decoded patch pixels and
  300 million walked screen pixels. Each PNG is at most 32 MiB and the total
  PNG output at most 256 MiB; the upstream working-buffer admission also applies.
  Strict decoding refuses partial frames. Composited mode applies preceding
  disposal; stored mode returns patches. Output pixels are checked after PNG
  encoding, and a local timing manifest lists every frame. Needs a local browser.
- Image tracing: still JPEG/PNG/WebP, at most 4096 per side and 4 megapixels.
  Single-color, lossy SVG shape approximation for logos or line art; not photo
  reconstruction. At most 100000 boundary edges, 1000 contours and 400000 SVG
  bytes. Passive path structure and rendered path pixels are checked.
- Stacking: 2–8 opaque, equal-size still JPEG/PNG/WebP frames, up to 128 MiB
  combined, 4096 per side and 4 megapixels. No alignment, resizing, focus stacking
  or RAW development. Uses encoded 8-bit SDR RGB; PNG pixels are lossless after
  stacking, JPEG is lossy. Both stacking and tracing require the local browser.
- Redaction: explicit 0-based integer rectangles in the decoded display image.
  Expected dimensions must match exactly; rectangles cannot be clipped. Up to
  100 regions, 16384 per side, 32 megapixels and 128 million rectangle pixels
  including overlaps. Solid black fill only, flattened PNG, with all decoded
  pixels checked. Covered pixels are exactly opaque black; outside alpha is
  retained and visible colors are within one 8-bit step of the decoded source.
  The new raster is 8-bit SDR and excludes source metadata. Does not locate sensitive content;
  review coverage before sharing. Requires the local browser.
- Passwords: cryptographic generation into a new plaintext `.txt`, one secret per
  line, at most 100 results and 64 KiB. Defaults to 24 characters; passphrase mode
  defaults to six EFF words. Settings come from local JSON up to 16 KiB. Secrets,
  secret hashes and samples never appear in tool results. No browser or vault.
- Compression: up to 80 megapixels and two minutes per image. `auto` may adjust
  the output extension to match the selected format. Other modes require the
  output extension to match the actual bytes, including an unchanged original.
- Compression may resize an image unless `allow_resize` is `false`. A file that
  already meets the target can pass through unchanged, retaining its metadata.
  Use metadata removal when that is part of the task.
- Metadata removal can retain animation in PNG and WebP because it edits their
  containers; compression refuses animation rather than flattening it.
- PDF splitting creates new PDFs. Document tags and metadata may be removed;
  digital signatures do not survive as valid signatures. Output page counts are
  verified. Bookmark preservation is enabled by default where supported.
- Metadata removal retains orientation and ICC profiles by default to preserve
  appearance. Set `keep_orientation` and `keep_icc` to `false` to remove those
  supported fields too; display orientation or colors may change. It does not
  establish that an image is anonymous.

Downloading a release or installing a browser uses the network. Processing files
through this adapter does not send their bytes over the network. The agent and
its host still receive paths, settings, summaries, and errors. The adapter needs
no account or API key.

See the [plugin privacy notice](PRIVACY.md) for the data handled by the adapter
and the separate responsibilities of the agent host.

The compressor detects common browser installations. Set `ABOX_BROWSER_PATH`
to an existing browser executable if needed. The browser's sandbox must work on
the host OS; Linux detection prefers installed stable Chrome over generic
Chromium builds. The plugin does not download a browser during processing.

## This plugin and the website's development MCP

This plugin runs file operations locally over MCP stdio. The separate website
catalogue at [mcp-dev.abox.tools/mcp](https://mcp-dev.abox.tools/mcp) exposes
`find_browser_tools`: it accepts a public search query, locale, and limit, then
returns tool links and an interactive catalogue. It accepts no files or filenames
and does not process files. Its source is the website's
[development catalogue worker](https://github.com/A-Box-of-Tools/website/tree/dev/workers/catalogue-mcp).

The `mcp-dev` endpoint is for development. This repository's release workflow
does not deploy the website or publish a production catalogue endpoint.
For directory submissions and MCP registration, see [Publishing](docs/publishing.md).
For Gemini CLI, Vercel skills.sh, Cursor and other distribution options, see
[Platform support and publishing](docs/platforms.md).
For additional directories, local distribution and their account or licensing
requirements, see [Other sharing platforms](docs/distribution-options.md).

## Developer setup and other MCP hosts

Use the release bundle for installation without development tools. To develop
from a source checkout, install Node.js 22.15 or later, then run:

```sh
npm ci --ignore-scripts
npm test
npm run test:browser
npm run doctor
```

Source setup downloads npm dependencies. The source checkout's `mcp.json` uses
Node from the host; release packaging replaces it with the bundled executable.
A developer can add this repository marketplace with
`codex plugin marketplace add A-Box-of-Tools/abox-tools-plugin`, then install it
in the desktop app and run Setup in the installed copy. See the
[official OpenAI packaging guide](https://developers.openai.com/plugins/build/plugins).

For another host supporting local MCP stdio, point its configuration at the
extracted bundle's executable and server script using absolute paths:

```json
{
  "mcpServers": {
    "abox": {
      "command": "/absolute/path/to/bundle/runtime/node",
      "args": ["/absolute/path/to/bundle/bin/abox-mcp.mjs"]
    }
  }
}
```

On Windows, use `runtime/node.exe`. Escape backslashes in JSON or use forward
slashes. A source checkout can use `node` instead of the bundled executable.
Follow the host's own configuration format; do not replace unrelated settings.

## Maintain the reused code

To refresh the pinned website sources from a local website checkout:

```sh
npm run sync-upstream -- --source /absolute/path/to/etoolbox
```

Review the vendor diff and provenance, retain license notices, and run the checks
above. A `v*` tag starts `.github/workflows/release.yml`: it tests, builds all four
platform bundles, builds a universal MCPB, and checks extracted MCP execution on
all four platforms before publishing the GitHub Release. A successful tagged
release then publishes its verified metadata to the Official MCP Registry using
GitHub's short-lived identity token. Claude and OpenAI directory reviews remain
separate submissions; see [Publishing](docs/publishing.md).