mcp-libraryofcongress 1.0.0

package/dist/index.js

@@ -0,0 +1,1695 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/version.ts
+var PKG_VERSION = "1.0.0";
+var REPO_URL = "https://github.com/smeet666/mcp-libraryofcongress";
+
+// src/config.ts
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+var MIN_ALLOWED_INTERVAL_MS = 3e3;
+var MAX_ALLOWED_INTERVAL_MS = 6e4;
+var DEFAULT_INTERVAL_MS = 6e3;
+var DEFAULT_NEWSPAPER_TIMEOUT_MS = 9e4;
+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;
+    process.stderr.write(`[mcp-libraryofcongress] ${at}: ${message}
+`);
+  };
+  return {
+    debug: (m) => write("debug", m),
+    info: (m) => write("info", m),
+    // A warning goes out at the error level so it survives the default
+    // setting: a caller has to know that rows were dropped.
+    warn: (m) => write("error", m),
+    error: (m) => write("error", m)
+  };
+}
+function readInteger(env, name, fallback, min, max) {
+  const raw = env[name];
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    process.stderr.write(
+      `[mcp-libraryofcongress] error: ${name}="${raw}" is not a whole number; using ${fallback}.
+`
+    );
+    return fallback;
+  }
+  if (value < min || value > max) {
+    process.stderr.write(
+      `[mcp-libraryofcongress] error: ${name}=${value} is outside ${min}..${max}; using ${fallback}.
+`
+    );
+    return fallback;
+  }
+  return value;
+}
+function loadConfig(env = process.env) {
+  const level = env.LOC_LOG_LEVEL;
+  const logLevel = level && LOG_LEVELS.includes(level) ? level : "error";
+  if (level && !LOG_LEVELS.includes(level)) {
+    process.stderr.write(
+      `[mcp-libraryofcongress] error: LOC_LOG_LEVEL="${level}" is not one of ${LOG_LEVELS.join(", ")}; using error.
+`
+    );
+  }
+  const custom = env.LOC_USER_AGENT?.trim();
+  return {
+    // A caller who wants to be recognised may say who they are, and the
+    // contact address stays attached: the Library has to be able to reach a
+    // human about traffic it did not expect.
+    userAgent: custom ? `${custom} ${DEFAULT_USER_AGENT}` : DEFAULT_USER_AGENT,
+    minIntervalMs: readInteger(
+      env,
+      "LOC_MIN_INTERVAL_MS",
+      DEFAULT_INTERVAL_MS,
+      MIN_ALLOWED_INTERVAL_MS,
+      MAX_ALLOWED_INTERVAL_MS
+    ),
+    // A catalogue page carries a row for every match on it.
+    timeoutMs: readInteger(env, "LOC_TIMEOUT_MS", 3e4, 1e3, 12e4),
+    newspaperTimeoutMs: readInteger(
+      env,
+      "LOC_NEWSPAPER_TIMEOUT_MS",
+      DEFAULT_NEWSPAPER_TIMEOUT_MS,
+      1e3,
+      3e5
+    ),
+    maxRetries: readInteger(env, "LOC_MAX_RETRIES", 3, 0, 8),
+    cacheTtlMs: readInteger(env, "LOC_CACHE_TTL_MS", 9e5, 0, 864e5),
+    cacheMaxEntries: readInteger(env, "LOC_CACHE_MAX_ENTRIES", 200, 1, 5e3),
+    logLevel
+  };
+}
+
+// src/errors.ts
+var LocError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "LocError";
+    this.code = code;
+    this.details = details;
+  }
+};
+var notFound = (message, details) => new LocError("not_found", message, details);
+var invalidInput = (message, hint) => new LocError("invalid_input", message, hint ? { hint } : {});
+var rateLimited = (message, details) => new LocError("rate_limited", message, {
+  hint: "Wait a moment and ask again. This says nothing about whether the Library holds what you asked for.",
+  ...details
+});
+var parseFailure = (message, details) => new LocError("parse_failure", message, {
+  hint: "The Library may have changed how it answers. Please report this at https://github.com/smeet666/mcp-libraryofcongress/issues with the arguments you used.",
+  ...details
+});
+var networkError = (message, details) => new LocError("network_error", message, details);
+var timeout = (message, details) => new LocError("timeout", message, details);
+
+// src/loc/cache.ts
+var Cache = class {
+  constructor(ttlMs, maxEntries) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+  }
+  ttlMs;
+  maxEntries;
+  entries = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    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;
+      this.entries.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.entries.size;
+  }
+};
+
+// src/loc/http.ts
+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;
+  const trimmed = value.trim();
+  const seconds = Number(trimmed);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  const at = Date.parse(trimmed);
+  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);
+}
+async function fetchText(options) {
+  const { url, userAgent, timeoutMs, maxRetries, limiter, logger } = options;
+  const doFetch = options.fetchImpl ?? fetch;
+  let lastError = null;
+  let askedWaitMs = 0;
+  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));
+      askedWaitMs = 0;
+    }
+    await limiter.beforeRequest();
+    const controller = new AbortController();
+    const deadline = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      logger.debug(`GET ${url}`);
+      const response = await doFetch(url, {
+        signal: controller.signal,
+        redirect: "follow",
+        headers: { "user-agent": userAgent, accept: "application/json, text/plain, */*" }
+      });
+      if (response.ok) {
+        limiter.succeeded();
+        return await response.text();
+      }
+      if (PUSH_BACK.has(response.status)) {
+        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
+        });
+      }
+      throw networkError(`The Library of Congress answered HTTP ${response.status}.`, {
+        url,
+        status: 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
+        });
+      }
+      askedWaitMs = backoffMs(attempt);
+      continue;
+    } finally {
+      clearTimeout(deadline);
+    }
+  }
+  throw networkError(
+    `Could not reach the Library of Congress: ${lastError?.message ?? "no attempt was made"}`,
+    { url }
+  );
+}
+async function fetchJson(options) {
+  const body = await fetchText(options);
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw parseFailure("The Library of Congress answered with something that is not JSON.", {
+      url: options.url
+    });
+  }
+}
+
+// src/loc/paths.ts
+var HOST = "https://www.loc.gov";
+var FORMAT_ROUTE = {
+  books: "/books/",
+  photos: "/photos/",
+  maps: "/maps/",
+  audio: "/audio/",
+  "film-and-videos": "/film-and-videos/",
+  manuscripts: "/manuscripts/",
+  "notated-music": "/notated-music/",
+  newspapers: "/newspapers/"
+};
+var FORMAT_ROUTES = Object.keys(FORMAT_ROUTE);
+var NEWSPAPER_PAGES_ROUTE = "/collections/chronicling-america/";
+var COLLECTIONS_ROUTE = "/collections/";
+var ITEM_ROUTE = "/item/";
+var PARAM = {
+  /** Asks for JSON rather than a web page. */
+  format: "fo",
+  /** The words to look for. */
+  query: "q",
+  /** Results per page. */
+  perPage: "c",
+  /** Which page, from 1. */
+  page: "sp",
+  /** A year range, written from/to. */
+  dates: "dates",
+  /** Facet filters, several of them separated by a vertical bar. */
+  facets: "fa",
+  /** Sort order. */
+  sort: "sb",
+  /** Which top-level blocks to return, which is what keeps a page small. */
+  attributes: "at",
+  /** Widens a search past what the Library has digitised. */
+  all: "all"
+};
+var WANTED_BLOCKS = "results,pagination";
+var FACET_FIELD = {
+  subject: "subject",
+  location: "location",
+  language: "language",
+  contributor: "contributor",
+  partof: "partof",
+  /** The state a newspaper was published in, as the newspaper corpus files it. */
+  state: "location_state",
+  /** A newspaper, named with the town and the years it ran. */
+  publication: "partof_title"
+};
+var SORT = {
+  relevance: "",
+  newest: "date_desc",
+  oldest: "date",
+  title: "title_s"
+};
+var ROW_FIELD = {
+  id: "id",
+  url: "url",
+  title: "title",
+  date: "date",
+  contributor: "contributor",
+  originalFormat: "original_format",
+  onlineFormat: "online_format",
+  location: "location",
+  subject: "subject",
+  description: "description",
+  partOf: "partof",
+  digitized: "digitized",
+  /** Newspaper pages only, from here down. */
+  pageNumber: "number_page",
+  publicationTitle: "partof_title",
+  state: "location_state",
+  /** How many records a collection gathers. */
+  count: "count",
+  /** Lists what a collection holds. */
+  items: "items"
+};
+var ITEM_FIELD = {
+  id: "id",
+  url: "url",
+  title: "title",
+  date: "date",
+  contributorNames: "contributor_names",
+  description: "description",
+  notes: "notes",
+  subjects: "subjects",
+  location: "location",
+  language: "language",
+  partOf: "partof",
+  repository: "repository",
+  callNumber: "call_number",
+  rights: "rights_advisory",
+  rightsFallback: "rights_information",
+  originalFormat: "original_format"
+};
+var MOST_SUBJECTS = 12;
+var itemUrl = (identifier) => `${HOST}${ITEM_ROUTE}${identifier.split("/").map(encodeURIComponent).join("/")}/`;
+
+// src/loc/urls.ts
+var YEAR_BOUND = { earliest: 1e3, latest: 9999 };
+function base(path) {
+  const url = new URL(HOST + path);
+  url.searchParams.set(PARAM.format, "json");
+  url.searchParams.set(PARAM.attributes, WANTED_BLOCKS);
+  return url;
+}
+function facetString(facets) {
+  return Object.entries(facets).filter(([, value]) => typeof value === "string" && value.trim() !== "").map(([field, value]) => `${FACET_FIELD[field]}:${value.trim().toLowerCase()}`).join("|");
+}
+function catalogueUrl(q) {
+  const url = base(FORMAT_ROUTE[q.format]);
+  url.searchParams.set(PARAM.query, q.query);
+  url.searchParams.set(PARAM.perPage, String(q.limit));
+  url.searchParams.set(PARAM.page, String(q.page));
+  if (q.yearFrom !== void 0 || q.yearTo !== void 0) {
+    const from = q.yearFrom ?? YEAR_BOUND.earliest;
+    const to = q.yearTo ?? YEAR_BOUND.latest;
+    url.searchParams.set(PARAM.dates, `${from}/${to}`);
+  }
+  const facets = facetString(q.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");
+  return url.toString();
+}
+function newspaperPagesUrl(query, limit, page, filters = {}) {
+  const url = base(NEWSPAPER_PAGES_ROUTE);
+  url.searchParams.set(PARAM.query, query);
+  url.searchParams.set(PARAM.perPage, String(limit));
+  url.searchParams.set(PARAM.page, String(page));
+  if (filters.yearFrom !== void 0 || filters.yearTo !== void 0) {
+    const from = filters.yearFrom ?? YEAR_BOUND.earliest;
+    const to = filters.yearTo ?? YEAR_BOUND.latest;
+    url.searchParams.set(PARAM.dates, `${from}/${to}`);
+  }
+  const facets = facetString(filters.facets ?? {});
+  if (facets !== "") url.searchParams.set(PARAM.facets, facets);
+  return url.toString();
+}
+function collectionsUrl(limit, page) {
+  const url = base(COLLECTIONS_ROUTE);
+  url.searchParams.set(PARAM.perPage, String(limit));
+  url.searchParams.set(PARAM.page, String(page));
+  return url.toString();
+}
+function itemDocumentUrl(identifier) {
+  const segments = identifier.trim().replace(/^\/+|\/+$/g, "").split("/").filter((segment) => segment !== "");
+  if (segments.some((segment) => /^\.+$/.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."
+    );
+  }
+  const path = segments.map(encodeURIComponent).join("/");
+  const url = new URL(`${HOST}${ITEM_ROUTE}${path}/`);
+  url.searchParams.set(PARAM.format, "json");
+  return url.toString();
+}
+function identifierFrom(address) {
+  if (!address) return null;
+  const trimmed = address.trim();
+  if (trimmed === "") return null;
+  const absolute = trimmed.startsWith("//") ? `https:${trimmed}` : trimmed;
+  let parsed;
+  try {
+    parsed = new URL(absolute);
+  } catch {
+    return null;
+  }
+  const path = parsed.pathname.replace(/^\/+|\/+$/g, "");
+  if (path === "") return null;
+  const segments = path.split("/");
+  if (parsed.hostname === "lccn.loc.gov") return segments[0] ?? null;
+  const first = segments[0];
+  if (first === "item" || first === "resource") {
+    const rest = segments.slice(1);
+    return rest.length > 0 ? rest.join("/") : null;
+  }
+  if (first === "collections") return segments[1] ?? null;
+  return null;
+}
+
+// src/loc/parse.ts
+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))
+    return value.filter((v) => typeof v === "string" && v.trim() !== "");
+  return [];
+}
+var asString = (value) => asStrings(value)[0] ?? null;
+function asLabels(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  const labels = [];
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      if (entry.trim() !== "") labels.push(entry);
+      continue;
+    }
+    const object = asObject(entry);
+    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);
+    }
+  }
+  return labels;
+}
+function asNumber(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 (Array.isArray(value)) return asNumber(value[0]);
+  return null;
+}
+function asPageNumber(value) {
+  const text = asString(value);
+  if (text === null) return null;
+  const digits = text.trim();
+  if (!/^\d+$/.test(digits)) return null;
+  const n = Number(digits);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+var PLAUSIBLE_YEAR = { first: 1e3, last: 2200 };
+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 direct = asNumber(value);
+  return direct === null ? null : plausible(direct);
+}
+function plainText(value) {
+  return value.replace(/<[^>]*>/g, "").replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#0?39;|&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+function toPaging(payload, url) {
+  const root = asObject(payload);
+  const pagination = root ? asObject(root.pagination) : null;
+  if (!pagination) {
+    throw parseFailure(
+      "The answer carried no pagination block, so nothing states how many results match.",
+      {
+        url
+      }
+    );
+  }
+  const resultCount = asNumber(pagination.of);
+  if (resultCount === null) {
+    throw parseFailure("The answer carried no readable count of results.", { url });
+  }
+  return {
+    resultCount,
+    pageCount: asNumber(pagination.total),
+    currentPage: asNumber(pagination.current),
+    perPage: asNumber(pagination.perpage)
+  };
+}
+function rowsOf(payload, url) {
+  const root = asObject(payload);
+  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);
+}
+var creatorOf = (row) => asStrings(row[ROW_FIELD.contributor]).map(plainText).join(", ") || null;
+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;
+  }
+  return identifier === null ? "" : itemUrl(identifier);
+}
+function toSearchResults(payload, url, onSkip) {
+  const rows = rowsOf(payload, url);
+  const records = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const title = asString(row[ROW_FIELD.title]);
+    const identifier = identifierFrom(asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]));
+    const source = sourceUrlOf(row, identifier);
+    if (title === null && source === "") {
+      skipped += 1;
+      continue;
+    }
+    records.push({
+      identifier,
+      title: title === null ? null : plainText(title),
+      creator: creatorOf(row),
+      year: asYear(row[ROW_FIELD.date]),
+      date: asString(row[ROW_FIELD.date]),
+      format: asString(row[ROW_FIELD.originalFormat]),
+      location: asStrings(row[ROW_FIELD.location]),
+      subjects: asStrings(row[ROW_FIELD.subject]).slice(0, MOST_SUBJECTS),
+      online: row[ROW_FIELD.digitized] === true,
+      sourceUrl: source
+    });
+  }
+  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 });
+  }
+  return { paging: toPaging(payload, url), records };
+}
+var JOINING_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "was",
+  "were",
+  "are",
+  "his",
+  "her",
+  "its",
+  "not",
+  "but",
+  "had",
+  "has",
+  "you",
+  "all",
+  "any",
+  "who"
+]);
+function queryTerms(query) {
+  const terms = [];
+  const phrases = query.match(/"([^"]+)"/g) ?? [];
+  for (const phrase of phrases) {
+    const inner = phrase.slice(1, -1).trim().toLowerCase();
+    if (inner !== "") terms.push(inner);
+  }
+  const rest = query.replace(/"[^"]*"/g, " ");
+  for (const word of rest.split(/[^\p{L}\p{N}'-]+/u)) {
+    const lower = word.trim().toLowerCase();
+    if (lower.length < 3 || JOINING_WORDS.has(lower)) continue;
+    terms.push(lower);
+  }
+  return [...new Set(terms)];
+}
+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;
+    at += direction;
+  }
+  return index;
+}
+function excerptsFor(text, terms, budget) {
+  const clean = text.replace(/\s+/g, " ").trim();
+  if (clean === "") return { passages: [], located: false };
+  const haystack = clean.toLowerCase();
+  const found = [];
+  for (const term of terms) {
+    let from = 0;
+    while (from <= haystack.length - term.length) {
+      const at = haystack.indexOf(term, from);
+      if (at === -1) break;
+      found.push({ at, length: term.length });
+      from = at + term.length;
+    }
+  }
+  if (found.length === 0) {
+    const opening = clean.slice(0, budget.maxChars);
+    const cut = opening.length < clean.length;
+    return {
+      passages: [cut ? `${opening.trimEnd()}\u2026` : opening],
+      located: false
+    };
+  }
+  found.sort((a, b) => a.at - b.at);
+  const windows = [];
+  for (const hit of found) {
+    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];
+    if (previous && start <= previous.end) {
+      previous.end = Math.max(previous.end, end);
+      continue;
+    }
+    windows.push({ start, end });
+  }
+  const passages = windows.slice(0, budget.maxCount).map(({ start, end }) => {
+    const body = clean.slice(start, Math.min(end, start + budget.maxChars)).trim();
+    const opensMidway = start > 0;
+    const closesEarly = Math.min(end, start + budget.maxChars) < clean.length;
+    return `${opensMidway ? "\u2026" : ""}${body}${closesEarly ? "\u2026" : ""}`;
+  });
+  return { passages, located: true };
+}
+function toNewspaperResults(payload, url, query, budget, onSkip) {
+  const rows = rowsOf(payload, url);
+  const terms = queryTerms(query);
+  const hits = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const address = asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]);
+    const source = sourceUrlOf(row, identifierFrom(address));
+    if (source === "") {
+      skipped += 1;
+      continue;
+    }
+    const pageText = asStrings(row[ROW_FIELD.description]).join(" ");
+    const { passages, located } = excerptsFor(pageText, terms, budget);
+    const publication = asString(row[ROW_FIELD.publicationTitle]);
+    const title = asString(row[ROW_FIELD.title]);
+    hits.push({
+      identifier: identifierFrom(address),
+      title: title === null ? null : plainText(title),
+      // A newspaper page is credited to whoever contributed the scan, which is
+      // a library rather than a writer.
+      creator: creatorOf(row),
+      year: asYear(row[ROW_FIELD.date]),
+      pageNumber: asPageNumber(row[ROW_FIELD.pageNumber]),
+      publishedOn: asString(row[ROW_FIELD.date]),
+      publication,
+      state: asString(row[ROW_FIELD.state]),
+      wordsLocated: located,
+      excerpts: passages,
+      sourceUrl: source
+    });
+  }
+  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), hits };
+}
+function toResources(value) {
+  if (!Array.isArray(value)) return [];
+  const resources = [];
+  for (const entry of value) {
+    const resource = asObject(entry);
+    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({
+      caption: asString(resource.caption),
+      fileCount,
+      url: asString(resource.url),
+      imageUrl: asString(resource.image)
+    });
+  }
+  return resources;
+}
+function toCitations(value) {
+  const block = asObject(value);
+  if (!block) return {};
+  const citations = {};
+  for (const [style, text] of Object.entries(block)) {
+    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 (asNumber(root.status) === 404) {
+    throw notFound(`The Library of Congress has no record called "${identifier}".`, { url });
+  }
+  const item = asObject(root.item);
+  if (!item) {
+    throw parseFailure(
+      `The record for "${identifier}" came back without the item block this server reads.`,
+      { url }
+    );
+  }
+  if (Object.keys(item).length === 0) {
+    throw notFound(`The Library of Congress has no record called "${identifier}".`, { url });
+  }
+  const description = asStrings(item[ITEM_FIELD.description]).map(plainText).join("\n\n");
+  const title = asString(item[ITEM_FIELD.title]);
+  const source = asString(item[ITEM_FIELD.url]) ?? itemUrl(identifier);
+  return {
+    identifier,
+    title: title === null ? null : plainText(title),
+    creator: asStrings(item[ITEM_FIELD.contributorNames]).map(plainText).join(", ") || null,
+    year: asYear(item[ITEM_FIELD.date]),
+    date: asString(item[ITEM_FIELD.date]),
+    format: asString(item[ITEM_FIELD.originalFormat]),
+    description: description === "" ? null : description,
+    notes: asStrings(item[ITEM_FIELD.notes]).map(plainText),
+    subjects: asLabels(item[ITEM_FIELD.subjects]).slice(0, MOST_SUBJECTS),
+    location: asLabels(item[ITEM_FIELD.location]),
+    language: asLabels(item[ITEM_FIELD.language]),
+    partOf: asLabels(item[ITEM_FIELD.partOf]),
+    repository: asStrings(item[ITEM_FIELD.repository]).map(plainText).join(" ") || null,
+    callNumber: asString(item[ITEM_FIELD.callNumber]),
+    rights: asString(item[ITEM_FIELD.rights]) ?? asString(item[ITEM_FIELD.rightsFallback]),
+    citations: toCitations(root.cite_this),
+    resources: toResources(root.resources),
+    sourceUrl: source.startsWith("//") ? `https:${source}` : source,
+    raw: item
+  };
+}
+function toCollections(payload, url, onSkip) {
+  const rows = rowsOf(payload, url);
+  const collections = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const title = asString(row[ROW_FIELD.title]);
+    if (title === null) {
+      skipped += 1;
+      continue;
+    }
+    const address = asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]);
+    const inner = asObject(row.item);
+    const description = asStrings(row[ROW_FIELD.description]).map(plainText).join("\n\n");
+    collections.push({
+      identifier: identifierFrom(address),
+      title: plainText(title),
+      description: description === "" ? null : description,
+      itemCount: asNumber(row[ROW_FIELD.count]),
+      subjects: asStrings(row[ROW_FIELD.subject]).slice(0, MOST_SUBJECTS),
+      formats: inner ? asStrings(inner.formats) : [],
+      sourceUrl: sourceUrlOf(row, null),
+      itemsUrl: asString(row[ROW_FIELD.items])
+    });
+  }
+  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 });
+  }
+  return { paging: toPaging(payload, url), collections };
+}
+
+// src/loc/rateLimiter.ts
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  lastStartedAt = 0;
+  queue = Promise.resolve();
+  calmStreak = 0;
+  constructor(options) {
+    this.baseIntervalMs = options.intervalMs;
+    this.maxIntervalMs = options.maxIntervalMs ?? options.intervalMs * 8;
+    this.intervalMs = options.intervalMs;
+  }
+  /** The spacing in force, which callers report rather than guess. */
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /**
+   * Run `task` with nothing else in flight.
+   *
+   * This only serialises. Spacing is claimed per attempt through
+   * `beforeRequest`, because a task that retries makes several requests and
+   * each of them owes the site the same gap.
+   */
+  schedule(task) {
+    const result = this.queue.then(task, task);
+    this.queue = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  /** Wait until enough time has passed since the previous request began. */
+  async beforeRequest() {
+    const elapsed = Date.now() - this.lastStartedAt;
+    const wait = Math.min(this.intervalMs, this.intervalMs - elapsed);
+    if (wait > 0) await sleep(wait);
+    this.lastStartedAt = Date.now();
+  }
+  /** Called when the site asks for room: double the gap, up to the ceiling. */
+  pushBack() {
+    this.calmStreak = 0;
+    this.intervalMs = Math.min(this.maxIntervalMs, this.intervalMs * 2);
+  }
+  /**
+   * Called on a clean answer. Recovery takes several in a row, so one lucky
+   * response after a rough patch does not undo the caution that earned it.
+   */
+  succeeded() {
+    if (this.intervalMs === this.baseIntervalMs) return;
+    this.calmStreak += 1;
+    if (this.calmStreak < 3) return;
+    this.calmStreak = 0;
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.round(this.intervalMs / 2));
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/loc/client.ts
+function withGuarantees(config) {
+  const defaults = loadConfig({});
+  const number = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  };
+  const claimed = typeof config.userAgent === "string" ? config.userAgent.trim() : "";
+  const identifier = defaults.userAgent;
+  return {
+    ...config,
+    // A caller may say who they are. Appending rather than replacing means the
+    // Library can always tell which software is calling, and reach someone.
+    userAgent: claimed === "" || claimed.includes(REPO_URL) ? identifier : `${claimed} ${identifier}`,
+    minIntervalMs: Math.max(
+      MIN_ALLOWED_INTERVAL_MS,
+      number(config.minIntervalMs, defaults.minIntervalMs)
+    ),
+    timeoutMs: number(config.timeoutMs, defaults.timeoutMs),
+    newspaperTimeoutMs: number(config.newspaperTimeoutMs, defaults.newspaperTimeoutMs),
+    maxRetries: number(config.maxRetries, defaults.maxRetries),
+    cacheTtlMs: number(config.cacheTtlMs, defaults.cacheTtlMs),
+    cacheMaxEntries: number(config.cacheMaxEntries, defaults.cacheMaxEntries)
+  };
+}
+var LocClient = class {
+  config;
+  logger;
+  limiter;
+  cache;
+  fetchImpl;
+  constructor(options = {}) {
+    const base2 = { ...loadConfig(), ...options.config };
+    this.config = withGuarantees(base2);
+    this.logger = options.logger ?? createLogger(this.config.logLevel);
+    this.limiter = new RateLimiter({ intervalMs: this.config.minIntervalMs });
+    this.cache = new Cache(this.config.cacheTtlMs, this.config.cacheMaxEntries);
+    this.fetchImpl = options.fetchImpl;
+  }
+  /** The pacing in force, which widens when the Library pushes back. */
+  get intervalMs() {
+    return this.limiter.currentIntervalMs;
+  }
+  /** What the Library sees this client call itself. */
+  get userAgent() {
+    return this.config.userAgent;
+  }
+  /**
+   * `cacheKey` is stated rather than taken from the address, because two reads
+   * of one address can produce different values: a passage cut to three hundred
+   * characters is not the same value as the same passage cut to a thousand, and
+   * serving one for the other would answer a budget the caller never set.
+   */
+  async read(cacheKey, url, parse, timeoutMs = this.config.timeoutMs) {
+    const cached = this.cache.get(cacheKey);
+    if (cached !== void 0) {
+      this.logger.debug(`cache hit ${cacheKey}`);
+      return { data: cached, cached: true };
+    }
+    let skipped = 0;
+    const payload = await this.limiter.schedule(
+      () => fetchJson({
+        url,
+        userAgent: this.config.userAgent,
+        timeoutMs,
+        maxRetries: this.config.maxRetries,
+        limiter: this.limiter,
+        logger: this.logger,
+        ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+      })
+    );
+    const data = parse(payload, (n) => {
+      skipped += n;
+      this.logger.warn(`skipped ${n} unreadable row(s) from ${url}`);
+    });
+    this.cache.set(cacheKey, data);
+    return skipped > 0 ? { data, cached: false, skipped } : { data, cached: false };
+  }
+  searchItems(query) {
+    const url = catalogueUrl(query);
+    return this.read(url, url, (payload, onSkip) => toSearchResults(payload, url, onSkip));
+  }
+  searchNewspapers(query, limit, page, budget, filters = {}) {
+    const trimmed = query.trim();
+    if (trimmed === "") {
+      return Promise.reject(invalidInput("Words to look for are required."));
+    }
+    const url = newspaperPagesUrl(trimmed, limit, page, filters);
+    const key = `${url}#${budget.maxChars}x${budget.maxCount}`;
+    return this.read(
+      key,
+      url,
+      (payload, onSkip) => toNewspaperResults(payload, url, trimmed, budget, onSkip),
+      // 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
+    );
+  }
+  getItem(identifier) {
+    const trimmed = identifier.trim();
+    if (trimmed === "") {
+      return Promise.reject(invalidInput("A record identifier is required."));
+    }
+    const url = itemDocumentUrl(trimmed);
+    return this.read(url, url, (payload) => toItemDetail(payload, trimmed, url));
+  }
+  listCollections(limit, page) {
+    const url = collectionsUrl(limit, page);
+    return this.read(url, url, (payload, onSkip) => toCollections(payload, url, onSkip));
+  }
+};
+
+// src/tools/getItem.ts
+import { z as z2 } from "zod";
+
+// src/tools/shared.ts
+import { z } from "zod";
+var MAX_TEXT_CHARS = 2200;
+var ATTRIBUTION = "Source: Library of Congress";
+var recordSchema = z.object({
+  identifier: z.string().nullable().describe(
+    "Pass this to get_item to read the full record. Null when the row names no address a record can be read at."
+  ),
+  title: z.string().nullable(),
+  creator: z.string().nullable().describe("Whoever the Library credits for the work."),
+  year: z.number().int().nullable().describe("Read off 'date' when that date names a year."),
+  date: z.string().nullable().describe("The date as published, which is often a range."),
+  format: z.string().nullable().describe("What the thing is: book, photo, map, newspaper."),
+  location: z.array(z.string()).describe("Places the record is catalogued under."),
+  subjects: z.array(z.string()),
+  online: z.boolean().describe("Whether a digitised copy can be read online."),
+  source_url: z.string().describe("Public page. Show this when citing the record.")
+});
+function indentMarkerLines(body) {
+  return body.replace(/^(Note:|Source:)/gm, " $1");
+}
+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();
+  const trailer = [...noteLines, credit].join("\n");
+  const cut = "\n\n[shortened; the full result is in the structured output]";
+  const budget = MAX_TEXT_CHARS - `
+
+${trailer}`.length;
+  const safe = indentMarkerLines(body);
+  const text = safe.length <= budget ? `${safe}
+
+${trailer}` : `${truncate(safe, Math.max(0, budget - cut.length))}${cut}
+
+${trailer}`;
+  return { content: [{ type: "text", text }], structuredContent: structured };
+}
+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}`);
+  return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
+}
+function truncate(text, maxChars) {
+  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 };
+  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;
+  return { slice: rest.slice(0, cut), nextOffset: offset + cut };
+}
+function renderRecords(records) {
+  return records.map((record, index) => {
+    const bits = [
+      `${index + 1}. ${record.title ?? record.identifier ?? "untitled"}`,
+      record.date ? `(${record.date})` : "",
+      record.creator ? `\xB7 ${record.creator}` : "",
+      record.format ? `\xB7 ${record.format}` : "",
+      record.identifier ? `\xB7 id: ${record.identifier}` : ""
+    ];
+    return `${bits.filter(Boolean).join(" ")}
+   ${record.source_url}`;
+  }).join("\n");
+}
+var OCR_CAVEAT = "Excerpts are the text a machine read off the scanned page, so misreadings are normal and words may be wrong. Quote them as scanned text, and follow source_url to check the page itself.";
+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
+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.",
+  "An identifier can carry slashes: a single newspaper issue is named by its paper, its date and its edition together.",
+  "Sections are opt-in: 'basic' is the default and covers what a description needs.",
+  "'citations' returns the ready-made citations the Library publishes for the record.",
+  "'resources' lists the served copies, such as page images and downloadable files.",
+  "'full_metadata' returns every field the Library publishes for the record, which is large and rarely needed.",
+  "A long description paginates: when 'next_offset' is not null, call again with 'offset' set to it."
+].join(" ");
+var getItemInput = z2.object({
+  identifier: z2.string().min(1).max(300).describe("Record identifier, such as '2017645459' or 'sn83045462/1929-02-03/ed-1'."),
+  sections: z2.array(z2.enum(SECTIONS)).default(["basic"]).describe("Which parts to return. Each one beyond 'basic' adds to the size of the answer."),
+  offset: z2.number().int().min(0).default(0).describe("Where to resume the description."),
+  max_description_chars: z2.number().int().min(200).max(2e4).default(2e3).describe("Characters of the description to return in one call.")
+});
+var getItemOutput = z2.object({
+  item: z2.object({
+    identifier: z2.string(),
+    title: z2.string().nullable(),
+    creator: z2.string().nullable(),
+    year: z2.number().int().nullable(),
+    date: z2.string().nullable(),
+    format: z2.string().nullable(),
+    source_url: z2.string().describe("Public page. Show this when citing the record.")
+  }),
+  description: z2.string().nullable(),
+  offset: z2.number().int(),
+  next_offset: z2.number().int().nullable().describe("Pass as 'offset' to read the rest of the description. Null when it ends here."),
+  notes_on_record: z2.array(z2.string()).describe("Notes the Library published about the record itself."),
+  subjects: z2.array(z2.string()),
+  location: z2.array(z2.string()),
+  language: z2.array(z2.string()),
+  part_of: z2.array(z2.string()).describe("Collections and divisions the record sits in."),
+  repository: z2.string().nullable().describe("Where the original is held."),
+  call_number: z2.string().nullable(),
+  rights: z2.string().nullable().describe(
+    "What the Library says about reuse. Null when it says nothing, which is not permission."
+  ),
+  citations: z2.record(z2.string(), z2.string()).optional(),
+  resources: z2.array(
+    z2.object({
+      caption: z2.string().nullable(),
+      file_count: z2.number().int().nullable(),
+      url: z2.string().nullable(),
+      image_url: z2.string().nullable()
+    })
+  ).optional(),
+  full_metadata: z2.record(z2.string(), z2.unknown()).optional(),
+  notes: z2.array(z2.string())
+});
+async function runGetItem(client, args) {
+  try {
+    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.");
+    const full = data.description ?? "";
+    const { slice, nextOffset } = sliceAtLineBoundary(
+      full,
+      args.offset,
+      args.max_description_chars
+    );
+    if (nextOffset !== null) {
+      notes.push(
+        `The description runs to ${full.length} characters. Call again with offset=${nextOffset} for the rest.`
+      );
+    }
+    if (slice === "" && args.offset > 0 && full.length > 0) {
+      notes.push(
+        `offset=${args.offset} is past the end of a description of ${full.length} characters. Call again with offset=0 to read it from the start.`
+      );
+    }
+    const structured = {
+      item: {
+        identifier: data.identifier,
+        title: data.title,
+        creator: data.creator,
+        year: data.year,
+        date: data.date,
+        format: data.format,
+        source_url: data.sourceUrl
+      },
+      description: slice === "" ? null : slice,
+      offset: args.offset,
+      next_offset: nextOffset,
+      notes_on_record: data.notes,
+      subjects: data.subjects,
+      location: data.location,
+      language: data.language,
+      part_of: data.partOf,
+      repository: data.repository,
+      call_number: data.callNumber,
+      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.rights) notes.push(RIGHTS_CAVEAT);
+    const lines = [
+      [data.title ?? data.identifier, data.date ? `(${data.date})` : ""].filter(Boolean).join(" "),
+      data.creator ? `By ${data.creator}` : "",
+      data.format ? `Kind: ${data.format}` : "",
+      data.subjects.length > 0 ? `Subjects: ${data.subjects.join(", ")}` : "",
+      data.partOf.length > 0 ? `Part of: ${data.partOf.join(", ")}` : "",
+      data.repository ? `Held at: ${data.repository}` : "",
+      data.rights ? `Rights: ${data.rights}` : ""
+    ].filter(Boolean);
+    if (slice !== "") lines.push("", slice);
+    const resources = structured.resources;
+    if (resources && resources.length > 0) {
+      lines.push("", "Copies served online:");
+      for (const resource of resources) {
+        lines.push(`  ${resource.caption ?? "copy"}${resource.url ? ` \u2014 ${resource.url}` : ""}`);
+      }
+    }
+    return ok(structured, lines.join("\n"), { notes, sourceUrl: data.sourceUrl });
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/tools/listCollections.ts
+import { z as z3 } from "zod";
+var listCollectionsDescription = [
+  "List the digital collections of the Library of Congress: bodies of material a curator chose, described and published together.",
+  "Use it to see what is there before searching, since a collection names a corpus that a query would have to guess at.",
+  "'collection_filter' on each row is the wording search_items takes as its 'collection' argument.",
+  "'item_count' is how many records the collection gathers, which is the size of the corpus rather than the number of rows here."
+].join(" ");
+var listCollectionsInput = z3.object({
+  limit: z3.number().int().min(1).max(50).default(20).describe("Collections to return."),
+  page: z3.number().int().min(1).max(100).default(1).describe("Which page of collections, from 1."),
+  max_description_chars: z3.number().int().min(80).max(2e3).default(300).describe("Budget for one collection's description.")
+});
+var listCollectionsOutput = z3.object({
+  total: z3.number().int().describe("Collections the Library publishes, not the number returned."),
+  page: z3.number().int(),
+  collections: z3.array(
+    z3.object({
+      identifier: z3.string().nullable().describe("The slug the collection is addressed by."),
+      title: z3.string(),
+      collection_filter: z3.string().describe("Pass as 'collection' to search_items to keep results within this collection."),
+      description: z3.string().nullable(),
+      item_count: z3.number().int().nullable().describe("Records the collection gathers. Null when the Library states none."),
+      subjects: z3.array(z3.string()),
+      formats: z3.array(z3.string()).describe("Kinds of thing the collection holds."),
+      source_url: z3.string(),
+      items_url: z3.string().nullable().describe("Lists what the collection holds, page by page.")
+    })
+  ),
+  notes: z3.array(z3.string())
+});
+async function runListCollections(client, args) {
+  try {
+    const { data, cached, skipped } = await client.listCollections(args.limit, args.page);
+    const notes = [];
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (skipped) {
+      notes.push(
+        `${skipped} row(s) came back in a shape this server could not read and were left out.`
+      );
+    }
+    const collections = data.collections.map((collection) => ({
+      identifier: collection.identifier,
+      title: collection.title,
+      // The filter takes the collection as the rows spell it, which is the
+      // title in lower case.
+      collection_filter: collection.title.toLowerCase(),
+      description: collection.description === null ? null : truncate(collection.description, args.max_description_chars),
+      item_count: collection.itemCount,
+      subjects: collection.subjects,
+      formats: collection.formats,
+      source_url: collection.sourceUrl,
+      items_url: collection.itemsUrl
+    }));
+    const total = data.paging.resultCount;
+    if (total > collections.length) {
+      notes.push(
+        `${total} collections exist and ${collections.length} are shown. Ask for page ${args.page + 1} to continue.`
+      );
+    }
+    if (collections.length === 0 && total > 0) {
+      notes.push(
+        `Page ${args.page} is past the last collection. ${total} exist, so ask for a lower page.`
+      );
+    }
+    const body = collections.length === 0 ? total > 0 ? `Page ${args.page} is past the last of ${total} collections.` : "The Library published no collection here." : `${collections.length} of ${total} collections:
+` + collections.map((collection, index) => {
+      const head = [
+        `${index + 1}. ${collection.title}`,
+        collection.item_count === null ? "" : `\xB7 ${collection.item_count} records`,
+        collection.formats.length > 0 ? `\xB7 ${collection.formats.join(", ")}` : ""
+      ].filter(Boolean).join(" ");
+      return `${head}
+   ${collection.source_url}`;
+    }).join("\n");
+    return ok({ total, page: args.page, collections, notes }, body, { notes });
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/tools/searchItems.ts
+import { z as z4 } from "zod";
+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.",
+  "This matches titles, creators and catalogue descriptions. It does not read the text inside a scan; use search_newspapers for a phrase printed on a newspaper page.",
+  "'subject', 'location', 'language' and 'collection' take the words the Library itself uses, as they appear on the rows this tool returns. A filter matching nothing is dropped and the answer says so.",
+  "By default only material with a digitised copy is returned; set 'online_only' to false to take in records the Library holds on a shelf alone.",
+  "Every row carries an 'identifier', which get_item takes."
+].join(" ");
+var mediaTypes = FORMAT_ROUTES;
+var searchItemsInput = z4.object({
+  query: z4.string().min(1).max(300).describe("Words to look for in titles, creators and catalogue descriptions."),
+  media_type: z4.enum(mediaTypes).describe(
+    "Which catalogue to search: books, photos, maps, audio, film-and-videos, manuscripts, notated-music or newspapers. 'newspapers' holds the papers themselves; a phrase printed on a page belongs in search_newspapers."
+  ),
+  year_from: z4.number().int().min(1e3).max(9999).optional().describe("Earliest year, inclusive."),
+  year_to: z4.number().int().min(1e3).max(9999).optional().describe("Latest year, inclusive."),
+  subject: z4.string().max(120).optional().describe("A subject heading, such as 'crime'."),
+  location: z4.string().max(120).optional().describe("A place, such as 'oklahoma'."),
+  language: z4.string().max(120).optional().describe("A language, written in English: 'english'."),
+  collection: z4.string().max(160).optional().describe(
+    "A collection, named exactly as list_collections reports it under 'collection_filter'."
+  ),
+  online_only: z4.boolean().default(true).describe("Keep to material with a digitised copy. Set false to include shelf-only records."),
+  sort: z4.enum(["relevance", "newest", "oldest", "title"]).default("relevance").describe("Order of the results."),
+  limit: z4.number().int().min(1).max(50).default(10),
+  page: z4.number().int().min(1).max(100).default(1)
+});
+var searchItemsOutput = z4.object({
+  query: z4.string(),
+  total: z4.number().int().describe("Records matching across this catalogue, not the number returned."),
+  page: z4.number().int(),
+  items: z4.array(recordSchema),
+  notes: z4.array(z4.string())
+});
+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.year_from !== void 0 || args.year_to !== void 0) {
+    written.push(`years ${args.year_from ?? "any"} to ${args.year_to ?? "any"}`);
+  }
+  return written;
+}
+async function runSearchItems(client, args) {
+  try {
+    if (args.year_from !== void 0 && args.year_to !== void 0 && args.year_from > args.year_to) {
+      return toToolError(
+        invalidInput(
+          `year_from ${args.year_from} is later than year_to ${args.year_to}, so no record can match.`,
+          "Put the earlier year in 'year_from'."
+        )
+      );
+    }
+    const facets = {};
+    const put = (field, value) => {
+      if (value && value.trim() !== "") facets[field] = value;
+    };
+    put("subject", args.subject);
+    put("location", args.location);
+    put("language", args.language);
+    put("partof", args.collection);
+    const narrowing = describeNarrowing(args);
+    const wide = {
+      query: args.query,
+      format: args.media_type,
+      onlineOnly: args.online_only,
+      sort: args.sort,
+      limit: args.limit,
+      page: args.page
+    };
+    const narrowed = {
+      ...wide,
+      facets,
+      ...args.year_from !== void 0 ? { yearFrom: args.year_from } : {},
+      ...args.year_to !== void 0 ? { yearTo: args.year_to } : {}
+    };
+    const notes = [];
+    let result = await client.searchItems(narrowed);
+    let narrowingSetAside = false;
+    if (result.data.paging.resultCount === 0 && narrowing.length > 0) {
+      const wider = await client.searchItems(wide);
+      if (wider.data.paging.resultCount > 0) {
+        notes.push(
+          `Nothing matches "${args.query}" with ${narrowing.join(", ")}. Those were set aside and the search was asked again without them, so the rows below are unfiltered. The Library uses its own wording for subjects, places and languages: read 'subjects' and 'location' on a row to see the form it expects.`
+        );
+        result = wider;
+        narrowingSetAside = true;
+      }
+    }
+    const { data, cached, skipped } = result;
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (skipped) {
+      notes.push(
+        `${skipped} row(s) came back in a shape this server could not read and were left out.`
+      );
+    }
+    const items = data.records.map((record) => ({
+      identifier: record.identifier,
+      title: record.title,
+      creator: record.creator,
+      year: record.year,
+      date: record.date,
+      format: record.format,
+      location: record.location,
+      subjects: record.subjects,
+      online: record.online,
+      source_url: record.sourceUrl
+    }));
+    const total = data.paging.resultCount;
+    if (total > items.length) {
+      notes.push(`${total} records match and ${items.length} are shown.`);
+    }
+    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. ${total} records match${pages === null ? "" : ` across ${pages} pages 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 ? `Nothing in the ${args.media_type} catalogue for "${args.query}".` : `${items.length} of ${total} records for "${args.query}":
+${renderRecords(items)}`;
+    return ok({ query: args.query, total, page: args.page, items, notes }, body, { notes });
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/tools/searchNewspapers.ts
+import { z as z5 } from "zod";
+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.",
+  "Put a phrase in double quotes to match it whole; without quotes the words are matched separately, which finds far more.",
+  "'total' counts the pages that match, and they page: ask for page 2, 3 and so on to see beyond the first answer. It is not a count of how many times the words occur.",
+  "Each match names the newspaper, the date, the leaf of the issue and the state it was published in, and 'source_url' opens that leaf with the query applied.",
+  "'location' keeps to papers published in one state, 'publication' to a single paper, and 'year_from' with 'year_to' to a span of years. A filter matching nothing is dropped and the answer says so.",
+  "The Library returns the opening of a page's text with each row rather than the whole page, so the searched words are often further down than the excerpts reach: 'words_located' says which of the two happened for each match.",
+  "Use search_items instead when looking for a work by its title, creator or subject."
+].join(" ");
+var searchNewspapersInput = z5.object({
+  query: z5.string().min(2).max(300).describe(`Words or a quoted phrase, such as '"cure for influenza"'.`),
+  location: z5.string().max(120).optional().describe(
+    "The state a paper was published in, written as the Library writes it: 'new york', 'district of columbia'. It is the value 'state' carries on the matches this tool returns."
+  ),
+  publication: z5.string().max(200).optional().describe(
+    "One newspaper, named with its town and the years it ran: 'new-york tribune (new york [n.y.]) 1866-1924'. Take the wording from 'publication' on a match here, or from a title in search_items with media_type 'newspapers'."
+  ),
+  year_from: z5.number().int().min(1e3).max(9999).optional().describe("Earliest year, inclusive."),
+  year_to: z5.number().int().min(1e3).max(9999).optional().describe("Latest year, inclusive."),
+  limit: z5.number().int().min(1).max(25).default(10).describe("Matches to return."),
+  page: z5.number().int().min(1).max(100).default(1).describe("Which page of matches, from 1."),
+  max_excerpt_chars: z5.number().int().min(80).max(1200).default(300).describe(
+    "Budget for one passage. Read it together with 'max_excerpts_per_match': the size of the answer is the product of the two and the number of matches."
+  ),
+  max_excerpts_per_match: z5.number().int().min(1).max(10).default(3).describe(
+    "Passages to keep per match. A page holding the words several times yields several, and the later ones rarely say anything the first did not."
+  )
+});
+var searchNewspapersOutput = z5.object({
+  query: z5.string(),
+  total: z5.number().int().describe(
+    "Newspaper pages that match, not the number returned and not a count of occurrences. Raise 'page' to read further into it."
+  ),
+  page: z5.number().int(),
+  hits: z5.array(
+    z5.object({
+      identifier: z5.string().nullable().describe("Pass to get_item for the record of the issue this leaf belongs to."),
+      title: z5.string().nullable().describe("How the Library names the leaf, paper and date included."),
+      creator: z5.string().nullable().describe("Whoever contributed the scan, which is a library."),
+      year: z5.number().int().nullable(),
+      page_number: z5.number().int().nullable().describe("The leaf within the issue."),
+      published_on: z5.string().nullable().describe("Date of the issue, as published."),
+      publication: z5.string().nullable().describe("The newspaper, with the years it ran."),
+      state: z5.string().nullable().describe("Where the paper was published."),
+      words_located: z5.boolean().describe(
+        "True when the searched words were found in the text returned with this row, in which case the excerpts are centred on them. False when they sit further down the page than that text reaches, in which case the excerpts are its opening."
+      ),
+      excerpts: z5.array(z5.string()).describe("Passages as a machine read them off the page."),
+      source_url: z5.string().describe("Opens the leaf itself, with the query applied.")
+    })
+  ),
+  notes: z5.array(z5.string())
+});
+function describeNarrowing2(args) {
+  const written = [];
+  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"}`);
+  }
+  return written;
+}
+async function runSearchNewspapers(client, args) {
+  try {
+    if (args.year_from !== void 0 && args.year_to !== void 0 && args.year_from > args.year_to) {
+      return toToolError(
+        invalidInput(
+          `year_from ${args.year_from} is later than year_to ${args.year_to}, so no page can match.`,
+          "Put the earlier year in 'year_from'."
+        )
+      );
+    }
+    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;
+    };
+    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 } : {}
+    };
+    const notes = [];
+    let result = await client.searchNewspapers(args.query, args.limit, args.page, budget, filters);
+    if (result.data.paging.resultCount === 0 && narrowing.length > 0) {
+      const wider = await client.searchNewspapers(args.query, args.limit, args.page, budget);
+      if (wider.data.paging.resultCount > 0) {
+        notes.push(
+          `No page carrying ${args.query} matches ${narrowing.join(", ")}. Those were set aside and the search was asked again without them, so the matches below are unfiltered. The corpus uses its own wording: read 'state' and 'publication' on a match to see the form it expects.`
+        );
+        result = wider;
+      }
+    }
+    const { data, cached, skipped } = result;
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (skipped) {
+      notes.push(
+        `${skipped} match(es) came back in a shape this server could not read and were left out. The count above is what the Library reported.`
+      );
+    }
+    const hits = data.hits.map((hit) => ({
+      identifier: hit.identifier,
+      title: hit.title,
+      creator: hit.creator,
+      year: hit.year,
+      page_number: hit.pageNumber,
+      published_on: hit.publishedOn,
+      publication: hit.publication,
+      state: hit.state,
+      words_located: hit.wordsLocated,
+      excerpts: hit.excerpts.map((excerpt) => truncate(excerpt, args.max_excerpt_chars + 2)),
+      source_url: hit.sourceUrl
+    }));
+    const total = data.paging.resultCount;
+    if (hits.length > 0) notes.push(OCR_CAVEAT);
+    const elsewhere = hits.filter((hit) => !hit.words_located).length;
+    if (elsewhere > 0) {
+      notes.push(
+        `On ${elsewhere} of ${hits.length} match(es) the searched words sit further down the page than the text returned with the row, so those excerpts are the opening of the page rather than the passage that matched. Follow source_url, which opens the leaf with the query applied.`
+      );
+    }
+    if (total > hits.length) {
+      notes.push(
+        `${total} pages match and ${hits.length} are shown. Ask for page ${args.page + 1} to continue: these results page, so the answer in hand is not the whole of it.`
+      );
+    }
+    if (total === 0) {
+      notes.push(
+        "No digitised newspaper page carries these words. An unquoted query matches the words separately, which usually finds more."
+      );
+    }
+    if (hits.length === 0 && total > 0) {
+      notes.push(
+        `Page ${args.page} is past the last match. ${total} pages match, so ask for a lower page.`
+      );
+    }
+    const body = hits.length === 0 ? total > 0 ? `Page ${args.page} is past the last of ${total} newspaper pages carrying ${args.query}.` : `Nothing found in the scanned newspapers for ${args.query}.` : `${hits.length} of ${total} newspaper pages carrying ${args.query}:
+` + hits.map((hit, index) => {
+      const where = [
+        `${index + 1}. ${hit.publication ?? hit.title ?? "untitled"}`,
+        hit.published_on ? `\xB7 ${hit.published_on}` : "",
+        hit.page_number === null ? "" : `\xB7 page ${hit.page_number}`,
+        hit.state ? `\xB7 ${hit.state}` : ""
+      ].filter(Boolean).join(" ");
+      const passages = hit.excerpts.map((excerpt) => `     ${excerpt}`).join("\n");
+      return `${where}
+${passages}
+     ${hit.source_url}`;
+    }).join("\n");
+    return ok({ query: args.query, total, page: args.page, hits, notes }, body, { notes });
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/server.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var INSTRUCTIONS = [
+  "Tools for the Library of Congress. No API key and no account are needed.",
+  "Two questions lead to two different tools, and choosing the wrong one gives a confident empty answer.",
+  "To find a phrase printed on a page of an American newspaper, use search_newspapers: it reads the text scanned off the pages and returns the paper, the date, the leaf and the passage.",
+  "To find a work by its title, creator or subject, use search_items, which requires a 'media_type' because the Library keeps a separate catalogue per kind of thing.",
+  "list_collections shows the corpora a curator built, and each row carries the wording search_items takes as its 'collection' filter.",
+  "search_newspapers reports 'total' as the number of pages that match, and they page: ask for the next page rather than treating the first answer as the whole of it.",
+  "Excerpts come from optical character recognition, so the words can be wrong; repeat them as scanned text and link the page. When 'words_located' is false the searched words sit further down the page than the text this server received, and the excerpt is the opening of that page.",
+  "Metadata here is in the public domain, and individual items are not: a record states its own terms, and a record stating none is not a record granting permission.",
+  "This server paces itself to the ceiling the Library publishes, so answers take a few seconds. A rate_limited error means it was asked to slow down, never that the thing you asked for is missing.",
+  "Every result carries a source_url. Credit the Library of Congress and link what you use."
+].join(" ");
+function createServer(options = {}) {
+  const config = options.config ?? loadConfig();
+  const logger = options.logger ?? createLogger(config.logLevel);
+  const client = new LocClient({
+    config,
+    logger,
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  });
+  const server = new McpServer(
+    { name: "mcp-libraryofcongress", version: PKG_VERSION },
+    { instructions: INSTRUCTIONS }
+  );
+  server.registerTool(
+    "search_newspapers",
+    {
+      title: "Search inside scanned newspaper pages",
+      description: searchNewspapersDescription,
+      inputSchema: searchNewspapersInput,
+      outputSchema: searchNewspapersOutput,
+      annotations: READ_ONLY
+    },
+    async (args) => runSearchNewspapers(client, args)
+  );
+  server.registerTool(
+    "search_items",
+    {
+      title: "Search the catalogue",
+      description: searchItemsDescription,
+      inputSchema: searchItemsInput,
+      outputSchema: searchItemsOutput,
+      annotations: READ_ONLY
+    },
+    async (args) => runSearchItems(client, args)
+  );
+  server.registerTool(
+    "get_item",
+    {
+      title: "Read a record",
+      description: getItemDescription,
+      inputSchema: getItemInput,
+      outputSchema: getItemOutput,
+      annotations: READ_ONLY
+    },
+    async (args) => runGetItem(client, args)
+  );
+  server.registerTool(
+    "list_collections",
+    {
+      title: "List the digital collections",
+      description: listCollectionsDescription,
+      inputSchema: listCollectionsInput,
+      outputSchema: listCollectionsOutput,
+      annotations: READ_ONLY
+    },
+    async (args) => runListCollections(client, args)
+  );
+  logger.info(
+    `ready: user-agent="${config.userAgent}", ${config.minIntervalMs}ms between requests, cache ${config.cacheTtlMs}ms`
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  const shutdown = async () => {
+    await server.close().catch(() => void 0);
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[mcp-libraryofcongress] fatal: ${message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map