mcp-metacritic 2.0.1 → 2.1.0

package/dist/index.js

@@ -8,7 +8,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import process from "process";
 
 // src/version.ts
-var PKG_VERSION = "2.0.1";
+var PKG_VERSION = "2.1.0";
 var REPO_URL = "https://github.com/smeet666/mcp-metacritic";
 
 // src/config.ts
@@ -306,10 +306,28 @@ function sleep(ms) {
 var BACKOFF_BASE_MS = 2e3;
 var BACKOFF_FACTOR = 2;
 var BACKOFF_MAX_MS = 2e4;
+var MAX_BODY_BYTES = 8e6;
 function backoffDelay(attempt, random = Math.random) {
   const capped = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * BACKOFF_FACTOR ** attempt);
   return Math.round(capped * (0.5 + random() * 0.5));
 }
+async function readBounded(response, url) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    throw parseFailure(
+      url,
+      `the response declares ${declared} bytes, past the ${MAX_BODY_BYTES} this server reads`
+    );
+  }
+  const body = await response.text();
+  if (body.length > MAX_BODY_BYTES) {
+    throw parseFailure(
+      url,
+      `the response carries more than the ${MAX_BODY_BYTES} bytes this server reads`
+    );
+  }
+  return body;
+}
 function readAnswer(url, status, body, retryAfterMs, ownGuessMs) {
   if (status === 429 || status === 503 || status === 403) {
     return {
@@ -365,10 +383,10 @@ async function fetchText(url, deps) {
     let askedWaitMs = null;
     for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
       if (attempt > 0) {
-        const delay = askedWaitMs ?? backoffDelay(attempt - 1);
+        const delay = askedWaitMs ?? Math.min(backoffDelay(attempt - 1), BACKOFF_MAX_MS);
         askedWaitMs = null;
         logger.info(`retry ${attempt}/${config.maxRetries} in ${delay}ms for ${url}`);
-        await sleep(Math.min(delay, BACKOFF_MAX_MS));
+        await sleep(delay);
       }
       let status;
       let body;
@@ -385,7 +403,7 @@ async function fetchText(url, deps) {
         });
         status = response.status;
         retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
-        body = await response.text();
+        body = await readBounded(response, url);
       } catch (error) {
         lastError = asTransportError(error, url);
         logger.debug(`${lastError.code} for ${url}: ${lastError.message}`);
@@ -600,6 +618,14 @@ var str = (value) => {
   const trimmed = value.trim();
   return trimmed === "" ? null : trimmed;
 };
+var line = (value) => {
+  const text = str(value);
+  return text === null ? null : text.replace(/\s*[\r\n]+\s*/g, " ");
+};
+var link = (value) => {
+  const text = str(value);
+  return text !== null && ABSOLUTE_URL.test(text) ? text : null;
+};
 var num = (value) => {
   if (typeof value === "number" && Number.isFinite(value)) {
     return value;
@@ -638,8 +664,8 @@ function toSummary(node) {
     return null;
   }
   const id = intOf(node.id);
-  const slug = str(node.slug);
-  const title = str(node.title);
+  const slug = line(node.slug);
+  const title = line(node.title);
   const kind = kindOf(node.type);
   if (id === null || !slug || !title || !kind) {
     return null;
@@ -679,7 +705,7 @@ function parseTitlePage(raw, url, what) {
   }
   return {
     titles,
-    totalResults: intOf(data[FIELD.totalResults]) ?? titles.length,
+    totalResults: intOf(data[FIELD.totalResults]),
     itemCount: items.length
   };
 }
@@ -745,7 +771,7 @@ function parseDetail(raw, url, kind, slug) {
     throw parseFailure(url, "the response carries no item object");
   }
   const id = intOf(item.id);
-  const title = str(item.title);
+  const title = line(item.title);
   if (id === null || !title) {
     throw parseFailure(url, "the entry has no id or no title");
   }
@@ -758,7 +784,7 @@ function parseDetail(raw, url, kind, slug) {
     year: intOf(item.premiereYear),
     releaseDate: str(item.releaseDate),
     rating: str(item.rating),
-    metascore: num(critic.score),
+    metascore: aggregate(critic.score),
     userScore: null,
     sourceUrl: titlePageUrl(kind, slug),
     description: str(item.description),
@@ -783,10 +809,14 @@ function parseScore(raw, url, what) {
   if (max === null) {
     throw parseFailure(url, "the score carries no scale");
   }
+  const reviewCount = intOf(item.reviewCount);
   return {
-    score: aggregate(item.score),
+    // A zero here is read against what stands behind it. An entry nobody has
+    // rated is published as 0 out of 10 from 0 ratings, which is an absence; a
+    // zero with reviews counted behind it is a verdict those reviewers gave.
+    score: reviewCount ? num(item.score) : aggregate(item.score),
     max,
-    reviewCount: intOf(item.reviewCount),
+    reviewCount,
     positiveCount: intOf(item.positiveCount),
     neutralCount: intOf(item.neutralCount),
     negativeCount: intOf(item.negativeCount),
@@ -813,7 +843,7 @@ function parseCriticReviews(raw, url, what, sentiment) {
       continue;
     }
     const quote = str(node.quote);
-    const publication = str(node.publicationName);
+    const publication = line(node.publicationName);
     if (!(quote && publication)) {
       continue;
     }
@@ -821,8 +851,8 @@ function parseCriticReviews(raw, url, what, sentiment) {
       quote,
       score: num(node.score),
       publication,
-      author: str(node.author),
-      url: str(node.url),
+      author: line(node.author),
+      url: link(node.url),
       date: str(node.date)
     });
   }
@@ -831,7 +861,7 @@ function parseCriticReviews(raw, url, what, sentiment) {
   }
   return {
     reviews,
-    totalResults: intOf(data[FIELD.totalResults]) ?? reviews.length,
+    totalResults: intOf(data[FIELD.totalResults]),
     itemCount: bucket.length
   };
 }
@@ -854,22 +884,22 @@ function parseUserReviews(raw, url, what, sentiment) {
   }
   return {
     reviews,
-    totalResults: intOf(data[FIELD.totalResults]) ?? reviews.length,
+    totalResults: intOf(data[FIELD.totalResults]),
     itemCount: bucket.length
   };
 }
-function unwrapLink(link) {
-  if (!link) {
+function unwrapLink(wrapper) {
+  if (!wrapper) {
     return null;
   }
   try {
-    const target = new URL(link).searchParams.get("r");
+    const target = new URL(wrapper).searchParams.get("r");
     if (target && ABSOLUTE_URL.test(target)) {
       return target;
     }
   } catch {
   }
-  return link;
+  return ABSOLUTE_URL.test(wrapper) ? wrapper : null;
 }
 function parseOffers(raw, url, what) {
   const data = envelope(raw, url, what);
@@ -886,7 +916,7 @@ function parseOffers(raw, url, what) {
       if (!isObject(node)) {
         continue;
       }
-      const provider = str(node.providerName);
+      const provider = line(node.providerName);
       if (!provider) {
         continue;
       }
@@ -897,16 +927,23 @@ function parseOffers(raw, url, what) {
 }
 
 // src/mc/client.ts
-var BROWSER_IDENTITY = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i;
 function withGuarantees(config) {
-  const userAgent = BROWSER_IDENTITY.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
+  const userAgent = config.userAgent.includes(DEFAULT_USER_AGENT) ? config.userAgent : `${config.userAgent} ${DEFAULT_USER_AGENT}`;
+  const asked = Number.isFinite(config.minIntervalMs) ? config.minIntervalMs : 0;
   return {
     ...config,
     userAgent,
-    minIntervalMs: Math.max(MIN_ALLOWED_INTERVAL_MS, config.minIntervalMs)
+    minIntervalMs: Math.max(MIN_ALLOWED_INTERVAL_MS, asked)
   };
 }
 var McClient = class {
+  /**
+   * The reads that have gone out and not come back, by URL.
+   *
+   * A route answering several variants is read once, so this is keyed on the
+   * URL rather than on the cache key a variant makes.
+   */
+  reading = /* @__PURE__ */ new Map();
   config;
   logger;
   limiter;
@@ -949,9 +986,10 @@ var McClient = class {
   }
   async browse(options) {
     const url = browseUrl(options);
+    const cache = options.sort === "score" ? this.catalogueCache : this.scoresCache;
     return await this.fetchParsed(
       url,
-      this.catalogueCache,
+      cache,
       (body) => parseTitlePage(body, url, `that ${options.kind} listing`)
     );
   }
@@ -1020,12 +1058,24 @@ var McClient = class {
       this.logger.debug(`cache hit ${key}`);
       return { data: hit, cached: true };
     }
-    const body = await fetchText(url, {
+    const inFlight = this.reading.get(url);
+    if (inFlight !== void 0) {
+      const body2 = await inFlight;
+      return { data: parse(body2), cached: true };
+    }
+    const reading = fetchText(url, {
       config: this.config,
       limiter: this.limiter,
       logger: this.logger,
       ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
     });
+    this.reading.set(url, reading);
+    let body;
+    try {
+      body = await reading;
+    } finally {
+      this.reading.delete(url);
+    }
     const data = parse(body);
     cache.set(key, data);
     return { data, cached: false };
@@ -1171,7 +1221,7 @@ function indentMarkerLines(body) {
   return body.replace(/^(Note:|Source:)/gm, " $1");
 }
 function ok(structured, body, options = {}) {
-  const attribution = options.sourceUrl ? `${ATTRIBUTION} \u2014 ${options.sourceUrl}` : ATTRIBUTION;
+  const attribution = options.sourceUrl ? `${ATTRIBUTION} (${options.sourceUrl})` : ATTRIBUTION;
   const noteLines = (options.notes ?? []).map((note) => `Note: ${note}`);
   while (noteLines.length > 0 && noteLines.join("\n").length > MAX_TEXT_MIRROR_CHARS / 2) {
     noteLines.pop();
@@ -1202,7 +1252,8 @@ function toToolError(error) {
   if (known.details.hint) {
     lines.push(`Hint: ${known.details.hint}`);
   }
-  return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
+  const safe = truncate(indentMarkerLines(lines.join("\n")), MAX_TEXT_MIRROR_CHARS);
+  return { content: [{ type: "text", text: safe }], isError: true };
 }
 function truncate(text, maxChars) {
   if (text.length <= maxChars) {
@@ -1290,7 +1341,7 @@ async function runBrowseTitles(client, args) {
       limit: args.limit,
       offset: args.offset
     });
-    const results = data.titles.map(toTitleSummaryOut);
+    const results = data.titles.slice(0, args.limit).map(toTitleSummaryOut);
     const notes = [];
     if (cached) {
       notes.push("Served from this server's short-lived in-memory cache.");
@@ -1305,13 +1356,14 @@ async function runBrowseTitles(client, args) {
         `${data.itemCount - data.titles.length} entries on this page could not be read and were skipped.`
       );
     }
-    const nextOffset = data.itemCount < args.limit ? null : args.offset + data.itemCount;
+    const nextOffset = data.itemCount < args.limit ? null : args.offset + args.limit;
     const heading = [
       args.genre ? `${args.genre} ` : "",
       `${args.kind}s`,
       orderedBy(args.sort)
     ].join("");
-    const summary = results.length === 0 ? `No rows for ${heading}.` : `${results.length} of ${data.totalResults} ${heading}:
+    const outOf = data.totalResults === null ? "" : ` of ${data.totalResults}`;
+    const summary = results.length === 0 ? `No rows for ${heading}.` : `${results.length}${outOf} ${heading}:
 ${renderTitleList(results)}`;
     return ok(
       {
@@ -1351,15 +1403,20 @@ var getReviewsInput = strictInput({
   limit: z4.number().int().min(1).max(50).default(10).describe("How many reviews to return from the sample Metacritic publishes."),
   offset: z4.number().int().min(0).default(0).describe("How many of the sampled reviews to skip. The sample itself cannot be paged past.")
 });
-var reviewSchema = z4.object({
+var saidSchema = {
   quote: z4.string().nullable().describe("Excerpt as published, truncated if long."),
   score: z4.number().nullable(),
   max: z4.number().describe("Scale for this review's score: 100 for critics, 10 for users."),
+  date: z4.string().nullable()
+};
+var criticReviewSchema = z4.object({
+  ...saidSchema,
   publication: z4.string().nullable().describe("Who ran it. Name it when quoting."),
   author: z4.string().nullable(),
-  url: z4.string().nullable().describe("Original article. Link it when quoting."),
-  date: z4.string().nullable()
+  url: z4.string().nullable().describe("Original article. Link it when quoting.")
 });
+var userReviewSchema = z4.object(saidSchema);
+var reviewSchema = z4.union([criticReviewSchema, userReviewSchema]);
 var getReviewsOutputShape = {
   slug: z4.string(),
   kind: z4.string(),
@@ -1385,15 +1442,22 @@ async function runGetReviews(client, args) {
     const max = args.source === "critic" ? 100 : 10;
     const { data, cached } = args.source === "critic" ? await client.getCriticReviews(request) : await client.getUserReviews(request);
     const sampled = data.reviews.slice(args.offset, args.offset + args.limit);
-    const reviews = sampled.map((review) => ({
-      quote: review.quote === null ? null : truncate(review.quote, MAX_QUOTE_CHARS),
-      score: review.score,
-      max,
-      publication: "publication" in review ? review.publication : null,
-      author: "author" in review ? review.author : null,
-      url: "url" in review ? review.url : null,
-      date: review.date
-    }));
+    const credits = (review) => "publication" in review ? review : null;
+    const reviews = sampled.map((review) => {
+      const said = {
+        quote: review.quote === null ? null : truncate(review.quote, MAX_QUOTE_CHARS),
+        score: review.score,
+        max,
+        date: review.date
+      };
+      const credited = credits(review);
+      return credited === null ? said : {
+        ...said,
+        publication: credited.publication,
+        author: credited.author,
+        url: credited.url
+      };
+    });
     const notes = [];
     if (cached) {
       notes.push("Served from this server's short-lived in-memory cache.");
@@ -1416,7 +1480,11 @@ async function runGetReviews(client, args) {
         `${data.itemCount - data.reviews.length} entries in the sample could not be attributed and were skipped.`
       );
     }
-    if (data.totalResults > data.reviews.length) {
+    if (data.totalResults === null) {
+      notes.push(
+        "Metacritic published no count of the reviews it holds for this entry, so the length of this sample is not evidence of how many exist."
+      );
+    } else if (data.totalResults > data.reviews.length) {
       const slice = args.sentiment === "all" ? "" : ` in the ${args.sentiment} slice`;
       notes.push(
         `Metacritic counts ${data.totalResults} ${args.source} reviews for this entry and serves ${data.reviews.length}${slice} here. The rest are only on the website: ${sourceUrl}`
@@ -1425,12 +1493,13 @@ async function runGetReviews(client, args) {
     const consumed = args.offset + reviews.length;
     const nextOffset = consumed < data.reviews.length ? consumed : null;
     const listing = reviews.map((review, index) => {
-      const who = [review.publication, review.author].filter(Boolean).join(", ");
+      const credited = credits(sampled[index]);
+      const who = [credited?.publication, credited?.author].filter(Boolean).join(", ");
       const head = `${index + 1}. ${review.score === null ? "" : `${review.score}/${max} `}${who || "anonymous"}`;
-      const quoted = (review.quote ?? "").split("\n").map((line) => `   ${line}`).join("\n");
+      const quoted = (review.quote ?? "").split("\n").map((line2) => `   ${line2}`).join("\n");
       return `${head}
 ${quoted}
-   ${review.url ?? sourceUrl}`;
+   ${credited?.url ?? sourceUrl}`;
     }).join("\n");
     const summary = reviews.length === 0 ? `No ${args.source} review to show for "${args.slug}".` : `${reviews.length} ${args.source} review${reviews.length === 1 ? "" : "s"} of "${args.slug}":
 ${listing}`;
@@ -1515,16 +1584,16 @@ var getTitleInput = strictInput({
 });
 var getTitleOutputShape = {
   title: titleSummarySchema,
-  description: z5.string().nullable(),
-  tagline: z5.string().nullable(),
-  genres: z5.array(z5.string()),
-  duration_minutes: z5.number().int().nullable().describe("Runtime in minutes for a film, or the length of a typical episode for a show."),
-  imdb_id: z5.string().nullable().describe("IMDb identifier, usable to cross-reference other sources."),
-  total_chars: z5.number().int().describe("Length of the full description."),
-  returned_chars: z5.number().int(),
+  description: z5.string().nullable().optional(),
+  tagline: z5.string().nullable().optional(),
+  genres: z5.array(z5.string()).optional(),
+  duration_minutes: z5.number().int().nullable().optional().describe("Runtime in minutes for a film, or the length of a typical episode for a show."),
+  imdb_id: z5.string().nullable().optional().describe("IMDb identifier, usable to cross-reference other sources."),
+  total_chars: z5.number().int().optional().describe("Length of the full description."),
+  returned_chars: z5.number().int().optional(),
   offset: z5.number().int(),
-  next_offset: z5.number().int().nullable().describe("Pass as 'offset' to read the rest."),
-  truncated: z5.boolean(),
+  next_offset: z5.number().int().nullable().optional().describe("Pass as 'offset' to read the rest."),
+  truncated: z5.boolean().optional(),
   critic_score: scoreSchema.nullable(),
   user_score: scoreSchema.nullable(),
   awards: z5.array(
@@ -1552,8 +1621,14 @@ async function runGetTitle(client, args) {
     let userScore = null;
     if (wanted.has("scores")) {
       [criticScore, userScore] = await Promise.all([
-        optionalScore(client, args.kind, args.slug, "critic", notes),
-        optionalScore(client, args.kind, args.slug, "user", notes)
+        optionalScore(client, args.kind, args.slug, "critic", {
+          notes,
+          onEntryPage: item.metascore
+        }),
+        optionalScore(client, args.kind, args.slug, "user", {
+          notes,
+          onEntryPage: item.userScore
+        })
       ]);
     }
     const basic = wanted.has("basic");
@@ -1570,29 +1645,32 @@ async function runGetTitle(client, args) {
         maxChars: args.max_chars
       })
     );
+    const entry = basic ? {
+      description: slice === "" ? null : slice,
+      tagline: item.tagline,
+      genres: item.genres,
+      duration_minutes: item.duration,
+      imdb_id: item.imdbId,
+      total_chars: full.length,
+      returned_chars: slice.length,
+      next_offset: nextOffset,
+      truncated: nextOffset !== null
+    } : {};
     const structured = {
       title: {
         ...toTitleSummaryOut(item),
         metascore: criticScore?.score ?? item.metascore,
         user_score: userScore?.score ?? null
       },
-      description: basic && slice !== "" ? slice : null,
-      tagline: basic ? item.tagline : null,
-      genres: basic ? item.genres : [],
-      duration_minutes: basic ? item.duration : null,
-      imdb_id: basic ? item.imdbId : null,
-      total_chars: basic ? full.length : 0,
-      returned_chars: basic ? slice.length : 0,
+      ...entry,
       offset: args.offset,
-      next_offset: basic ? nextOffset : null,
-      truncated: basic && nextOffset !== null,
       critic_score: criticScore ? toScoreOut(criticScore) : null,
       user_score: userScore ? toScoreOut(userScore) : null,
       notes
     };
     const production = attachAskedSections(structured, item, wanted, notes);
-    const offers = wanted.has("where_to_watch") ? await watchOffers(client, item, args.kind, notes) : [];
-    if (wanted.has("where_to_watch")) {
+    const offers = wanted.has("where_to_watch") ? await watchOffers(client, item, args.kind, notes) : null;
+    if (offers !== null) {
       structured.where_to_watch = offers;
     }
     return ok(
@@ -1600,7 +1678,8 @@ async function runGetTitle(client, args) {
       render(item, slice, wanted, {
         critic: criticScore,
         user: userScore,
-        offers,
+        offers: offers ?? [],
+        offersRead: offers !== null,
         production
       }),
       {
@@ -1612,13 +1691,16 @@ async function runGetTitle(client, args) {
     return toToolError(error);
   }
 }
-async function optionalScore(client, kind, slug, source, notes) {
+async function optionalScore(client, kind, slug, source, said) {
+  const { notes, onEntryPage } = said;
   try {
     const { data } = await client.getScore(kind, slug, source);
     return data;
   } catch (error) {
     if (error instanceof McError && error.code === "not_found") {
-      notes.push(`Metacritic publishes no ${source} score for this entry.`);
+      notes.push(
+        onEntryPage === null ? `Metacritic publishes no ${source} score for this entry.` : `Metacritic publishes no ${source} score breakdown for this entry, so the number stands without the review counts behind it.`
+      );
     } else {
       const reason = error instanceof McError ? error.code : "an unexpected error";
       notes.push(
@@ -1641,8 +1723,10 @@ async function watchOffers(client, item, kind, notes) {
     const { data } = await client.getWatchOffers(item.imdbId, kind);
     return data;
   } catch {
-    notes.push("Streaming offers could not be read for this entry.");
-    return [];
+    notes.push(
+      "Streaming offers could not be read for this entry, so they are missing here rather than absent from Metacritic. Call again to retry."
+    );
+    return null;
   }
 }
 function renderAwards(item, wanted) {
@@ -1661,7 +1745,7 @@ function renderAwards(item, wanted) {
     })
   ];
 }
-function renderAskedSections(item, wanted, offers, production) {
+function renderAskedSections(item, wanted, offers, offersRead, production) {
   const lines = [];
   lines.push(...renderAwards(item, wanted));
   if (wanted.has("networks") && item.networks.length > 0) {
@@ -1673,16 +1757,16 @@ function renderAskedSections(item, wanted, offers, production) {
       production.length === 0 ? "Production: no company credited." : `Production: ${production.map((company) => company.name).join(", ")}`
     );
   }
-  if (wanted.has("where_to_watch")) {
+  if (wanted.has("where_to_watch") && offersRead) {
     lines.push("", offers.length === 0 ? "Where to watch: nothing listed." : "Where to watch:");
     for (const o of offers) {
-      lines.push(`  ${o.provider} (${o.kind})${o.url ? ` \u2014 ${o.url}` : ""}`);
+      lines.push(`  ${o.provider} (${o.kind})${o.url ? `: ${o.url}` : ""}`);
     }
   }
   return lines;
 }
 function render(item, description, wanted, said) {
-  const { critic, user, offers, production } = said;
+  const { critic, user, offers, offersRead, production } = said;
   const yearShown = item.year !== null && !item.title.includes(`(${item.year})`);
   const header = [item.title, yearShown ? `(${item.year})` : "", `\xB7 ${item.kind}`].filter(Boolean).join(" ");
   const lines = [header];
@@ -1707,7 +1791,7 @@ function render(item, description, wanted, said) {
   if (description) {
     lines.push("", description);
   }
-  lines.push(...renderAskedSections(item, wanted, offers, production));
+  lines.push(...renderAskedSections(item, wanted, offers, offersRead, production));
   return lines.join("\n");
 }
 
@@ -1746,11 +1830,25 @@ async function runSearchTitles(client, args) {
     if (cached) {
       notes.push("Served from this server's short-lived in-memory cache.");
     }
+    if (data.itemCount > data.titles.length) {
+      notes.push(
+        `${data.itemCount - data.titles.length} entries in this page could not be read and were skipped.`
+      );
+    }
+    if (args.kind !== "any" && data.totalResults !== null) {
+      notes.push(
+        `total_available counts every kind Metacritic matched for this query, and the rows here are the ${args.kind}s among them.`
+      );
+    }
     const looseCount = WHITESPACE.test(args.query.trim());
     if (looseCount) {
       notes.push(
         "Metacritic counts a multi-word query loosely, so total_available is far larger than the number of real matches. The rows themselves are ordered by relevance."
       );
+    } else if (data.totalResults === null) {
+      notes.push(
+        "Metacritic published no count of what this search matched, so a short list here is not evidence that little exists."
+      );
     } else if (data.totalResults > results.length) {
       notes.push(
         `${data.totalResults} entries matched and ${results.length} are shown. Raise 'limit' for more, or narrow the query: this tool cannot page.`