contentdm-mcp 0.1.0__tar.gz

contentdm_mcp-0.1.0/.env.example

@@ -0,0 +1,34 @@
+# Copy to .env to change a default. Nothing here is required: CONTENTdm's web
+# services need no key and no account.
+#
+# The server reads .env from the directory it is started in -- the
+# repository root, when launched with `uv --directory /path/to/contentdm-mcp`.
+# Variables already set in the environment take precedence.
+
+# Optional: an email address or URL added to the User-Agent, so an
+# institution can reach you if your use ever causes it trouble.
+# CONTENTDM_CONTACT=you@example.org
+
+# Optional: directory for the on-disk response cache.
+# CONTENTDM_CACHE_DIR=~/.cache/contentdm-mcp
+
+# Optional: HTTP timeout in seconds for one request (default 30; image
+# downloads get 120 to read).
+# CONTENTDM_TIMEOUT=30
+
+# Optional: least seconds between two requests to one site (default 1, never
+# below 0.5).
+# CONTENTDM_MIN_INTERVAL=1
+
+# Optional: more CONTENTdm sites a tool may reach. Without this, a tool reaches
+# the curated sites and any address under contentdm.oclc.org, and nothing
+# else. Either https base URLs separated by commas, or the absolute path of a
+# YAML file whose entries are shaped like instances.yaml's (only base_url is
+# required). A model cannot add to this list; only you can.
+# CONTENTDM_EXTRA_INSTANCES=https://digital.example.edu
+# CONTENTDM_EXTRA_INSTANCES=/Users/you/contentdm-sites.yaml
+
+# Optional: an existing folder that every get_image destination must lie
+# inside. get_image never writes under ~/Library otherwise; set this to save
+# into an iCloud Drive folder, which lives there.
+# CONTENTDM_DOWNLOAD_DIR="~/Library/Mobile Documents/com~apple~CloudDocs/Genealogy"

contentdm_mcp-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Settings. .env holds local overrides; .env.example is the committed template.
+.env
+.env.*
+!.env.example
+.envrc
+
+# Response cache
+.cache/
+
+# Downloaded page images are never part of this repository. The one
+# recorded test image is the exception.
+*.jpg
+!tests/fixtures/*.jpg
+*.jpeg
+*.png
+*.tif
+*.tiff
+*.pdf
+ 
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store

contentdm_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/). The tool surface is the public
+interface: renaming or removing a tool or a parameter is a major release, and
+adding one is a minor release. Before 1.0, a minor release may do either.
+Changes to `instances.yaml` alone (a site added, moved or re-checked) are
+patch releases.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-10-06
+
+First release.
+
+### Added
+
+- Eight tools over classic CONTENTdm's `dmwebservices` API and IIIF image
+  service: `list_instances`, `list_collections`, `get_collection`, `search`,
+  `get_item`, `get_pages`, `get_image` (writes one new file, never
+  overwrites) and `cache_status`.
+- A host policy for arguments a model writes: a tool reaches the curated
+  sites, any address under `contentdm.oclc.org` (where every classic site
+  answers as `cdmNNNNN`), and sites the operator lists in
+  `CONTENTDM_EXTRA_INSTANCES`. Any other host is refused before it is looked
+  up, with a message naming both ways forward.
+- Every connection checked where it is made: a name that leads to a private,
+  loopback, link-local, CGNAT, multicast, reserved or unspecified address,
+  IPv4 or IPv6, is refused, and the connection goes to the address checked,
+  so redirects and DNS rebinding are covered. JSON answers are capped at
+  10 MB and images at 60 MB as they stream.
+- `get_image` saves only a real image of the format its `.jpg` or `.jpeg`
+  name says, never a hidden file or one under `~/Library`, and only inside
+  `CONTENTDM_DOWNLOAD_DIR` when that is set.
+- A curated `instances.yaml` of 18 state archive, state library and
+  university sites holding state or county records, each verified live on
+  2026-10-06, and 7 entries for institutions that have left CONTENTdm
+  (North Carolina to Quartex, Pennsylvania's POWER Library to Islandora,
+  South Dakota and Idaho to Preservica, Montana to Recollect, Wisconsin and
+  Arizona to their own sites).
+- An adapter layer between the tools and the API, so the new CONTENTdm or
+  Quartex can be added without changing the tools.
+- `search` across several sites side by side, reporting which answered,
+  failed, timed out or were not searched; `page_hits` for the page inside a
+  volume where a text match is.
+- Every result carries the item's public address and a citation core
+  (institution, collection, title, identifier, address); `get_item` adds the
+  institution's own "cite as" line and rights statement where it has them.
+- A polite client: one request at a time per site at least a second apart,
+  identical calls joined, answers cached (collection lists and fields 30
+  days, items 7, searches 1), one retry on 429 and 5xx.

contentdm_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+Issues and pull requests are welcome. This file says how the project is put
+together and what a change is expected to carry.
+
+## Setting up
+
+```bash
+git clone https://github.com/ianderso/contentdm-mcp
+cd contentdm-mcp
+uv sync --extra dev
+```
+
+Before sending a change, run what CI runs:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+The suite is mocked with [respx](https://lundberg.github.io/respx/) against
+recorded CONTENTdm responses. It must never touch a live site: each one is an
+institution's own server, and CI should not depend on any of them being up.
+
+## Where things live
+
+| Path | What it holds |
+| --- | --- |
+| `src/contentdm_mcp/server.py` | The tools. Their docstrings and `Field` descriptions *are* the published tool descriptions and schema. |
+| `src/contentdm_mcp/adapters/base.py` | The interface every platform adapter provides, and the records it returns. |
+| `src/contentdm_mcp/adapters/classic.py` | Classic CONTENTdm: the `dmwebservices` calls, IIIF, and item addresses. |
+| `src/contentdm_mcp/client.py` | The cached, paced HTTP client, the host allowlist, the redirect rule, the public-address check made at connect time, and the size caps. |
+| `src/contentdm_mcp/instances.py` | Loading the curated list and the operator's, and the host policy an address given as an instance must pass. |
+| `src/contentdm_mcp/instances.yaml` | The curated list itself. |
+| `src/contentdm_mcp/shape.py` | Turning records into results: kinds, labels, the citation core. |
+| `src/contentdm_mcp/config.py` | Settings from the environment and `.env`. |
+| `docs/API-NOTES.md` | What the API was observed to do, and when. |
+| `docs/DESIGN.md` | Why the server is shaped the way it is, and what is out of scope by decision. |
+| `tests/fixtures/` | Recorded responses and the tool-schema snapshot. |
+| `tests/test_tool_contract.py` | Tests over the tool surface as a client sees it. |
+| `tests/test_security.py` | Every refusal against a steered model: hosts, addresses, sizes, files. |
+| `tests/live_check.py` | The one script that talks to live sites, run by hand. Not collected. |
+
+## What a change carries
+
+**A test that fails without it.** Bug fixes especially: reproduce the bug as a
+test first.
+
+**Descriptions written for the model.** A tool's docstring is what a model
+reads when choosing and calling it. The combined descriptions have a ceiling
+(`DESCRIPTION_BUDGET` in `tests/test_tool_contract.py`), because they are sent
+on every session. Raise it deliberately, in a pull request of its own. They
+are dedented at import, so the budget measures the same text on every Python.
+
+**The evidence distinction, kept.** A transcript, OCR text or index entry is a
+lead to the page image, never the record. Tools that return text say so; a
+contract test enforces it.
+
+**A citation core on every item.** Any result that names an item carries its
+public address and the institution, collection, title and identifier.
+
+**A structured result, never an exception.** Every tool catches its failures
+and returns an `error` envelope. A sweep test calls every tool with every site
+failing and fails if one raises.
+
+**Nothing that writes to a site, and nothing that works around a bot check.**
+See [docs/DESIGN.md](docs/DESIGN.md#out-of-scope-by-decision).
+
+**Nothing that widens what an argument can reach.** Treat every argument as
+written by someone else's text. A new kind of host goes through the policy in
+`instances.resolve`, a new place to write through `server._destination`, and
+each comes with a test in `tests/test_security.py` showing that the refusals
+still come before the harm. See
+[docs/DESIGN.md](docs/DESIGN.md#which-hosts-a-tool-reaches).
+
+**A new fixture recorded, not invented,** when a change depends on how a site
+answers, with what was observed and when added to `docs/API-NOTES.md`. Keep
+fixtures to historical records.
+
+**The snapshot, when the surface changes.** Renaming or adding a tool or a
+parameter fails the snapshot test on purpose. Regenerate it with
+`uv run python -m tests.regen_tool_snapshot`, update the README tables, and add
+a `CHANGELOG.md` entry.
+
+## Adding a site to the curated list
+
+1. Call `{base}/digital/bl/dmwebservices/index.php?q=dmGetCollectionList/json`
+   yourself. Record the number of collections and the day.
+2. Prefer state archives, state libraries and statewide networks. Add a
+   university or public library only when it holds state or county records,
+   and say which collections in `holds`.
+3. Read a few items' rights fields and put what they say about reuse in
+   `terms`.
+4. Check the public host with Python (`uv run python -c "import httpx;
+   httpx.get('https://host/')"`). If its certificate chain is incomplete, add
+   the site's `cdmNNNNN.contentdm.oclc.org` address as `api_base`: the number
+   is in the `path` of every collection in the list.
+5. Run `uv run python -m tests.live_check`: it calls every entry.
+
+A site that has left CONTENTdm stays in the list with `status: moved` and a
+`moved_to`, so a search can say where it went.
+
+## Adding a platform
+
+Write an adapter in `src/contentdm_mcp/adapters/` that implements
+`adapters.base.Adapter`, register it in `ADAPTERS`, record its answers as
+fixtures, and change the affected entries' `platform`. The tools should not
+need to change; if they do, say why in the pull request.
+
+## Releasing
+
+A maintainer bumps `__version__` in `src/contentdm_mcp/__init__.py` and
+both versions in `server.json`, moves the changelog's Unreleased entries under
+the new version, and publishes a GitHub release tagged `v<version>`. The
+release workflow builds the tag, publishes to PyPI by Trusted Publishing, and
+lists the version in the MCP Registry.

contentdm_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contentdm_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.5
+Name: contentdm-mcp
+Version: 0.1.0
+Summary: MCP server for the record images and transcripts that US state archives and state libraries publish on OCLC's CONTENTdm: search one instance or a curated list of them, read an item and its pages, and download a page image. For genealogy and history.
+Project-URL: Homepage, https://github.com/ianderso/contentdm-mcp
+Project-URL: Repository, https://github.com/ianderso/contentdm-mcp
+Project-URL: Issues, https://github.com/ianderso/contentdm-mcp/issues
+Project-URL: Changelog, https://github.com/ianderso/contentdm-mcp/blob/main/CHANGELOG.md
+Author: Ian Anderson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: archives,contentdm,digital-collections,family-history,genealogy,iiif,mcp,research,state-archives
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Sociology :: Genealogy
+Classifier: Topic :: Sociology :: History
+Requires-Python: >=3.11
+Requires-Dist: httpcore>=1.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# contentdm-mcp
+
+[![CI](https://github.com/ianderso/contentdm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ianderso/contentdm-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/contentdm-mcp)](https://pypi.org/project/contentdm-mcp/)
+
+<!-- mcp-name: io.github.ianderso/contentdm-mcp -->
+
+An [MCP](https://modelcontextprotocol.io) server for the **record images
+that US state archives and state libraries publish on CONTENTdm**: death
+certificates and their annual indexes, Confederate pension files, voter
+registers, prison registers, county court and estate papers, letters and
+diaries, with whatever transcript or OCR text the institution added.
+
+[CONTENTdm](https://www.oclc.org/en/contentdm.html) is OCLC's hosted
+digital-collections platform. The Alabama Department of Archives and History,
+the Georgia Archives' Virtual Vault, the Tennessee State Library and Archives,
+Ohio Memory, the Illinois Digital Archives, the Indiana State Library,
+Missouri Digital Heritage and many more run on it, and every one of them
+answers the same keyless JSON API and IIIF image service. The server ships a
+curated list of those sites, searches one or several of them at once, reads
+an item and its pages, and downloads a page image to read.
+
+It works the way a careful genealogist does. **The page image is the
+evidence.** A transcript or OCR text is a lead that says which page to read,
+and an index card is a finding aid to the record behind it. Every result
+carries the holding institution's item address and a citation core
+(institution, collection, title, identifier, address), because the item page
+is what gets cited, not this server.
+
+Nothing here writes anywhere, and nothing here keeps a family tree. It sits
+well beside [dpla-catalog-mcp](https://github.com/ianderso/dpla-catalog-mcp),
+which finds an item across hundreds of collections and hands you the
+institution's address (`get_item` takes that address directly), and
+[nara-catalog-mcp](https://github.com/ianderso/nara-catalog-mcp) for federal
+records.
+
+This is an independent project. It is not affiliated with, endorsed by, or
+supported by OCLC or any of the institutions whose sites it reads.
+
+## Tools
+
+The server publishes eight tools. All but `get_image` are read-only;
+`get_image` writes one new file and never overwrites one.
+
+**Finding**
+
+| Tool | Purpose |
+| --- | --- |
+| `list_instances` | The curated sites: who runs each, what it holds for a genealogist, any reuse terms, and the day it was checked. Sites that have left CONTENTdm are listed with where they went. Makes no request. |
+| `list_collections` | A site's collections and the alias each is searched by. |
+| `get_collection` | One collection's fields: what `search` can name in `field`, and which field holds the transcript or OCR text. |
+| `search` | Search one site, or several side by side. Says which sites answered, failed or timed out, so a negative is bounded. `page_hits` returns the page inside a volume where a text match sits. |
+
+**Reading**
+
+| Tool | Purpose |
+| --- | --- |
+| `get_item` | One item: metadata, transcript or OCR text, the institution's own "cite as" line and rights statement, and the citation core. For a page, which object and page number it is. Takes an item address, such as DPLA's `isShownAt`, on a site it may reach. |
+| `get_pages` | A compound object's pages in order, with `query` to mark the pages that match. |
+| `get_image` | Download one page image through the site's IIIF service, sized to fit, including any page of a multi-page PDF. Saves a new `.jpg`, never a hidden file or one under `~/Library`. |
+| `cache_status` | This session's requests, by site, and cache use. Makes no request. |
+
+## The curated sites
+
+`list_instances` gives the whole list. On 2026-10-06, 18 sites answered, and 7
+entries record institutions that have left CONTENTdm, so a search can say
+where they went:
+
+| State | Site | Status |
+| --- | --- | --- |
+| AL | Alabama Department of Archives and History | supported |
+| AK | Alaska's Digital Archives | supported |
+| AR | Arkansas State Archives | supported |
+| CT | Connecticut State Library | supported |
+| DE | Delaware Division of Libraries, with the Delaware Public Archives | supported |
+| GA | Georgia Archives, Virtual Vault | supported |
+| IL | Illinois Digital Archives | supported |
+| IN | Indiana State Library (Indiana Memory); Ball State University | supported |
+| KY | Kentucky Digital Library | supported |
+| MO | Missouri Digital Heritage | supported |
+| ND | Digital Horizons | supported |
+| NM | New Mexico Digital Collections, with the State Records Center and Archives | supported |
+| NV | Nevada State Library, Archives and Public Records | supported |
+| OH | Ohio Memory | supported |
+| OK | Oklahoma Department of Libraries, with the Oklahoma State Archives | supported |
+| TN | Tennessee State Library and Archives (TeVA) | supported |
+| WA | Washington Rural Heritage | supported |
+| AZ | Arizona Memory Project | left CONTENTdm; behind a bot check |
+| ID, SD | State archives' digital collections | moved to Preservica |
+| MT | Montana Memory Project | moved to Recollect |
+| NC | State Archives of North Carolina | moved to Quartex |
+| PA | POWER Library | moved to Islandora |
+| WI | Wisconsin Historical Society | moved to its own site |
+
+Any other CONTENTdm site works too, at its `cdmNNNNN.contentdm.oclc.org`
+address: pass `https://cdmNNNNN.contentdm.oclc.org` as `instance`. Every
+classic site answers there, whatever its own domain, and the source of its
+pages names the number (`"cdmServerUrl": "serverNNNNN.contentdm.oclc.org"`).
+There are more than 675 of them, and no registry. To use a site by its own
+domain, add it to `CONTENTDM_EXTRA_INSTANCES`; a tool argument cannot, for the
+reason under [Security](#security).
+
+## Setup
+
+You need Python 3.11 or later and [uv](https://docs.astral.sh/uv/). There is
+no key to request.
+
+**Without cloning.** `uvx` fetches it from PyPI and runs it in one step:
+
+```bash
+uvx contentdm-mcp
+```
+
+**From a clone**, which is what you want if you will change it:
+
+```bash
+git clone https://github.com/ianderso/contentdm-mcp
+cd contentdm-mcp
+uv sync
+uv run contentdm-mcp   # stdio server, usually launched by the client
+```
+
+Either way the server speaks MCP over stdio, so you will normally let an MCP
+client start it rather than run it by hand.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "contentdm": {
+      "command": "uvx",
+      "args": ["contentdm-mcp"]
+    }
+  }
+}
+```
+
+A desktop app does not always inherit your shell's `PATH`. If the server fails
+to start because `uvx` cannot be found, give the full path that `which uvx`
+prints as the `command`.
+
+### Claude Code
+
+```bash
+claude mcp add contentdm -- uvx contentdm-mcp
+```
+
+## Configuration
+
+Nothing is required. A `.env` file in the directory the server starts in
+supplies anything the environment does not; only that directory is read.
+
+| Variable | Meaning |
+| --- | --- |
+| `CONTENTDM_CACHE_DIR` | Response cache directory. Default `~/.cache/contentdm-mcp`. |
+| `CONTENTDM_TIMEOUT` | HTTP timeout in seconds for one request. Default 30. Image downloads get 120 to read. |
+| `CONTENTDM_MIN_INTERVAL` | Least seconds between two requests to one site. Default 1, and never below 0.5. |
+| `CONTENTDM_CONTACT` | An email address or URL added to the User-Agent, so an institution can reach you if your use causes trouble. Optional, and courteous. |
+| `CONTENTDM_EXTRA_INSTANCES` | More sites a tool may reach by their own domain: https base URLs separated by commas, or the absolute path of a YAML file whose entries are shaped like [`instances.yaml`](src/contentdm_mcp/instances.yaml)'s (only `base_url` is required). `list_instances` lists them; a search of every site leaves them out. |
+| `CONTENTDM_DOWNLOAD_DIR` | An existing folder. When set, `get_image` saves only inside it. Set it to save into an iCloud Drive folder, which lives under `~/Library`. |
+
+An unusable value is reported on the first tool call as a `not_configured`
+result naming the variable.
+
+## Being a good guest
+
+Each site is one institution's server. The client sends one request at a time
+to each site, at least a second apart; a search across several sites runs
+them side by side, six at a time, so no site sees more than one caller. Two
+identical calls in flight share one request. Collection lists and field
+definitions are cached for 30 days, items for 7, searches for a day. A 429, a
+5xx or a dropped connection gets one retry, honouring `Retry-After`. The
+User-Agent names the package, its version and this repository.
+
+`robots.txt` on these sites disallows the website's search pages, not the
+API this server uses. Each institution's own terms govern what you do with
+its images: `list_instances` and `get_item` pass on what the sites say, and
+several ask for permission before publication.
+
+## How to read what comes back
+
+- **A search is only as wide as `answered`.** `failed`, `timed_out` and
+  `not_searched` list the sites a negative does not cover. A site that
+  redirects, asks for a bot check or lists no collections has usually moved.
+- **Search covers metadata and text fields, never the image.** Many record
+  images have no text at all, so a name can be on a page that no search finds.
+  Browse by collection, or by the index volume, instead.
+- **A compound object's text is on its pages.** Volumes, files and newspaper
+  issues are compound objects; their own transcript field is usually empty.
+  Use `page_hits=true`, or `get_pages` with a `query`, to find the page.
+- **Field names are per collection.** "Name of Father" is `namea` in one
+  collection and `father` in another. `get_collection` says which nick holds
+  what, and which field is the transcript: that is marked by type, because
+  the name differs from site to site.
+- **"Transcript" can be machine OCR.** The Tennessee vital-records indexes
+  carry OCR under that label. Read the image.
+- **`exact` is a phrase search** (the words together, in order), not
+  whole-field equality. `all` needs every word, `any` one of them.
+- **A PDF item can hold many pages.** Its IIIF image shows the first;
+  `get_image` with `pdf_page` reaches the others.
+- **`page` is a position in the object,** counted from 1, not the number
+  printed on the scan: the entry for Sgt. Alvin C. York is on page 461 of
+  volume 8 of Tennessee's 1960-1964 death index, a scan named `54784_460` and
+  stamped 457. Cite the printed number too when it differs.
+- **Cite the item page.** Use the `citation` each result carries, and the
+  institution's own `cite_as` line where `get_item` finds one (Georgia,
+  Oklahoma and Alaska items have them). Record the identifier
+  (`alias:pointer`) so the item can be found again.
+
+## Deliberately not here
+
+- **Writing to any site.** CONTENTdm's write functions need a staff login.
+- **Sites on other platforms.** The new CONTENTdm (launched 2026-09-22) has
+  no published public API, and Quartex's is undocumented. The tools speak to
+  an adapter layer, so either can be added without changing them; see
+  [docs/DESIGN.md](docs/DESIGN.md).
+- **Working around bot checks.** A site that answers with a challenge is
+  reported as blocked and left alone.
+
+## Security
+
+Tool arguments are written by a model, and the model reads text this server
+does not control: titles, transcripts, DPLA records, web pages. The server
+assumes that text can steer the model, and limits what a steered model can
+make it do.
+
+- **Which hosts.** A tool reaches the curated sites, any address under
+  `contentdm.oclc.org` (OCLC's own servers), and the sites you list in
+  `CONTENTDM_EXTRA_INSTANCES`. Any other host is refused before it is even
+  looked up, because a DNS query for `secret.attacker.example` would already
+  deliver the name; the refusal says how to reach the site instead.
+- **Which addresses.** Each connection is checked where it is made: a name
+  that leads to a private, loopback, link-local, CGNAT, multicast, reserved or
+  unspecified address, IPv4 or IPv6, is refused, and the connection goes to
+  the address that was checked. Redirects are followed only between an
+  instance's own hosts, and are checked again. Proxy settings in the
+  environment are not used.
+- **How much.** A JSON answer over 10 MB, or an image over 60 MB, is refused
+  as it streams in.
+- **Which files.** `get_image` creates one new file and never overwrites one.
+  The bytes must be an image, judged by their first bytes rather than the
+  Content-Type, and of the format the file's suffix names: `.jpg` or `.jpeg`.
+  Never a hidden file or folder, never under `~/Library`, and with
+  `CONTENTDM_DOWNLOAD_DIR` set, never outside it, all judged after links are
+  resolved. A refused download leaves nothing on disk.
+- **Arguments are validated** (collection aliases, field nicks, numeric
+  pointers) before they reach a request, and search words are stripped of the
+  API's own syntax characters.
+- **Site text is untrusted.** Titles, descriptions and transcripts reach the
+  model verbatim. The server's instructions tell the model to treat that text
+  as material to weigh, never as instructions; the model still decides, so
+  review what it proposes to do.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest                      # mocked with respx; never touches a site
+uv run ruff check .
+uv run ruff format --check .
+uv run python -m tests.live_check  # paced calls to the live sites
+```
+
+The live check asks the sites what the recorded fixtures cannot: whether
+their answers still have the shape the server reads, and whether every
+curated site still answers. See [CONTRIBUTING.md](CONTRIBUTING.md) for how the
+suite is organised, [docs/API-NOTES.md](docs/API-NOTES.md) for what was
+observed of the API and when, and [docs/DESIGN.md](docs/DESIGN.md) for why the
+server is shaped this way.
+
+## Credits
+
+The images and descriptions belong to the institutions that publish them.
+CONTENTdm is a product of [OCLC](https://www.oclc.org).
+
+## License
+
+[MIT](LICENSE).