mcp-libraryofcongress 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 2.1.2
+
+- A search the Library could not run is reported as a failure instead of as an
+  empty catalogue. Under load the site answers with a rendered page holding no
+  rows and a pagination block counting zero results, written in exactly the
+  words a search that genuinely matched nothing is written in: the collections
+  listing, which holds 584 collections and takes no query at all, came back as
+  `of: 0` beside an empty `results`, and the server published that as the
+  Library having gathered no collection. What separates the two is what the site
+  says about keeping the answer. A search it stands behind may be kept for a
+  day; the page it renders while its search is failing carries `no-cache` and a
+  lifetime of zero. A count of zero read off such a page is now `rate_limited`,
+  which says the site could not answer and says nothing about what the Library
+  holds. The catalogue, newspaper and collections searches all read their count
+  from that block, so all three are covered. A search that really matches
+  nothing still answers with a count of zero.
+- The nightly live canary tells a contract that moved apart from a site that
+  could not answer. A route that came back rate limited, unreachable or out of
+  time leaves that case out of the run and names it on stderr, so only an answer
+  this server could not read fails the canary and opens an issue. Each assertion
+  states the field or the behaviour it holds the site to.
+
+## 2.1.1
+
+- The README carries the same badge row as every server here: npm, CI, the
+  licence, the MCP registry entry, the Glama score, and one-click installs for
+  Cursor and VS Code. Each install link encodes this package. npm serves the
+  README frozen at publish time, so a release is what puts it there.
+
 ## 2.1.0
 
 - A catalogue row pointing at a collection no longer claims an identifier

package/README.md

@@ -2,9 +2,12 @@
 
 [![npm](https://img.shields.io/npm/v/mcp-libraryofcongress.svg)](https://www.npmjs.com/package/mcp-libraryofcongress)
 [![CI](https://github.com/smeet666/mcp-libraryofcongress/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-libraryofcongress/actions/workflows/ci.yml)
-[![license](https://img.shields.io/npm/l/mcp-libraryofcongress.svg)](LICENSE)
+[![license](https://img.shields.io/npm/l/mcp-libraryofcongress.svg)](./LICENSE)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-libraryofcongress)
 [![Glama](https://glama.ai/mcp/servers/smeet666/mcp-libraryofcongress/badges/score.svg)](https://glama.ai/mcp/servers/smeet666/mcp-libraryofcongress)
+[![M8ven Score](https://m8ven.ai/badge/mcp/smeet666-mcp-libraryofcongress-1rr3lc)](https://m8ven.ai/mcp/smeet666-mcp-libraryofcongress-1rr3lc)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=libraryofcongress&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1saWJyYXJ5b2Zjb25ncmVzcyJdfQ%3D%3D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=libraryofcongress&config=%7B%22name%22%3A%22libraryofcongress%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-libraryofcongress%22%5D%7D)
 
 An MCP server for the [Library of Congress](https://www.loc.gov). **Search the
 text scanned off digitised American newspaper pages**, search the catalogue by
@@ -297,8 +300,11 @@ console.log(data.paging.resultCount, data.hits[0]?.sourceUrl);
 ## Troubleshooting
 
 **`rate_limited`.** The site asked this client to slow down, or this server was
-asked for more than its pacing allows. It says nothing about whether the Library
-holds what you asked for. Wait and ask again.
+asked for more than its pacing allows. It also covers a search the site could
+not run: it answers then with a page holding no rows and refuses to have that
+page kept, and a count of nothing read off it would say the Library holds
+nothing. It says nothing about whether the Library holds what you asked for.
+Wait and ask again.
 
 **`parse_failure`.** A response arrived in a shape this server cannot read,
 which includes a long answer cut off in transit. It usually means a route
@@ -657,7 +663,10 @@ console.log(data.paging.resultCount, data.hits[0]?.sourceUrl);
 ## Dépannage
 
 **`rate_limited`.** Le site demande à ce client de ralentir, ou ce serveur a été
-sollicité au-delà de sa cadence. Cela ne dit rien de ce que la Library conserve.
+sollicité au-delà de sa cadence. Ce code couvre aussi une recherche que le site
+n'a pas pu exécuter : il répond alors par une page sans aucune ligne et refuse
+qu'elle soit conservée, et un compte de zéro lu sur cette page affirmerait que
+la Library ne conserve rien. Cela ne dit rien de ce que la Library conserve.
 Attendez et redemandez.
 
 **`parse_failure`.** Une réponse est arrivée dans une forme illisible pour ce

package/dist/index.js

@@ -7,7 +7,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/version.ts
-var PKG_VERSION = "2.1.0";
+var PKG_VERSION = "2.1.2";
 var REPO_URL = "https://github.com/smeet666/mcp-libraryofcongress";
 
 // src/config.ts
@@ -168,6 +168,12 @@ function backoffMs(attempt) {
   const base2 = Math.min(16e3, 1e3 * 2 ** attempt);
   return base2 + Math.floor(Math.random() * 500);
 }
+function statesASettledAnswer(cacheControl) {
+  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));
+}
 async function fetchText(options) {
   const { url, userAgent, timeoutMs, maxRetries, limiter, logger } = options;
   const doFetch = options.fetchImpl ?? fetch;
@@ -191,7 +197,8 @@ async function fetchText(options) {
       });
       if (response.ok) {
         limiter.succeeded();
-        return await response.text();
+        const settled = statesASettledAnswer(response.headers.get("cache-control"));
+        return { payload: await response.text(), settled };
       }
       if (PUSH_BACK.has(response.status)) {
         limiter.pushBack();
@@ -267,9 +274,9 @@ async function fetchText(options) {
   );
 }
 async function fetchJson(options) {
-  const body = await fetchText(options);
+  const { payload, settled } = await fetchText(options);
   try {
-    return JSON.parse(body);
+    return { payload: JSON.parse(payload), settled };
   } catch {
     throw parseFailure("The Library of Congress answered with something that is not JSON.", {
       url: options.url
@@ -648,7 +655,7 @@ function dateCode(filed) {
 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) {
+function toPaging(payload, url, settled = true) {
   const root = asObject(payload);
   const pagination = root ? asObject(root.pagination) : null;
   if (!pagination) {
@@ -663,6 +670,12 @@ function toPaging(payload, url) {
   if (resultCount === null) {
     throw parseFailure("The answer carried no readable count of results.", { url });
   }
+  if (resultCount === 0 && !settled) {
+    throw rateLimited(
+      "The Library of Congress answered with no results and asked that the answer not be kept, which is how the site answers while its search is failing.",
+      { url }
+    );
+  }
   return {
     resultCount,
     pageCount: asNumber(pagination.total),
@@ -695,7 +708,7 @@ function statedDateOfRow(row) {
   const both = [...words, ...spans];
   return both.length > 0 ? both.join("; ") : null;
 }
-function toSearchResults(payload, url, onSkip) {
+function toSearchResults(payload, url, onSkip, settled = true) {
   const rows = rowsOf(payload, url);
   const records = [];
   let skipped = 0;
@@ -730,7 +743,7 @@ function toSearchResults(payload, url, onSkip) {
   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 };
+  return { paging: toPaging(payload, url, settled), records };
 }
 var JOINING_WORDS = /* @__PURE__ */ new Set([
   "the",
@@ -826,7 +839,7 @@ function excerptsFor(text, terms, budget) {
   });
   return { passages, located: true };
 }
-function toNewspaperResults(payload, url, query, budget, onSkip) {
+function toNewspaperResults(payload, url, query, budget, onSkip, settled = true) {
   const rows = rowsOf(payload, url);
   const terms = queryTerms(query);
   const hits = [];
@@ -862,7 +875,7 @@ function toNewspaperResults(payload, url, query, budget, onSkip) {
   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 };
+  return { paging: toPaging(payload, url, settled), hits };
 }
 function toResources(value) {
   if (!Array.isArray(value)) return [];
@@ -940,7 +953,7 @@ function toItemDetail(payload, identifier, url) {
     raw: item
   };
 }
-function toCollections(payload, url, onSkip) {
+function toCollections(payload, url, onSkip, settled = true) {
   const rows = rowsOf(payload, url);
   const collections = [];
   let skipped = 0;
@@ -968,7 +981,7 @@ function toCollections(payload, url, onSkip) {
   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 };
+  return { paging: toPaging(payload, url, settled), collections };
 }
 
 // src/loc/rateLimiter.ts
@@ -1091,7 +1104,7 @@ var LocClient = class {
       return { data: cached, cached: true };
     }
     let skipped = 0;
-    const payload = await this.limiter.schedule(
+    const { payload, settled } = await this.limiter.schedule(
       () => fetchJson({
         url,
         userAgent: this.config.userAgent,
@@ -1102,16 +1115,24 @@ var LocClient = class {
         ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
       })
     );
-    const data = parse(payload, (n) => {
-      skipped += n;
-      this.logger.warn(`skipped ${n} unreadable row(s) from ${url}`);
-    });
+    const data = parse(
+      payload,
+      (n) => {
+        skipped += n;
+        this.logger.warn(`skipped ${n} unreadable row(s) from ${url}`);
+      },
+      settled
+    );
     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));
+    return this.read(
+      url,
+      url,
+      (payload, onSkip, settled) => toSearchResults(payload, url, onSkip, settled)
+    );
   }
   searchNewspapers(query, limit, page, budget, filters = {}) {
     const trimmed = query.trim();
@@ -1123,7 +1144,7 @@ var LocClient = class {
     return this.read(
       key,
       url,
-      (payload, onSkip) => toNewspaperResults(payload, url, trimmed, budget, onSkip),
+      (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
@@ -1139,7 +1160,11 @@ var LocClient = class {
   }
   listCollections(limit, page) {
     const url = collectionsUrl(limit, page);
-    return this.read(url, url, (payload, onSkip) => toCollections(payload, url, onSkip));
+    return this.read(
+      url,
+      url,
+      (payload, onSkip, settled) => toCollections(payload, url, onSkip, settled)
+    );
   }
 };