apud-mcp 0.0.1__tar.gz

apud_mcp-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store

apud_mcp-0.0.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: apud-mcp
+Version: 0.0.1
+Summary: MCP server exposing apud: IIIF-grounded, citable vision for historical documents
+Author: cadeos
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: apud
+Requires-Dist: mcp>=2.3
+Description-Content-Type: text/markdown
+
+# apud-mcp
+
+MCP server for [apud](https://github.com/cadeos/apud). Lets an agent list IIIF canvases, view
+regions at full detail, and record transcriptions as W3C annotations anchored to canvas
+coordinates, with a IIIF Content State link for each citation.
+
+```bash
+uvx apud-mcp
+```

apud_mcp-0.0.1/README.md

@@ -0,0 +1,9 @@
+# apud-mcp
+
+MCP server for [apud](https://github.com/cadeos/apud). Lets an agent list IIIF canvases, view
+regions at full detail, and record transcriptions as W3C annotations anchored to canvas
+coordinates, with a IIIF Content State link for each citation.
+
+```bash
+uvx apud-mcp
+```

apud_mcp-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "apud-mcp"
+version = "0.0.1"
+description = "MCP server exposing apud: IIIF-grounded, citable vision for historical documents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "cadeos" }]
+dependencies = ["apud", "mcp>=2.3"]
+
+[project.scripts]
+apud-mcp = "apud_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apud_mcp"]
+
+[tool.uv.sources]
+apud = { workspace = true }

apud_mcp-0.0.1/src/apud_mcp/server.py

@@ -0,0 +1,125 @@
+"""MCP server: lets an agent look at IIIF canvas regions and emit citable, anchored transcriptions.
+
+All coordinates exchanged with the model are canvas coordinates, so annotations and citations
+stay valid even when the served image size differs from the canvas size.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.mcpserver import Image, MCPServer
+
+from apud.annotations import encode_content_state, transcription_annotation
+from apud.client import IIIFClient
+from apud.iiif import Canvas, Region, canvas_to_image
+
+# Keeps a JPEG crop comfortably under typical MCP client result limits (~1 MB).
+DEFAULT_MAX_SIDE = 1568
+
+server = MCPServer(
+    name="apud",
+    instructions=(
+        "Work on IIIF manuscripts with verifiable citations. Use describe_manifest to list "
+        "canvases, view_region to look at a canvas area at full detail, and "
+        "annotate_transcription to record what you read, anchored to canvas coordinates."
+    ),
+)
+
+
+def _find_canvas(manifest_url: str, canvas_id: str, client: IIIFClient) -> tuple[str, Canvas]:
+    manifest = client.manifest(manifest_url)
+    for canvas in manifest.canvases:
+        if canvas.id == canvas_id:
+            return manifest.id, canvas
+    raise ValueError(f"canvas {canvas_id} not found in {manifest_url}")
+
+
+@server.tool()
+def describe_manifest(manifest_url: str, offset: int = 0, limit: int = 50) -> dict[str, Any]:
+    """List the canvases of a IIIF manifest (id, label, size), paginated."""
+    with IIIFClient() as client:
+        manifest = client.manifest(manifest_url)
+    canvases = manifest.canvases[offset : offset + limit]
+    return {
+        "manifest": manifest.id,
+        "label": manifest.label,
+        "total_canvases": len(manifest.canvases),
+        "canvases": [
+            {"id": c.id, "label": c.label, "width": c.width, "height": c.height} for c in canvases
+        ],
+    }
+
+
+@server.tool()
+def view_region(
+    manifest_url: str,
+    canvas_id: str,
+    x: int,
+    y: int,
+    w: int,
+    h: int,
+    max_side: int = DEFAULT_MAX_SIDE,
+) -> list[Any]:
+    """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.
+    """
+    with IIIFClient() as client:
+        _, canvas = _find_canvas(manifest_url, canvas_id, client)
+        if canvas.image_service is None:
+            raise ValueError("canvas has no IIIF image service")
+        service = client.image_service(canvas.image_service)
+        image_region = canvas_to_image(Region(x, y, w, h), service.width, service.height, canvas)
+        request, data = client.region(service, image_region, max_side)
+    canvas_per_crop_px = (canvas.width / service.width) / request.scale
+    return [
+        Image(data=data, format="jpeg"),
+        {
+            "canvas_region": {"x": x, "y": y, "w": w, "h": h},
+            "crop_size": {"width": request.width, "height": request.height},
+            "to_canvas": (
+                f"canvas_x = {x} + crop_x * {canvas_per_crop_px:.4f}; "
+                f"canvas_y = {y} + crop_y * {canvas_per_crop_px:.4f}"
+            ),
+            "source_url": request.url,
+        },
+    ]
+
+
+@server.tool()
+def annotate_transcription(
+    manifest_url: str,
+    canvas_id: str,
+    x: int,
+    y: int,
+    w: int,
+    h: int,
+    text: str,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """Record a transcription of a canvas region as a W3C annotation with a citable link."""
+    with IIIFClient() as client:
+        manifest_id, canvas = _find_canvas(manifest_url, canvas_id, client)
+    region = Region(x, y, w, h).clamp(canvas.width, canvas.height)
+    annotation = transcription_annotation(
+        annotation_id=f"{canvas.id}/apud/{region.xywh}",
+        canvas_id=canvas.id,
+        manifest_id=manifest_id,
+        region=region,
+        text=text,
+        language=language,
+        generator="apud-mcp",
+    )
+    return {
+        "annotation": annotation,
+        "content_state": encode_content_state(canvas.id, manifest_id, region),
+    }
+
+
+def main() -> None:
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

apud_mcp-0.0.1/tests/conftest.py

@@ -0,0 +1,4 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parents[2] / "core" / "tests"))

apud_mcp-0.0.1/tests/test_server.py

@@ -0,0 +1,49 @@
+import httpx
+import pytest
+
+from apud.client import IIIFClient
+from samples import V3_INFO, V3_MANIFEST
+
+MANIFEST_URL = "https://iiif.example.org/manifest.json"
+CANVAS = "https://iiif.example.org/canvas/1"
+
+
+@pytest.fixture
+def server(monkeypatch):
+    def handler(request: httpx.Request) -> httpx.Response:
+        url = str(request.url)
+        if url == MANIFEST_URL:
+            return httpx.Response(200, json=V3_MANIFEST)
+        if url.endswith("info.json"):
+            return httpx.Response(200, json=V3_INFO)
+        if url.endswith("default.jpg"):
+            return httpx.Response(200, content=b"\xff\xd8fakejpeg")
+        return httpx.Response(404)
+
+    import apud_mcp.server as module
+
+    monkeypatch.setattr(
+        module,
+        "IIIFClient",
+        lambda: IIIFClient(client=httpx.Client(transport=httpx.MockTransport(handler))),
+    )
+    return module
+
+
+def test_describe_manifest(server):
+    result = server.describe_manifest(MANIFEST_URL)
+    assert result["total_canvases"] == 1
+    assert result["canvases"][0]["id"] == CANVAS
+
+
+def test_view_region_maps_canvas_to_image(server):
+    image, meta = server.view_region(MANIFEST_URL, CANVAS, 100, 100, 500, 250, max_side=500)
+    # canvas 2000x3000 -> image 4000x6000, so the image region is doubled and then halved to fit
+    assert meta["source_url"].endswith("/200,200,1000,500/500,250/0/default.jpg")
+    assert meta["to_canvas"] == "canvas_x = 100 + crop_x * 1.0000; canvas_y = 100 + crop_y * 1.0000"
+
+
+def test_annotate_transcription(server):
+    result = server.annotate_transcription(MANIFEST_URL, CANVAS, 10, 20, 300, 40, "Nel mezzo", "it")
+    assert result["annotation"]["target"]["selector"]["value"] == "xywh=10,20,300,40"
+    assert result["content_state"]