How it works

iiiftools sits between a digital library’s IIIF infrastructure and your AI assistant. The whole interaction is four steps, driven by the assistant through MCP tools.

1. Resolve

You paste a viewer URL into the chat — for example:

https://viewer.library.wales/4397453#?xywh=0,-1512,3249,5098
https://digital.nls.uk/armorials/archive/251681527
http://hdl.handle.net/10107/4388829

The assistant calls resolve(url). iiiftools matches the URL against its repository rules, constructs the IIIF manifest URL, fetches and validates it, and opens an extraction — a temporary working session for that document. The reply includes the document’s title, canvas (page) count, and the first page of the canvas list.

Two niceties happen automatically:

• A #?xywh=… fragment in the URL (the region you were looking at in the viewer) is kept as a crop hint, so the assistant can zoom straight to the shield, initial, or marginal note you meant.
• If the URL is a hub page (an exhibition or search page) rather than a viewer, resolve fails helpfully: it lists the resolvable viewer links found on that page so the assistant can pick one.

2. Browse

Manuscripts routinely run to hundreds of leaves, so canvas lists are paged. The assistant uses list_canvases with an offset/limit, and can filter by label — "f. 12", a page number, a folio range — to find the right leaf without scrolling through everything.

3. Fetch pages

get_canvas_image downloads one page image from the library’s IIIF Image API into iiiftools’ temporary store, then delivers it one of two ways:

• inline — the image is embedded in the tool response (downscaled to ≤1568px). Best for “look at this page and read it”.
• url — a short-lived signed link to the full-resolution file. Best for batches, for clients that can fetch URLs, and for full-detail work. Links expire after ~30 minutes.

Regions crop server-side (region="crop_hint" or "x,y,w,h"), so the assistant can pull a high-detail crop of one initial instead of a whole downscaled folio. get_page_range fetches up to 10 pages at once as signed URLs.

For transcription, tiles — not downscaled pages. Vision models take ~1.15 megapixels per image, so a full folio inline lands well below native resolution — fine for layout, too small for dense secretary hand. get_canvas_tiles splits the page into ~1024px tiles at 1:1 native scale in reading order, four per call, with pixel coordinates for stitching. That is the intended way to read a page line by line; the inline full page even tells you when it’s too coarse (scale_of_native).

4. Release

When the job is done, the assistant calls release(extraction_id) and the downloaded images are deleted from the server. If it forgets, the extraction expires on a TTL (2 hours) and a background sweeper deletes the files anyway. See Storage, privacy & limits.

What iiiftools does not do

No transcription, no HTR, no image analysis happens on the server. The model you connected is the thing doing the reading — iiiftools just gets the pages in front of it.