apud-mcp exposes an IIIF-grounded MCP server for inspecting manifests and working with citable manuscript regions.
List a IIIF manifest’s canvases (id, label, size) with pagination via describe_manifest.
Fetch a canvas-coordinate region at the best resolution allowed, returning the image plus crop-to-canvas mapping via view_region.
Record a region transcription as a W3C annotation with a citable link, optionally with a language, via annotate_transcription.
Support IIIF-grounded, citable vision workflows over historical documents by agents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@apud-mcp read the marginal note on canvas 10 of this manifest and annotate it with coordinates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
IIIF-grounded, citable vision for historical documents.
Vision-language models can read manuscripts, but they cannot say where they read what they
report, and their answers cannot be checked by a scholar. apud sits between IIIF collections
and models:
fetches canvas regions from any IIIF Image API server at the best resolution the server and the model allow (Image API v2/v3, Presentation v2/v3, lenient parsing of real-world manifests), including Level 0 static servers, where the region is stitched from the covering tiles (or cut from the closest declared size) on the client;
keeps every model output anchored to canvas coordinates, even when the served image size differs from the canvas;
emits W3C Web Annotations (xywh fragment selectors) and IIIF Content State links, so
every transcription can be opened at the exact spot in Mirador or any IIIF viewer.
apud (Latin, "in the work of") is how philologists cite a source they read in someone else's text.
Status: pre-alpha.
Package | Path | What it is |
| Python library: IIIF parsing, region requests, annotations, citations | |
| MCP server exposing |
The benchmark lives in a separate repository: apud-bench.
Related MCP server: agent-vision-mcp
from apud.client import IIIFClient
from apud.iiif import Region, canvas_to_image
with IIIFClient() as iiif:
manifest = iiif.manifest("https://www.e-codices.unifr.ch/metadata/iiif/csg-0390/manifest.json")
canvas = manifest.canvases[10]
service = iiif.image_service(canvas.image_service)
region = canvas_to_image(Region(200, 300, 800, 400), service.width, service.height, canvas)
request, jpeg = iiif.region(service, region, max_side=1568)uvx apud-mcpTools: describe_manifest, view_region, annotate_transcription.
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .Apache-2.0. See CITATION.cff for how to cite.
Record a transcription of a canvas region as a W3C annotation with a citable link.
| Name | Required | Description | Default |
|---|---|---|---|
| h | Yes | ||
| w | Yes | ||
| x | Yes | ||
| y | Yes | ||
| text | Yes | ||
| language | No | ||
| canvas_id | Yes | ||
| manifest_url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden for what is clearly a write/create operation. It does not state whether the annotation persists, who can see it, whether it requires authentication, whether repeated calls duplicate annotations, or what the citable link looks like at call time. An output schema exists, which reduces the need to describe returns, but the mutation semantics remain undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the action, the input, and the resulting artifact are all in the first clause. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-required-parameter write tool with 0% schema description coverage and no annotations, one sentence is insufficient. An agent cannot tell what coordinate system x/y/w/h use, what format the manifest_url must take, or what the side effects of recording an annotation are; the existing output schema covers only the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and all 8 properties are bare titles, with x/y/w/h being single letters and nothing indicating coordinate space, units, or that they describe a bounding box. The phrase "canvas region" weakly implies the x/y/w/h geometry and "transcription" implies text, but manifest_url, canvas_id, and the optional language parameter get no clarification at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb ("Record") with a specific resource ("a transcription of a canvas region") and names the output artifact (a W3C annotation with a citable link). It is unambiguous what the tool produces. It does not reference the sibling tools, but the write/annotate nature distinguishes it implicitly from read-only describe_manifest and view_region.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus describe_manifest or view_region, nor any preconditions such as needing a manifest_url or a canvas_id discovered elsewhere. The only implicit hint is that a "canvas region" must exist, which an agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the canvases of a IIIF manifest (id, label, size), paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| manifest_url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden. It mentions pagination, but the limit/offset parameters already imply that; it says nothing about fetching a remote URL (network access, latency, possible SSRF concerns), what happens with an invalid or unsupported IIIF manifest, or whether access is authenticated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler: verb, resource, returned fields, and pagination in one clause. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values, but with 0% parameter coverage and no annotations, the description should explain the required manifest_url semantics and pagination contract. For a remote-fetch tool with an unconstrained string parameter, this is too thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across three parameters, so nothing documents manifest_url, limit, or offset. The description's only hint is the word 'paginated', which does not explain the required manifest URL format (IIIF v2 vs v3), default/max limit values, or offset semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb plus resource plus scope: 'List the canvases of a IIIF manifest', with the returned fields (id, label, size) named. An agent can tell this apart from view_region and annotate_transcription, though the description never explicitly contrasts them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this versus the siblings, no prerequisite about needing a valid IIIF manifest URL, and no guidance on paging through results. 'Paginated' hints at iteration but gives no instruction on how to proceed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a canvas region (canvas coordinates) at the best resolution the server allows.
Returns the image and the mapping from crop pixels back to canvas coordinates.
| Name | Required | Description | Default |
|---|---|---|---|
| h | Yes | ||
| w | Yes | ||
| x | Yes | ||
| y | Yes | ||
| max_side | No | ||
| canvas_id | Yes | ||
| manifest_url | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add real behavioral value: the server picks the best available resolution, and the response includes a crop-pixel-to-canvas-coordinate mapping. It omits safety profile (implicitly a read, but unstated), any auth/access constraints, how max_side interacts with the server-side resolution cap, and failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed by return-value information. Nothing is wasted, though it is under-specified rather than maximally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so explaining the return shape is optional, but the tool has 7 parameters at 0% schema coverage and zero annotations. The description should at minimum explain max_side's effect and where manifest_url/canvas_id come from; that gap makes it incomplete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 7 parameters. The description clarifies that x/y/w/h are canvas coordinates, which is genuinely useful, but says nothing about manifest_url, canvas_id, or max_side (default 1568) — the parameter that most affects output size. It does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a canvas region') with the coordinate space made explicit (canvas coordinates) and the resolution policy noted. It does not differentiate from the sibling describe_manifest, which is presumably the manifest/canvas-discovery step an agent needs first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to call this versus describe_manifest, and no prerequisites are given — despite manifest_url and canvas_id almost certainly coming from a prior manifest inspection. Only the implicit hint that this tool handles resolution selection itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0annotate_transcriptiondescribe_manifestview_regionScored across 3 tools
The three tools occupy clearly separate steps of a single workflow: enumerate structure (describe_manifest), retrieve imagery (view_region), and persist a transcription (annotate_transcription). There is no resource or action overlap that could cause misselection.
All three names follow a consistent verb_noun snake_case pattern (describe_, view_, annotate_) with noun phrases that match the IIIF vocabulary used in the descriptions. No mixed conventions or vague verbs.
Three tools is on the lean side, but each maps to a distinct, necessary step of the manifest-inspect-annotate loop and nothing feels redundant. A small number of additional read/query helpers would round it out, but the scope is deliberate rather than padded.
The read path (manifest structure + region imagery with coordinate mapping) is solid, but the annotation side is a dead end: there is no tool to list, retrieve, update, or delete existing annotations, so an agent can write transcriptions but never verify or re-read them. Manifest-level metadata and search are also absent.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Access Pollinations models and API capabilities through agent tools.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Generate images, GIFs, videos, and PDFs from HTML, URLs, or templates — from your AI agent.
