mcp-libraryofcongress 2.1.2 → 3.0.0

package/dist/index.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import process2 from "process";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// src/config.ts
+import process from "process";
+
 // src/version.ts
-var PKG_VERSION = "2.1.2";
+var PKG_VERSION = "3.0.0";
 var REPO_URL = "https://github.com/smeet666/mcp-libraryofcongress";
 
 // src/config.ts
@@ -20,7 +24,9 @@ var DEFAULT_USER_AGENT = `mcp-libraryofcongress/${PKG_VERSION} (+${REPO_URL})`;
 function createLogger(level) {
   const rank = LOG_LEVELS.indexOf(level);
   const write = (at, message) => {
-    if (rank === 0 || LOG_LEVELS.indexOf(at) > rank) return;
+    if (rank === 0 || LOG_LEVELS.indexOf(at) > rank) {
+      return;
+    }
     process.stderr.write(`[mcp-libraryofcongress] ${at}: ${message}
 `);
   };
@@ -35,9 +41,11 @@ function createLogger(level) {
 }
 function readInteger(env, name, fallback, min, max) {
   const raw = env[name];
-  if (raw === void 0 || raw.trim() === "") return fallback;
+  if (raw === void 0 || raw.trim() === "") {
+    return fallback;
+  }
   const value = Number(raw);
-  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+  if (!(Number.isFinite(value) && Number.isInteger(value))) {
     process.stderr.write(
       `[mcp-libraryofcongress] error: ${name}="${raw}" is not a whole number; using ${fallback}.
 `
@@ -96,7 +104,7 @@ var LocError = class extends Error {
   code;
   details;
   constructor(code, message, details = {}) {
-    super(message);
+    super(message, details.cause === void 0 ? void 0 : { cause: details.cause });
     this.name = "LocError";
     this.code = code;
     this.details = details;
@@ -126,7 +134,9 @@ var Cache = class {
   entries = /* @__PURE__ */ new Map();
   get(key) {
     const entry = this.entries.get(key);
-    if (!entry) return void 0;
+    if (!entry) {
+      return void 0;
+    }
     if (entry.expiresAt <= Date.now()) {
       this.entries.delete(key);
       return void 0;
@@ -136,12 +146,16 @@ var Cache = class {
     return entry.value;
   }
   set(key, value) {
-    if (this.ttlMs <= 0) return;
+    if (this.ttlMs <= 0) {
+      return;
+    }
     this.entries.delete(key);
     this.entries.set(key, { value, expiresAt: Date.now() + this.ttlMs });
     while (this.entries.size > this.maxEntries) {
       const oldest = this.entries.keys().next();
-      if (oldest.done) break;
+      if (oldest.done) {
+        break;
+      }
       this.entries.delete(oldest.value);
     }
   }
@@ -151,28 +165,118 @@ var Cache = class {
 };
 
 // src/loc/http.ts
+var ZERO_MAX_AGE = /^(?:max-age|s-maxage)\s*=\s*0$/;
 var RETRYABLE = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
 var PUSH_BACK = /* @__PURE__ */ new Set([429, 503]);
 var LONGEST_WAIT_MS = 3e4;
 var RETRIES_AFTER_SILENCE = 1;
 function parseRetryAfter(value, now = Date.now()) {
-  if (!value) return null;
+  if (!value) {
+    return null;
+  }
   const trimmed = value.trim();
   const seconds = Number(trimmed);
-  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1e3);
+  }
   const at = Date.parse(trimmed);
-  if (Number.isNaN(at)) return null;
+  if (Number.isNaN(at)) {
+    return null;
+  }
   return Math.max(0, at - now);
 }
 function backoffMs(attempt) {
   const base2 = Math.min(16e3, 1e3 * 2 ** attempt);
   return base2 + Math.floor(Math.random() * 500);
 }
+function readFailure(error, attempts) {
+  const { url, attempt, maxRetries, timeoutMs } = attempts;
+  if (error instanceof Error && error.name === "LocError") {
+    throw error;
+  }
+  if (error instanceof Error && error.name === "AbortError") {
+    if (attempt >= Math.min(maxRetries, RETRIES_AFTER_SILENCE)) {
+      throw timeout(
+        `No answer from the Library of Congress within ${timeoutMs}ms. The newspaper corpus in particular can take tens of seconds.`,
+        { url }
+      );
+    }
+    return error;
+  }
+  const failure = error instanceof Error ? error : new Error(String(error));
+  if (attempt >= maxRetries) {
+    throw networkError(`Could not reach the Library of Congress: ${failure.message}`, { url });
+  }
+  return failure;
+}
+async function readRefusal(response, url, attempt, maxRetries) {
+  if (PUSH_BACK.has(response.status)) {
+    await response.body?.cancel().catch(() => void 0);
+    const asked = parseRetryAfter(response.headers.get("retry-after"));
+    if (asked !== null && asked > LONGEST_WAIT_MS) {
+      return {
+        kind: "refused",
+        pushBack: true,
+        error: rateLimited(
+          `The Library of Congress asked this client to wait ${Math.round(asked / 1e3)} seconds (HTTP ${response.status}).`,
+          { url, status: response.status }
+        )
+      };
+    }
+    if (attempt >= maxRetries) {
+      return {
+        kind: "refused",
+        pushBack: true,
+        error: rateLimited(
+          `The Library of Congress asked this client to slow down (HTTP ${response.status}).`,
+          { url, status: response.status }
+        )
+      };
+    }
+    return { kind: "again", pushBack: true, waitMs: asked ?? backoffMs(attempt) };
+  }
+  if (RETRYABLE.has(response.status) && attempt < maxRetries) {
+    await response.body?.cancel().catch(() => void 0);
+    return { kind: "again", pushBack: false, waitMs: backoffMs(attempt) };
+  }
+  if (response.status === 400 || response.status === 422) {
+    return {
+      kind: "refused",
+      pushBack: false,
+      error: invalidInput(
+        "The Library of Congress would not accept this request.",
+        "Check the query. A quotation mark or bracket left unbalanced is read as syntax."
+      )
+    };
+  }
+  if (response.status === 404 || response.status === 410) {
+    return {
+      kind: "refused",
+      pushBack: false,
+      error: notFound("The Library of Congress holds nothing at this address.", {
+        url,
+        status: response.status
+      })
+    };
+  }
+  return {
+    kind: "refused",
+    pushBack: false,
+    error: networkError(`The Library of Congress answered HTTP ${response.status}.`, {
+      url,
+      status: response.status
+    })
+  };
+}
 function statesASettledAnswer(cacheControl) {
-  if (cacheControl === null) return true;
+  if (cacheControl === null) {
+    return true;
+  }
   const directives = cacheControl.toLowerCase().split(",").map((directive) => directive.trim());
-  if (directives.includes("no-cache") || directives.includes("no-store")) return false;
-  return !directives.some((directive) => /^(?:max-age|s-maxage)\s*=\s*0$/.test(directive));
+  if (directives.includes("no-cache") || directives.includes("no-store")) {
+    return false;
+  }
+  return !directives.some((directive) => ZERO_MAX_AGE.test(directive));
 }
 async function fetchText(options) {
   const { url, userAgent, timeoutMs, maxRetries, limiter, logger } = options;
@@ -182,7 +286,8 @@ async function fetchText(options) {
   for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
     if (askedWaitMs > 0) {
       logger.debug(`waiting ${askedWaitMs}ms, as asked`);
-      await new Promise((resolve) => setTimeout(resolve, askedWaitMs));
+      const asked = askedWaitMs;
+      await new Promise((resolve) => setTimeout(resolve, asked));
       askedWaitMs = 0;
     }
     await limiter.beforeRequest();
@@ -200,70 +305,19 @@ async function fetchText(options) {
         const settled = statesASettledAnswer(response.headers.get("cache-control"));
         return { payload: await response.text(), settled };
       }
-      if (PUSH_BACK.has(response.status)) {
+      const verdict = await readRefusal(response, url, attempt, maxRetries);
+      if (verdict.pushBack) {
         limiter.pushBack();
-        await response.body?.cancel().catch(() => void 0);
-        const asked = parseRetryAfter(response.headers.get("retry-after"));
-        if (asked !== null && asked > LONGEST_WAIT_MS) {
-          throw rateLimited(
-            `The Library of Congress asked this client to wait ${Math.round(asked / 1e3)} seconds (HTTP ${response.status}).`,
-            { url, status: response.status }
-          );
-        }
-        if (attempt >= maxRetries) {
-          throw rateLimited(
-            `The Library of Congress asked this client to slow down (HTTP ${response.status}).`,
-            { url, status: response.status }
-          );
-        }
-        askedWaitMs = asked ?? backoffMs(attempt);
-        lastError = new Error(`HTTP ${response.status}`);
-        continue;
-      }
-      if (RETRYABLE.has(response.status) && attempt < maxRetries) {
-        await response.body?.cancel().catch(() => void 0);
-        lastError = new Error(`HTTP ${response.status}`);
-        askedWaitMs = backoffMs(attempt);
-        continue;
-      }
-      if (response.status === 400 || response.status === 422) {
-        throw invalidInput(
-          "The Library of Congress would not accept this request.",
-          "Check the query. A quotation mark or bracket left unbalanced is read as syntax."
-        );
       }
-      if (response.status === 404 || response.status === 410) {
-        throw notFound("The Library of Congress holds nothing at this address.", {
-          url,
-          status: response.status
-        });
+      if (verdict.kind === "refused") {
+        throw verdict.error;
       }
-      throw networkError(`The Library of Congress answered HTTP ${response.status}.`, {
-        url,
-        status: response.status
-      });
+      askedWaitMs = verdict.waitMs;
+      lastError = new Error(`HTTP ${response.status}`);
     } catch (error) {
       clearTimeout(deadline);
-      if (error instanceof Error && error.name === "LocError") throw error;
-      if (error instanceof Error && error.name === "AbortError") {
-        lastError = error;
-        if (attempt >= Math.min(maxRetries, RETRIES_AFTER_SILENCE)) {
-          throw timeout(
-            `No answer from the Library of Congress within ${timeoutMs}ms. The newspaper corpus in particular can take tens of seconds.`,
-            { url }
-          );
-        }
-        askedWaitMs = backoffMs(attempt);
-        continue;
-      }
-      lastError = error instanceof Error ? error : new Error(String(error));
-      if (attempt >= maxRetries) {
-        throw networkError(`Could not reach the Library of Congress: ${lastError.message}`, {
-          url
-        });
-      }
+      lastError = readFailure(error, { url, attempt, maxRetries, timeoutMs });
       askedWaitMs = backoffMs(attempt);
-      continue;
     } finally {
       clearTimeout(deadline);
     }
@@ -277,9 +331,10 @@ async function fetchJson(options) {
   const { payload, settled } = await fetchText(options);
   try {
     return { payload: JSON.parse(payload), settled };
-  } catch {
+  } catch (cause) {
     throw parseFailure("The Library of Congress answered with something that is not JSON.", {
-      url: options.url
+      url: options.url,
+      cause
     });
   }
 }
@@ -309,7 +364,9 @@ function routesNamedBy(formats) {
   const named = /* @__PURE__ */ new Set();
   for (const format of formats) {
     const route = COLLECTION_FORMAT_ROUTE[format.trim().toLowerCase()];
-    if (route) named.add(route);
+    if (route) {
+      named.add(route);
+    }
   }
   return FORMAT_ROUTES.filter((route) => named.has(route));
 }
@@ -407,6 +464,7 @@ var MOST_SUBJECTS = 12;
 var itemUrl = (identifier) => `${HOST}${ITEM_ROUTE}${identifier.split("/").map(encodeURIComponent).join("/")}/`;
 
 // src/loc/urls.ts
+var DOTS_ONLY = /^\.+$/;
 var YEAR_BOUND = { earliest: 1e3, latest: 9999 };
 var CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
 function base(path) {
@@ -429,10 +487,16 @@ function catalogueUrl(q) {
     url.searchParams.set(PARAM.dates, `${from}/${to}`);
   }
   const facets = facetString(q.facets ?? {});
-  if (facets !== "") url.searchParams.set(PARAM.facets, facets);
+  if (facets !== "") {
+    url.searchParams.set(PARAM.facets, facets);
+  }
   const sort = q.sort ? SORT[q.sort] : "";
-  if (sort !== "") url.searchParams.set(PARAM.sort, sort);
-  if (!q.onlineOnly) url.searchParams.set(PARAM.all, "true");
+  if (sort !== "") {
+    url.searchParams.set(PARAM.sort, sort);
+  }
+  if (!q.onlineOnly) {
+    url.searchParams.set(PARAM.all, "true");
+  }
   return url.toString();
 }
 function newspaperPagesUrl(query, limit, page, filters = {}) {
@@ -446,7 +510,9 @@ function newspaperPagesUrl(query, limit, page, filters = {}) {
     url.searchParams.set(PARAM.dates, `${from}/${to}`);
   }
   const facets = facetString(filters.facets ?? {});
-  if (facets !== "") url.searchParams.set(PARAM.facets, facets);
+  if (facets !== "") {
+    url.searchParams.set(PARAM.facets, facets);
+  }
   return url.toString();
 }
 function collectionsUrl(limit, page) {
@@ -463,7 +529,7 @@ function itemDocumentUrl(identifier) {
     );
   }
   const segments = identifier.trim().replace(/^\/+|\/+$/g, "").split("/").filter((segment) => segment !== "");
-  if (segments.some((segment) => /^\.+$/.test(segment))) {
+  if (segments.some((segment) => DOTS_ONLY.test(segment))) {
     throw invalidInput(
       `"${identifier}" is not an identifier: it carries a relative path segment.`,
       "Take the identifier from a search result rather than building one."
@@ -475,9 +541,13 @@ function itemDocumentUrl(identifier) {
   return url.toString();
 }
 function segmentsOf(address) {
-  if (!address) return null;
+  if (!address) {
+    return null;
+  }
   const trimmed = address.trim();
-  if (trimmed === "") return null;
+  if (trimmed === "") {
+    return null;
+  }
   const absolute = trimmed.startsWith("//") ? `https:${trimmed}` : trimmed;
   let parsed;
   try {
@@ -486,14 +556,20 @@ function segmentsOf(address) {
     return null;
   }
   const path = parsed.pathname.replace(/^\/+|\/+$/g, "");
-  if (path === "") return null;
+  if (path === "") {
+    return null;
+  }
   return { host: parsed.hostname, segments: path.split("/") };
 }
 function identifierFrom(address) {
   const parsed = segmentsOf(address);
-  if (!parsed) return null;
+  if (!parsed) {
+    return null;
+  }
   const { host, segments } = parsed;
-  if (host === "lccn.loc.gov") return segments[0] ?? null;
+  if (host === "lccn.loc.gov") {
+    return segments[0] ?? null;
+  }
   const first = segments[0];
   if (first === "item" || first === "resource") {
     const rest = segments.slice(1);
@@ -503,16 +579,24 @@ function identifierFrom(address) {
 }
 function collectionSlugFrom(address) {
   const parsed = segmentsOf(address);
-  if (!parsed) return null;
+  if (!parsed) {
+    return null;
+  }
   return parsed.segments[0] === "collections" ? parsed.segments[1] ?? null : null;
 }
 
 // src/loc/parse.ts
+var DIGITS_ONLY = /^\d+$/;
+var FOUR_DIGITS = /(\d{4})/;
+var WORD_SEPARATORS = /[^\p{L}\p{N}'-]+/u;
 var asObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 function asStrings(value) {
-  if (typeof value === "string") return value.trim() === "" ? [] : [value];
-  if (Array.isArray(value))
+  if (typeof value === "string") {
+    return value.trim() === "" ? [] : [value];
+  }
+  if (Array.isArray(value)) {
     return value.filter((v) => typeof v === "string" && v.trim() !== "");
+  }
   return [];
 }
 var asString = (value) => asStrings(value)[0] ?? null;
@@ -521,36 +605,52 @@ function asLabels(value) {
   const labels = [];
   for (const entry of entries) {
     if (typeof entry === "string") {
-      if (entry.trim() !== "") labels.push(entry);
+      if (entry.trim() !== "") {
+        labels.push(entry);
+      }
       continue;
     }
     const object = asObject(entry);
-    if (!object) continue;
+    if (!object) {
+      continue;
+    }
     const titled = asString(object.title);
     if (titled !== null) {
       labels.push(titled);
       continue;
     }
     for (const key of Object.keys(object)) {
-      if (key.trim() !== "") labels.push(key);
+      if (key.trim() !== "") {
+        labels.push(key);
+      }
     }
   }
   return labels;
 }
 function asNumber(value) {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
   if (typeof value === "string" && value.trim() !== "") {
     const n = Number(value);
-    if (Number.isFinite(n)) return n;
+    if (Number.isFinite(n)) {
+      return n;
+    }
+  }
+  if (Array.isArray(value)) {
+    return asNumber(value[0]);
   }
-  if (Array.isArray(value)) return asNumber(value[0]);
   return null;
 }
 function asPageNumber(value) {
   const text = asString(value);
-  if (text === null) return null;
+  if (text === null) {
+    return null;
+  }
   const digits = text.trim();
-  if (!/^\d+$/.test(digits)) return null;
+  if (!DIGITS_ONLY.test(digits)) {
+    return null;
+  }
   const n = Number(digits);
   return Number.isFinite(n) && n > 0 ? n : null;
 }
@@ -559,8 +659,10 @@ function asYear(value) {
   const plausible = (year) => Number.isFinite(year) && year >= PLAUSIBLE_YEAR.first && year <= PLAUSIBLE_YEAR.last ? Math.trunc(year) : null;
   const text = asString(value);
   if (text !== null) {
-    const m = /(\d{4})/.exec(text);
-    if (m) return plausible(Number(m[1]));
+    const m = FOUR_DIGITS.exec(text);
+    if (m) {
+      return plausible(Number(m[1]));
+    }
   }
   const direct = asNumber(value);
   return direct === null ? null : plausible(direct);
@@ -607,10 +709,14 @@ function monthsNamed(text, filedYear) {
   for (const match of text.matchAll(MONTH_BESIDE_A_NUMBER)) {
     const word = (match[2] ?? match[3] ?? "").toLowerCase();
     const month = MONTH_NUMBER[word];
-    if (month !== void 0) months.add(month);
+    if (month !== void 0) {
+      months.add(month);
+    }
   }
   for (const match of text.matchAll(YEAR_AND_TWO_DIGITS)) {
-    if (match[1] === filedYear) months.add(Number(match[2]));
+    if (match[1] === filedYear) {
+      months.add(Number(match[2]));
+    }
   }
   for (const match of text.matchAll(SLASHED_DATE)) {
     months.add(Number(match[1]));
@@ -633,22 +739,32 @@ function rangeOpenings(text) {
 }
 function statedDate(item) {
   const words = asStrings(item[ITEM_FIELD.createdPublished]).map(plainText).filter((line) => line !== "");
-  if (words.length > 0) return words.join("; ");
+  if (words.length > 0) {
+    return words.join("; ");
+  }
   const spans = asLabels(item[ITEM_FIELD.dateSpans]);
   return spans.length > 0 ? spans.join("; ") : null;
 }
 function datePublished(filed, stated) {
-  if (filed === null) return null;
+  if (filed === null) {
+    return null;
+  }
   const trimmed = filed.trim();
-  if (trimmed === "" || isCataloguingCode(trimmed)) return null;
+  if (trimmed === "" || isCataloguingCode(trimmed)) {
+    return null;
+  }
   const filled = FILED_TO_THE_DAY.exec(trimmed) ?? FILED_TO_THE_MONTH.exec(trimmed);
-  if (filled === null || stated === null) return trimmed;
+  if (filled === null || stated === null) {
+    return trimmed;
+  }
   const year = filled[1];
   const month = Number(filled[2]);
   return monthsNamed(stated, year).has(month) ? trimmed : year;
 }
 function dateCode(filed) {
-  if (filed === null) return null;
+  if (filed === null) {
+    return null;
+  }
   const trimmed = filed.trim();
   return isCataloguingCode(trimmed) ? trimmed : null;
 }
@@ -685,7 +801,7 @@ function toPaging(payload, url, settled = true) {
 }
 function rowsOf(payload, url) {
   const root = asObject(payload);
-  if (!root || !Array.isArray(root.results)) {
+  if (!(root && Array.isArray(root.results))) {
     throw parseFailure("The answer carried its rows in a shape this server cannot read.", { url });
   }
   return root.results.map(asObject).filter((r) => r !== null);
@@ -695,9 +811,15 @@ function sourceUrlOf(row, identifier) {
   const raw = asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]);
   if (raw) {
     const trimmed = raw.trim();
-    if (trimmed.startsWith("//")) return `https:${trimmed}`;
-    if (trimmed.startsWith("http://")) return `https://${trimmed.slice("http://".length)}`;
-    if (trimmed.startsWith("https://")) return trimmed;
+    if (trimmed.startsWith("//")) {
+      return `https:${trimmed}`;
+    }
+    if (trimmed.startsWith("http://")) {
+      return `https://${trimmed.slice("http://".length)}`;
+    }
+    if (trimmed.startsWith("https://")) {
+      return trimmed;
+    }
   }
   return identifier === null ? "" : itemUrl(identifier);
 }
@@ -739,7 +861,9 @@ function toSearchResults(payload, url, onSkip, settled = true) {
       sourceUrl: source
     });
   }
-  if (skipped > 0) onSkip(skipped);
+  if (skipped > 0) {
+    onSkip(skipped);
+  }
   if (rows.length > 0 && records.length === 0) {
     throw parseFailure(`${rows.length} rows came back and none could be read.`, { url });
   }
@@ -773,12 +897,16 @@ function queryTerms(query) {
   const phrases = query.match(/"([^"]+)"/g) ?? [];
   for (const phrase of phrases) {
     const inner = phrase.slice(1, -1).trim().toLowerCase();
-    if (inner !== "") terms.push(inner);
+    if (inner !== "") {
+      terms.push(inner);
+    }
   }
   const rest = query.replace(/"[^"]*"/g, " ");
-  for (const word of rest.split(/[^\p{L}\p{N}'-]+/u)) {
+  for (const word of rest.split(WORD_SEPARATORS)) {
     const lower = word.trim().toLowerCase();
-    if (lower.length < 3 || JOINING_WORDS.has(lower)) continue;
+    if (lower.length < 3 || JOINING_WORDS.has(lower)) {
+      continue;
+    }
     terms.push(lower);
   }
   return [...new Set(terms)];
@@ -792,21 +920,27 @@ function toWordBoundary(text, index, direction) {
   const limit = direction === -1 ? 0 : text.length;
   let at = index;
   for (let step = 0; step < 30 && at !== limit; step += 1) {
-    if (text[at] === " ") return at;
+    if (text[at] === " ") {
+      return at;
+    }
     at += direction;
   }
   return index;
 }
 function excerptsFor(text, terms, budget) {
   const clean = text.replace(/\s+/g, " ").trim();
-  if (clean === "") return { passages: [], located: false };
+  if (clean === "") {
+    return { passages: [], located: false };
+  }
   const found = [];
   for (const term of terms) {
     const pattern = wholeWord(term);
     let match = pattern.exec(clean);
     while (match !== null) {
       found.push({ at: match.index, length: match[0].length });
-      if (match[0].length === 0) pattern.lastIndex += 1;
+      if (match[0].length === 0) {
+        pattern.lastIndex += 1;
+      }
       match = pattern.exec(clean);
     }
   }
@@ -824,7 +958,7 @@ function excerptsFor(text, terms, budget) {
     const half = Math.max(0, Math.floor((budget.maxChars - hit.length) / 2));
     const start = toWordBoundary(clean, Math.max(0, hit.at - half), -1);
     const end = toWordBoundary(clean, Math.min(clean.length, hit.at + hit.length + half), 1);
-    const previous = windows[windows.length - 1];
+    const previous = windows.at(-1);
     if (previous && start <= previous.end) {
       previous.end = Math.max(previous.end, end);
       continue;
@@ -839,7 +973,8 @@ function excerptsFor(text, terms, budget) {
   });
   return { passages, located: true };
 }
-function toNewspaperResults(payload, url, query, budget, onSkip, settled = true) {
+function toNewspaperResults(payload, url, query, reading) {
+  const { budget, onSkip, settled = true } = reading;
   const rows = rowsOf(payload, url);
   const terms = queryTerms(query);
   const hits = [];
@@ -871,18 +1006,24 @@ function toNewspaperResults(payload, url, query, budget, onSkip, settled = true)
       sourceUrl: source
     });
   }
-  if (skipped > 0) onSkip(skipped);
+  if (skipped > 0) {
+    onSkip(skipped);
+  }
   if (rows.length > 0 && hits.length === 0) {
     throw parseFailure(`${rows.length} matches came back and none could be read.`, { url });
   }
   return { paging: toPaging(payload, url, settled), hits };
 }
 function toResources(value) {
-  if (!Array.isArray(value)) return [];
+  if (!Array.isArray(value)) {
+    return [];
+  }
   const resources = [];
   for (const entry of value) {
     const resource = asObject(entry);
-    if (!resource) continue;
+    if (!resource) {
+      continue;
+    }
     const files = resource.files;
     const fileCount = Array.isArray(files) ? files.reduce((sum, group) => sum + (Array.isArray(group) ? group.length : 1), 0) : asNumber(files);
     resources.push({
@@ -896,17 +1037,23 @@ function toResources(value) {
 }
 function toCitations(value) {
   const block = asObject(value);
-  if (!block) return {};
+  if (!block) {
+    return {};
+  }
   const citations = {};
   for (const [style, text] of Object.entries(block)) {
-    if (typeof text !== "string" || text.trim() === "") continue;
+    if (typeof text !== "string" || text.trim() === "") {
+      continue;
+    }
     citations[style] = plainText(text);
   }
   return citations;
 }
 function toItemDetail(payload, identifier, url) {
   const root = asObject(payload);
-  if (!root) throw parseFailure("The item answer was not an object.", { url });
+  if (!root) {
+    throw parseFailure("The item answer was not an object.", { url });
+  }
   if (asNumber(root.status) === 404) {
     throw notFound(`The Library of Congress has no record called "${identifier}".`, { url });
   }
@@ -977,7 +1124,9 @@ function toCollections(payload, url, onSkip, settled = true) {
       itemsUrl: asString(row[ROW_FIELD.items])
     });
   }
-  if (skipped > 0) onSkip(skipped);
+  if (skipped > 0) {
+    onSkip(skipped);
+  }
   if (rows.length > 0 && collections.length === 0) {
     throw parseFailure(`${rows.length} collections came back and none could be read.`, { url });
   }
@@ -1020,7 +1169,9 @@ var RateLimiter = class {
   async beforeRequest() {
     const elapsed = Date.now() - this.lastStartedAt;
     const wait = Math.min(this.intervalMs, this.intervalMs - elapsed);
-    if (wait > 0) await sleep(wait);
+    if (wait > 0) {
+      await sleep(wait);
+    }
     this.lastStartedAt = Date.now();
   }
   /** Called when the site asks for room: double the gap, up to the ceiling. */
@@ -1033,9 +1184,13 @@ var RateLimiter = class {
    * response after a rough patch does not undo the caution that earned it.
    */
   succeeded() {
-    if (this.intervalMs === this.baseIntervalMs) return;
+    if (this.intervalMs === this.baseIntervalMs) {
+      return;
+    }
     this.calmStreak += 1;
-    if (this.calmStreak < 3) return;
+    if (this.calmStreak < 3) {
+      return;
+    }
     this.calmStreak = 0;
     this.intervalMs = Math.max(this.baseIntervalMs, Math.round(this.intervalMs / 2));
   }
@@ -1144,7 +1299,7 @@ var LocClient = class {
     return this.read(
       key,
       url,
-      (payload, onSkip, settled) => toNewspaperResults(payload, url, trimmed, budget, onSkip, settled),
+      (payload, onSkip, settled) => toNewspaperResults(payload, url, trimmed, { budget, onSkip, settled }),
       // Reading the text of millions of pages takes the site far longer than
       // answering from the catalogue, so this route carries a budget of its own.
       this.config.newspaperTimeoutMs
@@ -1174,11 +1329,24 @@ import { z as z3 } from "zod";
 // src/tools/arguments.ts
 import { z } from "zod";
 var INVALID_INPUT = "invalid_input";
+var defaultMessage = z.core.locales.en().localeError;
 function strictInput(shape) {
   const declared = Object.keys(shape);
-  return z.strictObject(shape, {
-    error: (issue) => issue.code === "unrecognized_keys" ? unknownArgumentMessage(issue.keys, declared) : void 0
-  });
+  const refuse = (issue) => issue.code === "unrecognized_keys" ? unknownArgumentMessage(issue.keys, declared) : `[${INVALID_INPUT}] ${defaultMessage(issue)}`;
+  for (const argument of Object.values(shape)) {
+    carryTheCode(argument, refuse);
+  }
+  return z.strictObject(shape, { error: refuse });
+}
+function carryTheCode(schema, refuse) {
+  const definition = schema._zod.def;
+  definition.error = refuse;
+  for (const check of definition.checks ?? []) {
+    check._zod.def.error = refuse;
+  }
+  if (definition.innerType) {
+    carryTheCode(definition.innerType, refuse);
+  }
 }
 function unknownArgumentMessage(keys, declared) {
   const named = keys.map((key) => {
@@ -1190,15 +1358,21 @@ function unknownArgumentMessage(keys, declared) {
 function nearestArgument(key, declared) {
   const flatten = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
   const flat = flatten(key);
-  if (flat.length === 0) return void 0;
+  if (flat.length === 0) {
+    return void 0;
+  }
   const sameName = declared.find((name) => flatten(name) === flat);
-  if (sameName) return sameName;
+  if (sameName) {
+    return sameName;
+  }
   const overlapping = declared.find((name) => {
     const other = flatten(name);
     const [shorter, longer] = other.length < flat.length ? [other, flat] : [flat, other];
     return shorter.length >= 3 && (longer.startsWith(shorter) || longer.endsWith(shorter));
   });
-  if (overlapping) return overlapping;
+  if (overlapping) {
+    return overlapping;
+  }
   let closest;
   let shortest = Number.POSITIVE_INFINITY;
   for (const name of declared) {
@@ -1212,19 +1386,38 @@ function nearestArgument(key, declared) {
 }
 function editDistance(left, right) {
   let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  let distance = right.length;
   for (let row = 1; row <= left.length; row += 1) {
     const current = [row];
-    for (let column = 1; column <= right.length; column += 1) {
-      const substitution = previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1);
-      current[column] = Math.min(substitution, previous[column] + 1, current[column - 1] + 1);
+    let diagonal = row - 1;
+    let leftward = row;
+    for (const [column, above] of previous.entries()) {
+      if (column === 0) {
+        continue;
+      }
+      const substitution = diagonal + (left[row - 1] === right[column - 1] ? 0 : 1);
+      const cell = Math.min(substitution, above + 1, leftward + 1);
+      current.push(cell);
+      diagonal = above;
+      leftward = cell;
     }
     previous = current;
+    distance = leftward;
   }
-  return previous[right.length];
+  return distance;
 }
 
 // src/tools/shared.ts
 import { z as z2 } from "zod";
+function identifierLine(record) {
+  if (record.identifier) {
+    return `\xB7 id: ${record.identifier}`;
+  }
+  if (record.is_collection) {
+    return "\xB7 a collection, no identifier";
+  }
+  return "\xB7 no identifier";
+}
 var MAX_TEXT_CHARS = 2200;
 var ATTRIBUTION = "Source: Library of Congress";
 var recordSchema = z2.object({
@@ -1253,7 +1446,9 @@ function indentMarkerLines(body) {
 function ok(structured, body, options = {}) {
   const credit = options.sourceUrl ? `${ATTRIBUTION} \u2014 ${options.sourceUrl}` : ATTRIBUTION;
   const noteLines = (options.notes ?? []).map((note) => `Note: ${note}`);
-  while (noteLines.length > 0 && noteLines.join("\n").length > MAX_TEXT_CHARS / 2) noteLines.pop();
+  while (noteLines.length > 0 && noteLines.join("\n").length > MAX_TEXT_CHARS / 2) {
+    noteLines.pop();
+  }
   const trailer = [...noteLines, credit].join("\n");
   const cut = "\n\n[shortened; the full result is in the structured output]";
   const budget = MAX_TEXT_CHARS - `
@@ -1270,7 +1465,9 @@ ${trailer}`;
 function toToolError(error) {
   const known = error instanceof LocError ? error : new LocError("network_error", error instanceof Error ? error.message : String(error));
   const lines = [`[${known.code}] ${known.message}`];
-  if (known.details.hint) lines.push(`Hint: ${known.details.hint}`);
+  if (known.details.hint) {
+    lines.push(`Hint: ${known.details.hint}`);
+  }
   return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
 }
 function agrees(n, singular, plural) {
@@ -1280,17 +1477,23 @@ function counted(n, singular, plural = `${singular}s`) {
   return `${n} ${agrees(n, singular, plural)}`;
 }
 function truncate(text, maxChars) {
-  if (text.length <= maxChars) return text;
+  if (text.length <= maxChars) {
+    return text;
+  }
   return `${text.slice(0, Math.max(0, maxChars - 1)).trimEnd()}\u2026`;
 }
 function sliceAtLineBoundary(text, offset, maxChars) {
   const rest = text.slice(offset);
-  if (rest.length <= maxChars) return { slice: rest, nextOffset: null };
+  if (rest.length <= maxChars) {
+    return { slice: rest, nextOffset: null };
+  }
   const window = rest.slice(0, maxChars);
   const lastBreak = window.lastIndexOf("\n");
   let cut = lastBreak > 0 ? lastBreak : maxChars;
   const code = rest.charCodeAt(cut - 1);
-  if (code >= 55296 && code <= 56319) cut -= 1;
+  if (code >= 55296 && code <= 56319) {
+    cut -= 1;
+  }
   return { slice: rest.slice(0, cut), nextOffset: offset + cut };
 }
 function renderRecords(records) {
@@ -1303,7 +1506,7 @@ function renderRecords(records) {
       // An identifier a row does not carry is stated rather than left out: a
       // line with nothing where the others carry an id reads as a line whose
       // id went unprinted.
-      record.identifier ? `\xB7 id: ${record.identifier}` : record.is_collection ? "\xB7 a collection, no identifier" : "\xB7 no identifier"
+      identifierLine(record)
     ];
     return `${bits.filter(Boolean).join(" ")}
    ${record.source_url}`;
@@ -1313,6 +1516,45 @@ var OCR_CAVEAT = "Excerpts are the text a machine read off the scanned page, so
 var RIGHTS_CAVEAT = "The Library states no terms of use on this record. Silence is not permission: check the record's page before republishing.";
 
 // src/tools/getItem.ts
+function attachAskedSections(structured, data, wanted, notes) {
+  if (wanted.has("citations")) {
+    structured.citations = data.citations;
+    if (Object.keys(data.citations).length === 0) {
+      notes.push("The Library publishes no ready-made citation for this record.");
+    }
+  }
+  if (wanted.has("resources")) {
+    structured.resources = data.resources.map((resource) => ({
+      caption: resource.caption,
+      file_count: resource.fileCount,
+      url: resource.url,
+      image_url: resource.imageUrl
+    }));
+    if (data.resources.length === 0) {
+      notes.push("The Library serves no copy of this record online.");
+    }
+  }
+  if (wanted.has("full_metadata")) {
+    structured.full_metadata = data.raw ?? {};
+  }
+}
+function notesOnWhatTheRecordStates(data) {
+  const notes = [];
+  if (data.dateIsSpanOpening) {
+    notes.push(
+      `The record states its date as "${data.dateStated}". ${data.date} is the opening of that span and where the Library files the record, and 'year' reads the same value, so neither is a date the record carries.`
+    );
+  }
+  if (data.dateCode !== null) {
+    notes.push(
+      `The Library files this record under "${data.dateCode}", a cataloguing code standing for digits it has not established rather than a date, so 'date' and 'year' are null. 'date_stated' repeats what the record itself says about when it was made.`
+    );
+  }
+  if (!data.rights) {
+    notes.push(RIGHTS_CAVEAT);
+  }
+  return notes;
+}
 var SECTIONS = ["basic", "citations", "resources", "full_metadata"];
 var getItemDescription = [
   "Read one Library of Congress record by its identifier, as returned by search_items or search_newspapers.",
@@ -1380,7 +1622,9 @@ async function runGetItem(client, args) {
     const wanted = new Set(args.sections);
     const { data, cached } = await client.getItem(args.identifier);
     const notes = [];
-    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (cached) {
+      notes.push("Served from this server's short-lived in-memory cache.");
+    }
     const full = data.description ?? "";
     const notesOnRecord = data.notes.filter((note) => !full.includes(note));
     const { slice, nextOffset } = sliceAtLineBoundary(
@@ -1423,35 +1667,8 @@ async function runGetItem(client, args) {
       rights: data.rights,
       notes
     };
-    if (wanted.has("citations")) {
-      structured.citations = data.citations;
-      if (Object.keys(data.citations).length === 0) {
-        notes.push("The Library publishes no ready-made citation for this record.");
-      }
-    }
-    if (wanted.has("resources")) {
-      structured.resources = data.resources.map((resource) => ({
-        caption: resource.caption,
-        file_count: resource.fileCount,
-        url: resource.url,
-        image_url: resource.imageUrl
-      }));
-      if (data.resources.length === 0) {
-        notes.push("The Library serves no copy of this record online.");
-      }
-    }
-    if (wanted.has("full_metadata")) structured.full_metadata = data.raw ?? {};
-    if (data.dateIsSpanOpening) {
-      notes.push(
-        `The record states its date as "${data.dateStated}". ${data.date} is the opening of that span and where the Library files the record, and 'year' reads the same value, so neither is a date the record carries.`
-      );
-    }
-    if (data.dateCode !== null) {
-      notes.push(
-        `The Library files this record under "${data.dateCode}", a cataloguing code standing for digits it has not established rather than a date, so 'date' and 'year' are null. 'date_stated' repeats what the record itself says about when it was made.`
-      );
-    }
-    if (!data.rights) notes.push(RIGHTS_CAVEAT);
+    attachAskedSections(structured, data, wanted, notes);
+    notes.push(...notesOnWhatTheRecordStates(data));
     const lines = [
       [data.title ?? data.identifier, data.date ? `(${data.date})` : ""].filter(Boolean).join(" "),
       data.creator ? `By ${data.creator}` : "",
@@ -1461,7 +1678,9 @@ async function runGetItem(client, args) {
       data.repository ? `Held at: ${data.repository}` : "",
       data.rights ? `Rights: ${data.rights}` : ""
     ].filter(Boolean);
-    if (slice !== "") lines.push("", slice);
+    if (slice !== "") {
+      lines.push("", slice);
+    }
     const resources = structured.resources;
     if (resources && resources.length > 0) {
       lines.push("", "Copies served online:");
@@ -1477,6 +1696,15 @@ async function runGetItem(client, args) {
 
 // src/tools/listCollections.ts
 import { z as z4 } from "zod";
+function nothingOnThisPage(read, total, page) {
+  if (read > 0) {
+    return `None of the ${counted(read, "collection")} on page ${page} publishes a format naming a media_type.`;
+  }
+  if (total > 0) {
+    return `Page ${page} is past the last of ${counted(total, "collection")}.`;
+  }
+  return "The Library published no collection here.";
+}
 var MAX_COLLECTION_PAGE = 100;
 var listCollectionsDescription = [
   "List the digital collections of the Library of Congress: bodies of material a curator chose, described and published together.",
@@ -1520,7 +1748,9 @@ async function askCollections(client, limit, page) {
   try {
     return await client.listCollections(limit, page);
   } catch (error) {
-    if (!(error instanceof LocError) || error.code !== "not_found" || page <= 1) throw error;
+    if (!(error instanceof LocError) || error.code !== "not_found" || page <= 1) {
+      throw error;
+    }
     const first = await client.listCollections(limit, 1);
     return { data: { paging: first.data.paging, collections: [] }, cached: first.cached };
   }
@@ -1529,7 +1759,9 @@ async function runListCollections(client, args) {
   try {
     const { data, cached, skipped } = await askCollections(client, args.limit, args.page);
     const notes = [];
-    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (cached) {
+      notes.push("Served from this server's short-lived in-memory cache.");
+    }
     if (skipped) {
       notes.push(
         `${counted(skipped, "row")} came back in a shape this server could not read and ${agrees(skipped, "was", "were")} left out.`
@@ -1582,7 +1814,7 @@ async function runListCollections(client, args) {
         `Page ${args.page} is past the last collection. ${total} ${agrees(total, "exists", "exist")}, so ask for a lower page.`
       );
     }
-    const body = collections.length === 0 ? read.length > 0 ? `None of the ${counted(read.length, "collection")} on page ${args.page} publishes a format naming a media_type.` : total > 0 ? `Page ${args.page} is past the last of ${counted(total, "collection")}.` : "The Library published no collection here." : `${collections.length} of ${counted(total, "collection")}:
+    const body = collections.length === 0 ? nothingOnThisPage(read.length, total, args.page) : `${collections.length} of ${counted(total, "collection")}:
 ` + collections.map((collection, index) => {
       const head = [
         `${index + 1}. ${collection.title}`,
@@ -1600,6 +1832,61 @@ async function runListCollections(client, args) {
 
 // src/tools/searchItems.ts
 import { z as z5 } from "zod";
+function notesOnWhatTheSearchReached(data, args, items, total, narrowing) {
+  const notes = [];
+  if (total > items.length) {
+    notes.push(
+      narrowing.setAside ? `${counted(total, "record")} match the search${narrowing.without}, and ${items.length} ${agrees(items.length, "is", "are")} shown.` : `${counted(total, "record")} match and ${items.length} ${agrees(items.length, "is", "are")} shown.`
+    );
+  }
+  const gathered = items.filter((item) => item.is_collection).length;
+  if (gathered > 0) {
+    notes.push(
+      `${gathered} of the ${counted(items.length, "row")} shown ${agrees(gathered, "is a collection", "are collections")} the Library gathered and named rather than ${agrees(gathered, "a record", "records")} of the ${args.media_type} catalogue: 'identifier' is null there, get_item has nothing to take, and 'source_url' opens the collection. The count beside the rows is the catalogue's own, and it counts them in.`
+    );
+  }
+  const anonymous = items.filter((item) => item.identifier === null && !item.is_collection).length;
+  if (anonymous > 0) {
+    notes.push(
+      `${counted(anonymous, "row")} shown ${agrees(anonymous, "names", "name")} an address that is not a record: 'identifier' is null there and get_item has nothing to take, so ${agrees(anonymous, "read it at its", "read them at their")} 'source_url'.`
+    );
+  }
+  const coded = items.filter((item) => item.date_code !== null);
+  if (coded.length > 0) {
+    const codes = [...new Set(coded.map((item) => item.date_code))].join(", ");
+    notes.push(
+      `${counted(coded.length, "row")} shown ${agrees(coded.length, "carries", "carry")} no date: the Library files ${agrees(coded.length, "it", "them")} under a cataloguing code standing for digits it has not established, so 'date' and 'year' are null there while 'date_code' holds the code it filed ${agrees(coded.length, "it", "them")} under: ${codes}.`
+    );
+  }
+  if (total === 0) {
+    notes.push(
+      `Nothing in the ${args.media_type} catalogue matches. A search here reads titles and catalogue descriptions only, so a phrase printed inside a newspaper belongs in search_newspapers.`
+    );
+  }
+  if (items.length === 0 && total > 0) {
+    const pages = data.paging.pageCount;
+    notes.push(
+      `Page ${args.page} is past the last row. ${counted(total, "record")} match${pages === null ? "" : ` across ${counted(pages, "page")} at this page size`}, so ask for a lower page.`
+    );
+  }
+  if (!narrowing.setAside && (args.year_from !== void 0 || args.year_to !== void 0)) {
+    notes.push(
+      "A record spanning several years matches on any of them, so a row can carry a date outside the range asked for while still belonging to it."
+    );
+  }
+  if (!args.online_only && items.length > 0) {
+    notes.push(
+      "This search took in records with no digitised copy. Read 'online' on a row before promising something can be read from a browser."
+    );
+  }
+  return notes;
+}
+function nothingOnThisPage2(total, page, mediaType, query) {
+  if (total > 0) {
+    return `Page ${page} is past the last of ${counted(total, "record")} the ${mediaType} catalogue holds for "${query}".`;
+  }
+  return `Nothing in the ${mediaType} catalogue for "${query}".`;
+}
 var searchItemsDescription = [
   "Search the Library of Congress catalogue: books, photographs, maps, recordings, films, manuscripts, sheet music and newspaper titles.",
   "'media_type' is required, because the Library keeps a separate catalogue for each kind of thing.",
@@ -1641,10 +1928,18 @@ var searchItemsOutput = z5.object({
 });
 function describeNarrowing(args) {
   const written = [];
-  if (args.subject) written.push(`subject="${args.subject}"`);
-  if (args.location) written.push(`location="${args.location}"`);
-  if (args.language) written.push(`language="${args.language}"`);
-  if (args.collection) written.push(`collection="${args.collection}"`);
+  if (args.subject) {
+    written.push(`subject="${args.subject}"`);
+  }
+  if (args.location) {
+    written.push(`location="${args.location}"`);
+  }
+  if (args.language) {
+    written.push(`language="${args.language}"`);
+  }
+  if (args.collection) {
+    written.push(`collection="${args.collection}"`);
+  }
   if (args.year_from !== void 0 || args.year_to !== void 0) {
     written.push(`years ${args.year_from ?? "any"} to ${args.year_to ?? "any"}`);
   }
@@ -1652,9 +1947,15 @@ function describeNarrowing(args) {
 }
 function whereTheWordingIs(args) {
   const advice = [];
-  if (args.subject) advice.push("a subject is spelled as 'subjects' spells it on a row");
-  if (args.location) advice.push("a place is spelled as 'location' spells it on a row");
-  if (args.language) advice.push('a language is written in English, as in "english"');
+  if (args.subject) {
+    advice.push("a subject is spelled as 'subjects' spells it on a row");
+  }
+  if (args.location) {
+    advice.push("a place is spelled as 'location' spells it on a row");
+  }
+  if (args.language) {
+    advice.push('a language is written in English, as in "english"');
+  }
   if (args.collection) {
     advice.push("a collection is spelled as list_collections reports it under 'collection_filter'");
   }
@@ -1666,14 +1967,16 @@ async function askCatalogue(client, query, page) {
   try {
     return await client.searchItems(query);
   } catch (error) {
-    if (!(error instanceof LocError) || error.code !== "not_found" || page <= 1) throw error;
+    if (!(error instanceof LocError) || error.code !== "not_found" || page <= 1) {
+      throw error;
+    }
     const first = await client.searchItems({ ...query, page: 1 });
     return { data: { paging: first.data.paging, records: [] }, cached: first.cached };
   }
 }
 async function runSearchItems(client, args) {
   try {
-    if (!INDEXED_WORD.test(args.query) && !ONE_CHARACTER_WORD.test(args.query)) {
+    if (!(INDEXED_WORD.test(args.query) || ONE_CHARACTER_WORD.test(args.query))) {
       return toToolError(
         invalidInput(
           `Every word of "${args.query}" is a single letter, and the catalogue index holds no such word, so this query is one the index cannot be asked.`,
@@ -1691,7 +1994,9 @@ async function runSearchItems(client, args) {
     }
     const facets = {};
     const put = (field, value) => {
-      if (value && value.trim() !== "") facets[field] = value;
+      if (value && value.trim() !== "") {
+        facets[field] = value;
+      }
     };
     put("subject", args.subject);
     put("location", args.location);
@@ -1709,8 +2014,8 @@ async function runSearchItems(client, args) {
     const narrowed = {
       ...wide,
       facets,
-      ...args.year_from !== void 0 ? { yearFrom: args.year_from } : {},
-      ...args.year_to !== void 0 ? { yearTo: args.year_to } : {}
+      ...args.year_from === void 0 ? {} : { yearFrom: args.year_from },
+      ...args.year_to === void 0 ? {} : { yearTo: args.year_to }
     };
     const notes = [];
     let result = await askCatalogue(client, narrowed, args.page);
@@ -1727,7 +2032,9 @@ async function runSearchItems(client, args) {
       }
     }
     const { data, cached, skipped } = result;
-    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (cached) {
+      notes.push("Served from this server's short-lived in-memory cache.");
+    }
     if (skipped) {
       notes.push(
         `${counted(skipped, "row")} came back in a shape this server could not read and ${agrees(skipped, "was", "were")} left out.`
@@ -1749,54 +2056,13 @@ async function runSearchItems(client, args) {
     }));
     const total = data.paging.resultCount;
     const withoutNarrowing = narrowingSetAside ? ` without ${narrowing.join(", ")}` : "";
-    if (total > items.length) {
-      notes.push(
-        narrowingSetAside ? `${counted(total, "record")} match the search${withoutNarrowing}, and ${items.length} ${agrees(items.length, "is", "are")} shown.` : `${counted(total, "record")} match and ${items.length} ${agrees(items.length, "is", "are")} shown.`
-      );
-    }
-    const gathered = items.filter((item) => item.is_collection).length;
-    if (gathered > 0) {
-      notes.push(
-        `${gathered} of the ${counted(items.length, "row")} shown ${agrees(gathered, "is a collection", "are collections")} the Library gathered and named rather than ${agrees(gathered, "a record", "records")} of the ${args.media_type} catalogue: 'identifier' is null there, get_item has nothing to take, and 'source_url' opens the collection. The count beside the rows is the catalogue's own, and it counts them in.`
-      );
-    }
-    const anonymous = items.filter(
-      (item) => item.identifier === null && !item.is_collection
-    ).length;
-    if (anonymous > 0) {
-      notes.push(
-        `${counted(anonymous, "row")} shown ${agrees(anonymous, "names", "name")} an address that is not a record: 'identifier' is null there and get_item has nothing to take, so ${agrees(anonymous, "read it at its", "read them at their")} 'source_url'.`
-      );
-    }
-    const coded = items.filter((item) => item.date_code !== null);
-    if (coded.length > 0) {
-      const codes = [...new Set(coded.map((item) => item.date_code))].join(", ");
-      notes.push(
-        `${counted(coded.length, "row")} shown ${agrees(coded.length, "carries", "carry")} no date: the Library files ${agrees(coded.length, "it", "them")} under a cataloguing code standing for digits it has not established, so 'date' and 'year' are null there while 'date_code' holds the code it filed ${agrees(coded.length, "it", "them")} under: ${codes}.`
-      );
-    }
-    if (total === 0) {
-      notes.push(
-        `Nothing in the ${args.media_type} catalogue matches. A search here reads titles and catalogue descriptions only, so a phrase printed inside a newspaper belongs in search_newspapers.`
-      );
-    }
-    if (items.length === 0 && total > 0) {
-      const pages = data.paging.pageCount;
-      notes.push(
-        `Page ${args.page} is past the last row. ${counted(total, "record")} match${pages === null ? "" : ` across ${counted(pages, "page")} at this page size`}, so ask for a lower page.`
-      );
-    }
-    if (!narrowingSetAside && (args.year_from !== void 0 || args.year_to !== void 0)) {
-      notes.push(
-        "A record spanning several years matches on any of them, so a row can carry a date outside the range asked for while still belonging to it."
-      );
-    }
-    if (!args.online_only && items.length > 0) {
-      notes.push(
-        "This search took in records with no digitised copy. Read 'online' on a row before promising something can be read from a browser."
-      );
-    }
-    const body = items.length === 0 ? total > 0 ? `Page ${args.page} is past the last of ${counted(total, "record")} the ${args.media_type} catalogue holds for "${args.query}".` : `Nothing in the ${args.media_type} catalogue for "${args.query}".` : `${items.length} of ${counted(total, "record")} for "${args.query}"${withoutNarrowing}:
+    notes.push(
+      ...notesOnWhatTheSearchReached(data, args, items, total, {
+        setAside: narrowingSetAside,
+        without: withoutNarrowing
+      })
+    );
+    const body = items.length === 0 ? nothingOnThisPage2(total, args.page, args.media_type, args.query) : `${items.length} of ${counted(total, "record")} for "${args.query}"${withoutNarrowing}:
 ${renderRecords(items)}`;
     return ok({ query: args.query, total, page: args.page, items, notes }, body, { notes });
   } catch (error) {
@@ -1806,6 +2072,12 @@ ${renderRecords(items)}`;
 
 // src/tools/searchNewspapers.ts
 import { z as z6 } from "zod";
+function nothingOnThisPage3(total, page, query) {
+  if (total > 0) {
+    return `Page ${page} is past the last of ${counted(total, "newspaper page")} the Library matched for ${query}.`;
+  }
+  return `Nothing found in the scanned newspapers for ${query}.`;
+}
 var searchNewspapersDescription = [
   "Search the text inside digitised American newspaper pages held by the Library of Congress.",
   "This reads what optical recognition took off the scanned pages, so it finds a phrase that appears nowhere in a title or a catalogue record.",
@@ -1865,8 +2137,12 @@ var searchNewspapersOutput = z6.object({
 var QUOTED_PHRASE = /"[^"]+"/;
 function describeNarrowing2(args) {
   const written = [];
-  if (args.location) written.push(`location="${args.location}"`);
-  if (args.publication) written.push(`publication="${args.publication}"`);
+  if (args.location) {
+    written.push(`location="${args.location}"`);
+  }
+  if (args.publication) {
+    written.push(`publication="${args.publication}"`);
+  }
   if (args.year_from !== void 0 || args.year_to !== void 0) {
     written.push(`years ${args.year_from ?? "any"} to ${args.year_to ?? "any"}`);
   }
@@ -1885,15 +2161,17 @@ async function runSearchNewspapers(client, args) {
     const budget = { maxChars: args.max_excerpt_chars, maxCount: args.max_excerpts_per_match };
     const facets = {};
     const put = (field, value) => {
-      if (value && value.trim() !== "") facets[field] = value;
+      if (value && value.trim() !== "") {
+        facets[field] = value;
+      }
     };
     put("state", args.location);
     put("publication", args.publication);
     const narrowing = describeNarrowing2(args);
     const filters = {
       facets,
-      ...args.year_from !== void 0 ? { yearFrom: args.year_from } : {},
-      ...args.year_to !== void 0 ? { yearTo: args.year_to } : {}
+      ...args.year_from === void 0 ? {} : { yearFrom: args.year_from },
+      ...args.year_to === void 0 ? {} : { yearTo: args.year_to }
     };
     const notes = [];
     let result = await client.searchNewspapers(args.query, args.limit, args.page, budget, filters);
@@ -1907,7 +2185,9 @@ async function runSearchNewspapers(client, args) {
       }
     }
     const { data, cached, skipped } = result;
-    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (cached) {
+      notes.push("Served from this server's short-lived in-memory cache.");
+    }
     if (skipped) {
       notes.push(
         `${counted(skipped, "match", "matches")} came back in a shape this server could not read and ${agrees(skipped, "was", "were")} left out. The count above is what the Library reported.`
@@ -1927,7 +2207,9 @@ async function runSearchNewspapers(client, args) {
       source_url: hit.sourceUrl
     }));
     const total = data.paging.resultCount;
-    if (hits.length > 0) notes.push(OCR_CAVEAT);
+    if (hits.length > 0) {
+      notes.push(OCR_CAVEAT);
+    }
     const openings = hits.filter(
       (hit) => hit.excerpt_kind === "page_opening" && hit.excerpts.length > 0
     ).length;
@@ -1956,7 +2238,7 @@ async function runSearchNewspapers(client, args) {
         `Page ${args.page} is past the last match. ${counted(total, "page")} match, so ask for a lower page.`
       );
     }
-    const body = hits.length === 0 ? total > 0 ? `Page ${args.page} is past the last of ${counted(total, "newspaper page")} the Library matched for ${args.query}.` : `Nothing found in the scanned newspapers for ${args.query}.` : `${hits.length} of ${counted(total, "newspaper page")} the Library matched for ${args.query}:
+    const body = hits.length === 0 ? nothingOnThisPage3(total, args.page, args.query) : `${hits.length} of ${counted(total, "newspaper page")} the Library matched for ${args.query}:
 ` + hits.map((hit, index) => {
       const where = [
         `${index + 1}. ${hit.publication ?? hit.title ?? "untitled"}`,
@@ -2067,15 +2349,15 @@ async function main() {
   await server.connect(transport);
   const shutdown = async () => {
     await server.close().catch(() => void 0);
-    process.exit(0);
+    process2.exit(0);
   };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+  process2.on("SIGINT", shutdown);
+  process2.on("SIGTERM", shutdown);
 }
 main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
-  process.stderr.write(`[mcp-libraryofcongress] fatal: ${message}
+  process2.stderr.write(`[mcp-libraryofcongress] fatal: ${message}
 `);
-  process.exit(1);
+  process2.exit(1);
 });
 //# sourceMappingURL=index.js.map