Tools

Eight tools, designed around one flow: resolve → browse → fetch → release.

resolve

resolve(url, offset=0, limit=25)

Resolves a viewer URL to its IIIF manifest and opens an extraction (a temporary working session, TTL 2 hours). Returns the extraction_id used by every other tool, manifest metadata (title, IIIF version, canvas count), a crop_hint if the URL carried an xywh region fragment, and the first page of canvases.

If the URL is a hub page (exhibition, search results) rather than a viewer, the error lists the resolvable viewer links found on the page.

list_canvases

list_canvases(extraction_id, offset=0, limit=50, query=None)

Pages through the canvas list. query filters by label substring — folio numbers ("f. 12"), page names, plate numbers. Responses follow the paging contract returned / totalCanvases / hasMore; walk with offset rather than asking for everything.

get_canvas_image

get_canvas_image(extraction_id, canvas_index, region="full", size=None, delivery="inline")

Fetches one page image from the library’s IIIF Image API into temporary storage and delivers it:

Parameter	Values	Notes
region	full, crop_hint, "x,y,w,h"	crops server-side via the IIIF region parameter
size	IIIF size, or unset	unset picks a safe default (some repositories only serve advertised sizes)
delivery	inline, url	see below
enhance	gray, stretch, clahe, clahe_red	optional legibility filter (see get_canvas_tiles)

inline embeds the image in the response, downscaled to ≤1568px on the long edge — works in every client, including sandboxed apps. Oversized results are refused with a suggestion to use a region or url.

url returns a signed link to the full-resolution file plus dimensions and byte size. Links expire after ~30 minutes; re-request rather than caching them.

Repeat requests for the same canvas/region/size reuse the already-downloaded file.

When an inline image comes back well below native resolution, the response says so (scale_of_native) and points at get_canvas_tiles.

get_canvas_tiles

get_canvas_tiles(extraction_id, canvas_index, region="full", tile_px=1024,
                 overlap=64, offset=0, limit=4, delivery="inline")

The reading tool. Vision models accept ~1.15 megapixels per image — anything larger is silently downscaled before the model sees it, which is why a whole folio delivered inline is often below legibility for dense script. This tool splits the canvas (or a region) into a grid of ~1024×1024 tiles at 1:1 native scale, returned in reading order (left→right, top→bottom) with pixel coordinates:

• Each tile is an IIIF region request, so only the tile’s pixels cross the wire. Servers that refuse region requests fall back to one cached full download cropped server-side.
• The response always carries the full tile map (grid shape + every tile’s x,y,w,h), so an agent can plan a page, request specific tiles, and stitch its transcription.
• Inline returns at most 4 tiles per call — page with offset. delivery="url" returns up to 10 signed URLs per call.
• region narrows the grid to one column, paragraph, or the crop_hint from the source URL.
• tile_px (256–1072; default 1024) and overlap (default 64px, so line fragments at tile edges appear in both neighbours) are tunable per manuscript. The upper bound is deliberate: square tiles above ~1072px exceed the vision-input budget and get silently downscaled — bigger tiles would lose resolution, which is the opposite of the point.
• enhance applies a server-side legibility filter to each tile (a derived copy — originals are untouched): gray (luminance), stretch (2–98% contrast stretch), clahe (adaptive histogram equalisation), or clahe_red — CLAHE on the red channel, where brown iron-gall ink is darkest against parchment; usually the best choice for faded sixteenth-century hands.

A ~3500×5000 folio is 24 tiles ≈ 6 inline calls for a full-page transcription at true native resolution.

get_page_range

get_page_range(extraction_id, start_index, end_index, region="full", size=None)

Fetches a run of up to 10 canvases and returns signed URLs for each (inline is not offered for batches — it would flood the context). Failed canvases are reported per-index, not fatally.

release

release(extraction_id)

Deletes the extraction’s downloaded images from the server and closes it. Call it when the job is done — it is the polite end of the flow. Forgotten extractions are cleaned up by TTL.

The transcribe_folio prompt

Besides tools, the server ships one MCP prompt template: transcribe_folio(url, folio, notes?). In clients that surface server prompts (Claude Desktop’s + menu, and others), it expands to the full guided workflow — resolve, locate the canvas, read at native resolution via tiles, diplomatic transcription with [?]/[...] uncertainty marking and an explicit ban on reconstructing gaps from expected content, enhancement retries on weak passages, and release. The same discipline is in the server instructions, so plain “transcribe folio x” requests get most of it automatically; the prompt makes it one click.

search / fetch

search(query)    fetch(id)

The ChatGPT-connector compatibility pair: search looks through your recent extractions by title or source URL; fetch returns one extraction’s summary. To work on a new document, use resolve — these two only cover ground already resolved.