mcp-metacritic 1.0.0

package/dist/index.js

@@ -0,0 +1,1526 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/version.ts
+var PKG_VERSION = "1.0.0";
+var REPO_URL = "https://github.com/smeet666/mcp-metacritic";
+
+// src/config.ts
+var DEFAULT_USER_AGENT = `mcp-metacritic v${PKG_VERSION} (${REPO_URL})`;
+var DEFAULTS = {
+  minIntervalMs: 1e3,
+  timeoutMs: 15e3,
+  maxRetries: 3,
+  // A catalogue entry moves when a title is edited, which is rare, so a day is
+  // safe. The cache lives in memory and dies with the process, so this is a
+  // ceiling on one session rather than a stored copy of the site.
+  cacheTtlMs: 24 * 60 * 60 * 1e3,
+  // Scores and reviews move as reviews come in, especially around a release,
+  // so they get their own much shorter lifetime.
+  scoresCacheTtlMs: 60 * 60 * 1e3,
+  cacheMaxEntries: 200,
+  logLevel: "error"
+};
+var MIN_ALLOWED_INTERVAL_MS = 500;
+var MAX_ALLOWED_INTERVAL_MS = 6e4;
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+function readNumber(name, env, range) {
+  const raw = env[name];
+  if (raw === void 0 || raw.trim() === "") return range.fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`${name}="${raw}" is not a number, using ${range.fallback}`);
+    return range.fallback;
+  }
+  const rounded = Math.round(parsed);
+  if (rounded < range.min || rounded > range.max) {
+    warn(
+      `${name}=${raw} is outside the accepted range ${range.min}-${range.max} and was ignored; using ${range.fallback}`
+    );
+    return range.fallback;
+  }
+  return rounded;
+}
+function warn(message) {
+  process.stderr.write(`[mcp-metacritic] ${message}
+`);
+}
+function readInterval(env) {
+  const raw = env.MC_MIN_INTERVAL_MS;
+  if (raw === void 0 || raw.trim() === "") return DEFAULTS.minIntervalMs;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`MC_MIN_INTERVAL_MS="${raw}" is not a number, using ${DEFAULTS.minIntervalMs}ms`);
+    return DEFAULTS.minIntervalMs;
+  }
+  const rounded = Math.round(parsed);
+  if (rounded < MIN_ALLOWED_INTERVAL_MS) {
+    warn(
+      `MC_MIN_INTERVAL_MS=${raw} is below the ${MIN_ALLOWED_INTERVAL_MS}ms floor and was ignored; using ${DEFAULTS.minIntervalMs}ms. Metacritic publishes no rate limit, so this client sets its own.`
+    );
+    return DEFAULTS.minIntervalMs;
+  }
+  if (rounded > MAX_ALLOWED_INTERVAL_MS) {
+    warn(
+      `MC_MIN_INTERVAL_MS=${raw} exceeds the ${MAX_ALLOWED_INTERVAL_MS}ms ceiling; using ${MAX_ALLOWED_INTERVAL_MS}ms.`
+    );
+    return MAX_ALLOWED_INTERVAL_MS;
+  }
+  return rounded;
+}
+function loadConfig(env = process.env) {
+  const rawUserAgent = env.MC_USER_AGENT?.trim();
+  const rawLogLevel = env.MC_LOG_LEVEL?.trim().toLowerCase();
+  let logLevel = DEFAULTS.logLevel;
+  if (rawLogLevel) {
+    if (LOG_LEVELS.includes(rawLogLevel)) {
+      logLevel = rawLogLevel;
+    } else {
+      warn(`MC_LOG_LEVEL="${rawLogLevel}" is unknown, using "${DEFAULTS.logLevel}"`);
+    }
+  }
+  return {
+    userAgent: rawUserAgent || DEFAULT_USER_AGENT,
+    minIntervalMs: readInterval(env),
+    timeoutMs: readNumber("MC_TIMEOUT_MS", env, {
+      min: 1e3,
+      max: 12e4,
+      fallback: DEFAULTS.timeoutMs
+    }),
+    maxRetries: readNumber("MC_MAX_RETRIES", env, {
+      min: 0,
+      max: 10,
+      fallback: DEFAULTS.maxRetries
+    }),
+    cacheTtlMs: readNumber("MC_CACHE_TTL_MS", env, {
+      min: 0,
+      max: 7 * 24 * 60 * 60 * 1e3,
+      fallback: DEFAULTS.cacheTtlMs
+    }),
+    scoresCacheTtlMs: readNumber("MC_SCORES_CACHE_TTL_MS", env, {
+      min: 0,
+      max: 24 * 60 * 60 * 1e3,
+      fallback: DEFAULTS.scoresCacheTtlMs
+    }),
+    cacheMaxEntries: readNumber("MC_CACHE_MAX_ENTRIES", env, {
+      min: 0,
+      max: 1e4,
+      fallback: DEFAULTS.cacheMaxEntries
+    }),
+    logLevel
+  };
+}
+var LEVEL_RANK = { silent: 0, error: 1, info: 2, debug: 3 };
+function createLogger(level) {
+  const emit = (at, message) => {
+    if (LEVEL_RANK[level] >= LEVEL_RANK[at]) {
+      process.stderr.write(`[mcp-metacritic] ${message}
+`);
+    }
+  };
+  return {
+    error: (message) => emit("error", message),
+    info: (message) => emit("info", message),
+    debug: (message) => emit("debug", message)
+  };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/mc/cache.ts
+var TtlLruCache = class {
+  constructor(maxEntries, ttlMs) {
+    this.maxEntries = maxEntries;
+    this.ttlMs = ttlMs;
+  }
+  maxEntries;
+  ttlMs;
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() >= entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.maxEntries <= 0 || this.ttlMs <= 0) return;
+    this.store.delete(key);
+    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next();
+      if (oldest.done) break;
+      this.store.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.store.size;
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/errors.ts
+var McError = class extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "McError";
+  }
+  code;
+  details;
+};
+var ISSUES_URL = "https://github.com/smeet666/mcp-metacritic/issues";
+function notFound(url, what) {
+  return new McError("not_found", `Metacritic has no entry for ${what}.`, {
+    url,
+    status: 404,
+    hint: "Use search_titles to find an entry, then pass its slug and kind to this tool."
+  });
+}
+function invalidInput(message, hint) {
+  return new McError("invalid_input", message, hint ? { hint } : {});
+}
+function rateLimited(url, retryAfterMs) {
+  return new McError(
+    "rate_limited",
+    "Metacritic is refusing requests from this client for now. This does NOT mean the title is missing.",
+    {
+      url,
+      retryAfterMs,
+      hint: `Wait about ${Math.ceil(retryAfterMs / 1e3)} seconds, then call the same tool again with the same arguments. If it keeps happening, raise MC_MIN_INTERVAL_MS.`
+    }
+  );
+}
+function parseFailure(url, what) {
+  return new McError(
+    "parse_failure",
+    `Metacritic answered, but the response did not have the expected shape (${what}).`,
+    { url, hint: `Please report this, with the request you made, at ${ISSUES_URL}` }
+  );
+}
+function upstreamError(url, status) {
+  return new McError("network_error", `Metacritic returned HTTP ${status}.`, {
+    url,
+    status,
+    ...status >= 500 ? { hint: "This is a problem on Metacritic's side. Try again shortly." } : {}
+  });
+}
+
+// src/mc/rateLimiter.ts
+var DEFAULT_MAX_INTERVAL_MS = 1e4;
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  /** Tail of the queue: each task chains onto the previous one. */
+  tail = Promise.resolve();
+  lastStart = 0;
+  constructor(options) {
+    this.baseIntervalMs = Math.max(0, options.minIntervalMs);
+    this.maxIntervalMs = Math.max(
+      this.baseIntervalMs,
+      options.maxIntervalMs ?? DEFAULT_MAX_INTERVAL_MS
+    );
+    this.intervalMs = this.baseIntervalMs;
+  }
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /**
+   * Queue a task. Tasks run in call order, one at a time.
+   *
+   * A task may send several requests, since the retry loop lives inside its
+   * slot. It must call `beforeRequest` around each of them: the pacing is
+   * measured between requests, and stamping only the start of the task would
+   * let the next one follow a long retry chain's final request immediately.
+   */
+  schedule(task) {
+    const run = this.tail.then(async () => task());
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /**
+   * Wait for this request's slot, then claim it.
+   *
+   * Called once per upstream request rather than once per task, so every
+   * request is paced from the previous one whether or not they belong to the
+   * same retry chain.
+   */
+  async beforeRequest() {
+    await this.waitForSlot();
+    this.lastStart = Date.now();
+  }
+  /** Called after the site signals it is under load. */
+  penalize() {
+    const next = this.intervalMs === 0 ? 250 : this.intervalMs * 2;
+    this.intervalMs = Math.min(this.maxIntervalMs, next);
+  }
+  /** Called after a success, so a single hiccup does not slow things down forever. */
+  relax() {
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
+  }
+  async waitForSlot() {
+    if (this.intervalMs === 0 || this.lastStart === 0) return;
+    const elapsed = Date.now() - this.lastStart;
+    const remaining = Math.min(this.intervalMs, this.intervalMs - elapsed);
+    if (remaining > 0) await sleep(remaining);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/mc/http.ts
+var BACKOFF_BASE_MS = 2e3;
+var BACKOFF_FACTOR = 2;
+var BACKOFF_MAX_MS = 2e4;
+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 fetchText(url, deps) {
+  const { config, limiter, logger } = deps;
+  const doFetch = deps.fetchImpl ?? fetch;
+  return limiter.schedule(async () => {
+    let lastError;
+    let askedWaitMs = null;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+      if (attempt > 0) {
+        const delay = askedWaitMs ?? backoffDelay(attempt - 1);
+        askedWaitMs = null;
+        logger.info(`retry ${attempt}/${config.maxRetries} in ${delay}ms for ${url}`);
+        await sleep(Math.min(delay, BACKOFF_MAX_MS));
+      }
+      let status;
+      let body;
+      let retryAfterMs = null;
+      try {
+        await limiter.beforeRequest();
+        const response = await doFetch(url, {
+          headers: {
+            "User-Agent": config.userAgent,
+            Accept: "application/json,*/*;q=0.8"
+          },
+          redirect: "follow",
+          signal: AbortSignal.timeout(config.timeoutMs)
+        });
+        status = response.status;
+        retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+        body = await response.text();
+      } catch (error) {
+        lastError = asTransportError(error, url);
+        logger.debug(`${lastError.code} for ${url}: ${lastError.message}`);
+        continue;
+      }
+      if (status === 429 || status === 503 || status === 403) {
+        limiter.penalize();
+        askedWaitMs = retryAfterMs;
+        lastError = rateLimited(url, retryAfterMs ?? backoffDelay(attempt));
+        logger.info(
+          `refused on ${url} with ${status}, interval now ${limiter.currentIntervalMs}ms`
+        );
+        continue;
+      }
+      if (status >= 500) {
+        lastError = upstreamError(url, status);
+        continue;
+      }
+      if (status === 404) throw notFound(url, "that request");
+      if (status >= 400) throw upstreamError(url, status);
+      const trimmed = body.trim();
+      if (trimmed === "") {
+        limiter.penalize();
+        lastError = rateLimited(url, backoffDelay(attempt));
+        logger.info(`empty body on ${url}, treating as a refusal`);
+        continue;
+      }
+      if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+        limiter.penalize();
+        lastError = parseFailure(url, "the body is not JSON");
+        askedWaitMs = retryAfterMs;
+        logger.info(`non-JSON body on ${url}, retrying`);
+        continue;
+      }
+      limiter.relax();
+      return body;
+    }
+    throw lastError ?? new McError("network_error", `Could not fetch ${url}.`, { url });
+  });
+}
+function parseRetryAfter(raw) {
+  if (!raw) return null;
+  const seconds = Number(raw.trim());
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  const when = Date.parse(raw);
+  if (Number.isNaN(when)) return null;
+  return Math.max(0, when - Date.now());
+}
+function asTransportError(error, url) {
+  if (error instanceof McError) return error;
+  const name = error instanceof Error ? error.name : "";
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new McError("timeout", "Metacritic did not answer in time.", {
+      url,
+      hint: "Raise MC_TIMEOUT_MS if this happens often on a slow connection."
+    });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new McError("network_error", `Could not reach Metacritic: ${message}`, { url });
+}
+
+// src/mc/paths.ts
+var API_BASE = "https://backend.metacritic.com";
+var SITE_BASE = "https://www.metacritic.com";
+var API_SEGMENT = {
+  movie: "movies",
+  show: "shows",
+  game: "games"
+};
+var SITE_SEGMENT = {
+  movie: "movie",
+  show: "tv",
+  game: "game"
+};
+var MCO_TYPE_ID = {
+  show: 1,
+  movie: 2,
+  game: 13
+};
+var SEARCH_TYPE = {
+  movie: "movie",
+  show: "show",
+  game: "game-title"
+};
+var SORT_BY = {
+  score: "-metaScore",
+  recent: "-releaseDate",
+  popular: "-popularityCount"
+};
+var COMPONENT = {
+  product: { componentName: "product", componentType: "Product" },
+  criticStats: { componentName: "critic-score-summary", componentType: "MetaScoreSummary" },
+  userStats: { componentName: "user-score-summary", componentType: "MetaScoreSummary" },
+  criticReviews: { componentName: "critic-reviews", componentType: "ProductReviewsSummary" },
+  userReviews: { componentName: "user-reviews", componentType: "ProductReviewsSummary" }
+};
+var FIELD = {
+  data: "data",
+  errors: "errors",
+  item: "item",
+  items: "items",
+  totalResults: "totalResults",
+  /** Reviews arrive pre-sorted into these buckets, which is the sentiment filter. */
+  reviewBuckets: { all: "default", positive: "positive", neutral: "neutral", negative: "negative" }
+};
+
+// src/mc/urls.ts
+function build(path, params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== "") query.set(key, String(value));
+  }
+  const suffix = query.toString();
+  return suffix ? `${API_BASE}${path}?${suffix}` : `${API_BASE}${path}`;
+}
+function checkSlug(slug) {
+  const trimmed = slug.trim();
+  if (trimmed === "") {
+    throw invalidInput("The slug is empty.", "Take it from a search_titles result.");
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(trimmed)) {
+    throw invalidInput(
+      `"${slug}" does not look like a Metacritic slug.`,
+      "Slugs are lowercase words joined by hyphens, such as the-matrix. Use search_titles to get one."
+    );
+  }
+  return trimmed;
+}
+function searchUrl(query, limit, offset) {
+  const trimmed = query.trim();
+  if (trimmed === "") {
+    throw invalidInput("The search query is empty.", "Pass a title or part of one.");
+  }
+  return build(`/finder/metacritic/search/${encodeURIComponent(trimmed)}/web`, { limit, offset });
+}
+function browseUrl(options) {
+  return build("/finder/metacritic/web", {
+    sortBy: SORT_BY[options.sort],
+    mcoTypeId: MCO_TYPE_ID[options.kind],
+    genres: options.genre,
+    limit: options.limit,
+    offset: options.offset
+  });
+}
+function detailUrl(kind, slug) {
+  return build(`/${API_SEGMENT[kind]}/metacritic/${checkSlug(slug)}/web`, COMPONENT.product);
+}
+function scoreUrl(kind, slug, source) {
+  const component = source === "critic" ? COMPONENT.criticStats : COMPONENT.userStats;
+  return build(
+    `/reviews/metacritic/${source}/${API_SEGMENT[kind]}/${checkSlug(slug)}/stats/web`,
+    component
+  );
+}
+function reviewsUrl(options) {
+  const component = options.source === "critic" ? COMPONENT.criticReviews : COMPONENT.userReviews;
+  return build(
+    `/reviews/metacritic/${options.source}/${API_SEGMENT[options.kind]}/${checkSlug(options.slug)}/summary/web`,
+    component
+  );
+}
+function watchUrl(imdbId, kind) {
+  const trimmed = imdbId.trim();
+  if (!/^tt\d+$/.test(trimmed)) {
+    throw invalidInput(
+      `"${imdbId}" is not an IMDb id.`,
+      "IMDb ids look like tt0133093. get_title returns one as imdb_id."
+    );
+  }
+  return build("/justwatch/metacritic/offersByIMDbId", {
+    id: trimmed,
+    type: kind === "show" ? "show" : "movie"
+  });
+}
+function titlePageUrl(kind, slug) {
+  return `${SITE_BASE}/${SITE_SEGMENT[kind]}/${slug}/`;
+}
+function bucketFor(sentiment) {
+  return sentiment === "all" ? "default" : sentiment;
+}
+
+// src/mc/parse.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function envelope(raw, url, what) {
+  let body;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    throw parseFailure(url, "the body is not valid JSON");
+  }
+  if (!isObject(body)) throw parseFailure(url, "the body is not an object");
+  const errors = body[FIELD.errors];
+  if (Array.isArray(errors) && errors.length > 0) {
+    const first = isObject(errors[0]) ? errors[0] : {};
+    if (first.code === 404) throw notFound(url, what);
+    throw parseFailure(
+      url,
+      `the site reported ${String(first.reason ?? first.code ?? "an error")}`
+    );
+  }
+  const data = body[FIELD.data];
+  if (!isObject(data)) throw parseFailure(url, "the response carries no data object");
+  return data;
+}
+var str = (value) => {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+};
+var num = (value) => {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+};
+var intOf = (value) => {
+  const parsed = num(value);
+  return parsed === null ? null : Math.trunc(parsed);
+};
+function kindOf(value) {
+  const type = str(value);
+  if (type === SEARCH_TYPE.movie) return "movie";
+  if (type === SEARCH_TYPE.show) return "show";
+  if (type === SEARCH_TYPE.game) return "game";
+  return null;
+}
+function toSummary(node) {
+  if (!isObject(node)) return null;
+  const id = intOf(node.id);
+  const slug = str(node.slug);
+  const title = str(node.title);
+  const kind = kindOf(node.type);
+  if (id === null || !slug || !title || !kind) return null;
+  const critic = isObject(node.criticScoreSummary) ? node.criticScoreSummary : {};
+  const userSummary = isObject(node.userScoreSummary) ? node.userScoreSummary : {};
+  const userObject = isObject(node.userScore) ? node.userScore : {};
+  const userScore = num(userSummary.score) ?? num(userObject.score) ?? num(node.userScore);
+  return {
+    id,
+    kind,
+    title,
+    slug,
+    year: intOf(node.premiereYear),
+    releaseDate: str(node.releaseDate),
+    rating: str(node.rating),
+    metascore: num(critic.score),
+    userScore,
+    sourceUrl: titlePageUrl(kind, slug)
+  };
+}
+function parseTitlePage(raw, url, what) {
+  const data = envelope(raw, url, what);
+  const items = data[FIELD.items];
+  if (!Array.isArray(items)) throw parseFailure(url, "the response carries no items array");
+  const titles = [];
+  for (const node of items) {
+    const row = toSummary(node);
+    if (row) titles.push(row);
+  }
+  if (items.length > 0 && titles.length === 0) {
+    throw parseFailure(url, `${items.length} rows but none could be read`);
+  }
+  return {
+    titles,
+    totalResults: intOf(data[FIELD.totalResults]) ?? titles.length,
+    itemCount: items.length
+  };
+}
+function toCompanies(value) {
+  const source = isObject(value) ? value.companies : value;
+  if (!Array.isArray(source)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const node of source) {
+    const name = isObject(node) ? str(node.name) : str(node);
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ name, id: isObject(node) ? intOf(node.id) : null });
+  }
+  return out;
+}
+function toStringList(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const node of value) {
+    const name = isObject(node) ? str(node.name) : str(node);
+    if (name) out.push(name);
+  }
+  return out;
+}
+function toAwards(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const node of value) {
+    if (!isObject(node)) continue;
+    const ceremony = str(node.awardEvent);
+    if (!ceremony) continue;
+    out.push({
+      ceremony,
+      wins: intOf(node.wins),
+      nominations: intOf(node.nominations)
+    });
+  }
+  return out;
+}
+function parseDetail(raw, url, kind, slug) {
+  const data = envelope(raw, url, `${kind} "${slug}"`);
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no item object");
+  const id = intOf(item.id);
+  const title = str(item.title);
+  if (id === null || !title) throw parseFailure(url, "the entry has no id or no title");
+  const critic = isObject(item.criticScoreSummary) ? item.criticScoreSummary : {};
+  return {
+    id,
+    kind,
+    title,
+    slug,
+    year: intOf(item.premiereYear),
+    releaseDate: str(item.releaseDate),
+    rating: str(item.rating),
+    metascore: num(critic.score),
+    userScore: null,
+    sourceUrl: titlePageUrl(kind, slug),
+    description: str(item.description),
+    tagline: str(item.tagline),
+    genres: toStringList(item.genres),
+    duration: intOf(item.duration),
+    imdbId: str(item.imdbId),
+    networks: toStringList(item.networks),
+    production: toCompanies(item.production),
+    awards: toAwards(item.awards),
+    criticScoreDetail: null,
+    userScoreDetail: null
+  };
+}
+function parseScore(raw, url, what) {
+  const data = envelope(raw, url, what);
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no score object");
+  const max = num(item.max);
+  if (max === null) throw parseFailure(url, "the score carries no scale");
+  return {
+    score: num(item.score),
+    max,
+    reviewCount: intOf(item.reviewCount),
+    positiveCount: intOf(item.positiveCount),
+    neutralCount: intOf(item.neutralCount),
+    negativeCount: intOf(item.negativeCount),
+    sentiment: str(item.sentiment)
+  };
+}
+function reviewBucket(data, url, sentiment) {
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no reviews object");
+  const bucket = item[bucketFor(sentiment)];
+  if (!Array.isArray(bucket)) {
+    throw parseFailure(url, `there is no "${bucketFor(sentiment)}" group of reviews`);
+  }
+  return bucket;
+}
+function parseCriticReviews(raw, url, what, sentiment) {
+  const data = envelope(raw, url, what);
+  const bucket = reviewBucket(data, url, sentiment);
+  const reviews = [];
+  for (const node of bucket) {
+    if (!isObject(node)) continue;
+    const quote = str(node.quote);
+    const publication = str(node.publicationName);
+    if (!quote || !publication) continue;
+    reviews.push({
+      quote,
+      score: num(node.score),
+      publication,
+      author: str(node.author),
+      url: str(node.url),
+      date: str(node.date)
+    });
+  }
+  if (bucket.length > 0 && reviews.length === 0) {
+    throw parseFailure(url, `${bucket.length} reviews but none could be read`);
+  }
+  return {
+    reviews,
+    totalResults: intOf(data[FIELD.totalResults]) ?? reviews.length,
+    itemCount: bucket.length
+  };
+}
+function parseUserReviews(raw, url, what, sentiment) {
+  const data = envelope(raw, url, what);
+  const bucket = reviewBucket(data, url, sentiment);
+  const reviews = [];
+  for (const node of bucket) {
+    if (!isObject(node)) continue;
+    const quote = str(node.quote);
+    if (!quote) continue;
+    reviews.push({ quote, score: num(node.score), date: str(node.date) });
+  }
+  if (bucket.length > 0 && reviews.length === 0) {
+    throw parseFailure(url, `${bucket.length} reviews but none could be read`);
+  }
+  return {
+    reviews,
+    totalResults: intOf(data[FIELD.totalResults]) ?? reviews.length,
+    itemCount: bucket.length
+  };
+}
+function unwrapLink(link) {
+  if (!link) return null;
+  try {
+    const target = new URL(link).searchParams.get("r");
+    if (target && /^https?:\/\//i.test(target)) return target;
+  } catch {
+  }
+  return link;
+}
+function parseOffers(raw, url, what) {
+  const data = envelope(raw, url, what);
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no offers object");
+  const offers = [];
+  for (const [group, value] of Object.entries(item)) {
+    if (!Array.isArray(value)) continue;
+    for (const node of value) {
+      if (!isObject(node)) continue;
+      const provider = str(node.providerName);
+      if (!provider) continue;
+      offers.push({ provider, kind: group, url: unwrapLink(str(node.link)) });
+    }
+  }
+  return offers;
+}
+
+// src/mc/client.ts
+function withGuarantees(config) {
+  const userAgent = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
+  return {
+    ...config,
+    userAgent,
+    minIntervalMs: Math.max(MIN_ALLOWED_INTERVAL_MS, config.minIntervalMs)
+  };
+}
+var McClient = class {
+  config;
+  logger;
+  limiter;
+  /**
+   * Two caches, because the two kinds of data age at different speeds. A
+   * catalogue entry changes when someone edits it, which is rare. A score moves
+   * every time a review lands, which around a release is constantly.
+   */
+  catalogueCache;
+  scoresCache;
+  fetchImpl;
+  constructor(options = {}) {
+    this.config = withGuarantees(options.config ?? loadConfig());
+    this.logger = options.logger ?? createLogger(this.config.logLevel);
+    this.limiter = new RateLimiter({ minIntervalMs: this.config.minIntervalMs });
+    this.catalogueCache = new TtlLruCache(
+      this.config.cacheMaxEntries,
+      this.config.cacheTtlMs
+    );
+    this.scoresCache = new TtlLruCache(
+      this.config.cacheMaxEntries,
+      this.config.scoresCacheTtlMs
+    );
+    this.fetchImpl = options.fetchImpl;
+  }
+  /**
+   * Search across films, shows and games.
+   *
+   * The return type carries rows only. The upstream response embeds artwork
+   * variants on every match, and dropping them here rather than in a tool means
+   * they have no path out of this layer.
+   */
+  async search(query, limit, offset) {
+    const url = searchUrl(query, limit, offset);
+    return this.fetchParsed(
+      url,
+      this.catalogueCache,
+      (body) => parseTitlePage(body, url, `the query "${query}"`)
+    );
+  }
+  async browse(options) {
+    const url = browseUrl(options);
+    return this.fetchParsed(
+      url,
+      this.catalogueCache,
+      (body) => parseTitlePage(body, url, `that ${options.kind} listing`)
+    );
+  }
+  async getDetail(kind, slug) {
+    const url = detailUrl(kind, slug);
+    const clean = slug.trim();
+    return this.fetchParsed(
+      url,
+      this.catalogueCache,
+      (body) => parseDetail(body, url, kind, clean)
+    );
+  }
+  async getScore(kind, slug, source) {
+    const url = scoreUrl(kind, slug, source);
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseScore(body, url, `the ${source} score of ${kind} "${slug}"`)
+    );
+  }
+  async getCriticReviews(options) {
+    const url = reviewsUrl({ ...options, source: "critic" });
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseCriticReviews(
+        body,
+        url,
+        `reviews of ${options.kind} "${options.slug}"`,
+        options.sentiment
+      ),
+      options.sentiment
+    );
+  }
+  async getUserReviews(options) {
+    const url = reviewsUrl({ ...options, source: "user" });
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseUserReviews(
+        body,
+        url,
+        `reviews of ${options.kind} "${options.slug}"`,
+        options.sentiment
+      ),
+      options.sentiment
+    );
+  }
+  async getWatchOffers(imdbId, kind) {
+    const url = watchUrl(imdbId, kind);
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseOffers(body, url, `streaming offers for ${imdbId}`)
+    );
+  }
+  /**
+   * Fetch, parse, then cache. In that order: a response that could not be read
+   * is never stored, so a bad minute upstream cannot be replayed from memory
+   * for the rest of the cache lifetime.
+   */
+  async fetchParsed(url, cache, parse, variant = "") {
+    const key = variant ? `${url}#${variant}` : url;
+    const hit = cache.get(key);
+    if (hit !== void 0) {
+      this.logger.debug(`cache hit ${key}`);
+      return { data: hit, cached: true };
+    }
+    const body = await fetchText(url, {
+      config: this.config,
+      limiter: this.limiter,
+      logger: this.logger,
+      ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+    });
+    const data = parse(body);
+    cache.set(key, data);
+    return { data, cached: false };
+  }
+};
+
+// src/tools/browseTitles.ts
+import { z as z2 } from "zod";
+
+// src/tools/shared.ts
+import { z } from "zod";
+var MAX_TEXT_MIRROR_CHARS = 2e3;
+var ATTRIBUTION = "Source: Metacritic";
+var kindSchema = z.enum(["movie", "show", "game"]).describe("Which catalogue the entry belongs to. Pass it back with the slug.");
+var titleSummarySchema = z.object({
+  id: z.number().int(),
+  kind: z.enum(["movie", "show", "game"]),
+  title: z.string(),
+  slug: z.string().describe("Identifier to pass to get_title and get_reviews, with 'kind'."),
+  year: z.number().int().nullable(),
+  release_date: z.string().nullable(),
+  rating: z.string().nullable().describe("Age rating as published, such as R or TV-MA."),
+  metascore: z.number().nullable().describe("Critic score, out of 100. Not comparable to user_score without rescaling."),
+  user_score: z.number().nullable().describe("Audience score, out of 10. Not comparable to metascore without rescaling."),
+  source_url: z.string().describe("Metacritic page. Show this when citing the entry.")
+});
+function toTitleSummaryOut(title) {
+  return {
+    id: title.id,
+    kind: title.kind,
+    title: title.title,
+    slug: title.slug,
+    year: title.year,
+    release_date: title.releaseDate,
+    rating: title.rating,
+    metascore: title.metascore,
+    user_score: title.userScore,
+    source_url: title.sourceUrl
+  };
+}
+var scoreSchema = z.object({
+  score: z.number().nullable(),
+  max: z.number().describe("Scale this score is on: 100 for critics, 10 for users."),
+  review_count: z.number().int().nullable(),
+  positive_count: z.number().int().nullable(),
+  neutral_count: z.number().int().nullable(),
+  negative_count: z.number().int().nullable(),
+  sentiment: z.string().nullable().describe("Metacritic's own wording for the verdict.")
+});
+function toScoreOut(score) {
+  return {
+    score: score.score,
+    max: score.max,
+    review_count: score.reviewCount,
+    positive_count: score.positiveCount,
+    neutral_count: score.neutralCount,
+    negative_count: score.negativeCount,
+    sentiment: score.sentiment
+  };
+}
+function ok(structured, body, trailer = ATTRIBUTION) {
+  const cutMarker = "\n\n[shortened; the full result is in the structured output]";
+  const reserved = `
+
+${trailer}`.length;
+  const budget = MAX_TEXT_MIRROR_CHARS - reserved;
+  let text;
+  if (body.length <= budget) {
+    text = `${body}
+
+${trailer}`;
+  } else {
+    const kept = truncate(body, Math.max(0, budget - cutMarker.length));
+    text = `${kept}${cutMarker}
+
+${trailer}`;
+  }
+  return { content: [{ type: "text", text }], structuredContent: structured };
+}
+function toToolError(error) {
+  const known = error instanceof McError ? error : new McError("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, 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 renderTitleList(titles) {
+  return titles.map((title, index) => {
+    const scores = [
+      title.metascore === null ? "" : `critics ${title.metascore}/100`,
+      title.user_score === null ? "" : `users ${title.user_score}/10`
+    ].filter(Boolean);
+    const yearShown = title.year !== null && !title.title.includes(`(${title.year})`);
+    const parts = [
+      `${index + 1}. ${title.title}`,
+      yearShown ? `(${title.year})` : "",
+      `\xB7 ${title.kind}`,
+      scores.length > 0 ? `\xB7 ${scores.join(", ")}` : "",
+      `\xB7 slug: ${title.slug}`
+    ];
+    return parts.filter(Boolean).join(" ");
+  }).join("\n");
+}
+
+// src/tools/browseTitles.ts
+var browseTitlesDescription = [
+  "List films, shows or games by score, by release date or by current popularity.",
+  "Use this when there is no specific title to look up: best rated, newest, what people are looking at now.",
+  "Filter by genre with a single name such as Horror, Comedy or Action.",
+  "Sorting by score returns the all-time ranking, which is dominated by older titles: combine with a genre to narrow it.",
+  "Scores come back on their own scales, 100 for critics and 10 for users.",
+  "Paging is approximate: Metacritic does not order tied entries stably, so an entry can appear on two consecutive pages. Deduplicate by slug rather than counting rows."
+].join(" ");
+var browseTitlesInputShape = {
+  kind: z2.enum(["movie", "show", "game"]).default("movie").describe("Which catalogue to list."),
+  sort: z2.enum(["score", "recent", "popular"]).default("score").describe(
+    "'score' is the critic ranking, 'recent' is by release date, 'popular' is current attention."
+  ),
+  genre: z2.string().optional().describe("Single genre name, such as Horror. Omit for all genres."),
+  limit: z2.number().int().min(1).max(50).default(20).describe("How many rows to return."),
+  offset: z2.number().int().min(0).default(0).describe("How many rows to skip, for paging.")
+};
+var browseTitlesOutputShape = {
+  kind: z2.string(),
+  sort: z2.string(),
+  genre: z2.string().nullable(),
+  results: z2.array(titleSummarySchema),
+  total_available: z2.number().int().describe("How many entries match upstream, which is the size of what this samples."),
+  offset: z2.number().int(),
+  next_offset: z2.number().int().nullable().describe(
+    "Pass as 'offset' for the next page. Tied entries are not ordered stably upstream, so deduplicate by slug across pages."
+  ),
+  notes: z2.array(z2.string())
+};
+async function runBrowseTitles(client, args) {
+  try {
+    const { data, cached } = await client.browse({
+      kind: args.kind,
+      sort: args.sort,
+      ...args.genre ? { genre: args.genre } : {},
+      limit: args.limit,
+      offset: args.offset
+    });
+    const results = data.titles.map(toTitleSummaryOut);
+    const notes = [];
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (results.length === 0) {
+      notes.push(
+        args.genre ? `No ${args.kind} matched the genre "${args.genre}" at this offset. Check the spelling, or drop the genre.` : "The listing returned no rows at this offset."
+      );
+    }
+    if (data.itemCount > data.titles.length) {
+      notes.push(
+        `${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 heading = [
+      args.genre ? `${args.genre} ` : "",
+      `${args.kind}s`,
+      args.sort === "score" ? " by critic score" : args.sort === "recent" ? " by release date" : " by current popularity"
+    ].join("");
+    const summary = results.length === 0 ? `No rows for ${heading}.` : `${results.length} of ${data.totalResults} ${heading}:
+${renderTitleList(results)}`;
+    return ok(
+      {
+        kind: args.kind,
+        sort: args.sort,
+        genre: args.genre ?? null,
+        results,
+        total_available: data.totalResults,
+        offset: args.offset,
+        next_offset: nextOffset,
+        notes
+      },
+      summary
+    );
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/tools/getReviews.ts
+import { z as z3 } from "zod";
+var MAX_QUOTE_CHARS = 600;
+var getReviewsDescription = [
+  "Read individual reviews of a Metacritic entry, from critics or from users.",
+  "Get the slug and kind from search_titles first.",
+  "Filter with 'sentiment' to read only what praised or panned it, which Metacritic groups itself.",
+  "Metacritic returns a fixed sample rather than the full list, so 'total_available' is usually far larger than what comes back, and there is no way to page past the sample.",
+  "Critic reviews carry the publication and a link to the original article: quote them with both.",
+  "Critic scores run to 100 and user scores to 10, so do not average the two together."
+].join(" ");
+var getReviewsInputShape = {
+  slug: z3.string().min(1).describe("Identifier from search_titles, such as 'the-matrix'."),
+  kind: kindSchema,
+  source: z3.enum(["critic", "user"]).default("critic").describe("'critic' is the professional press, 'user' is the audience."),
+  sentiment: z3.enum(["all", "positive", "neutral", "negative"]).default("all").describe("Which slice to read. Metacritic groups reviews this way itself."),
+  limit: z3.number().int().min(1).max(50).default(10).describe("How many reviews to return from the sample Metacritic publishes."),
+  offset: z3.number().int().min(0).default(0).describe("How many of the sampled reviews to skip. The sample itself cannot be paged past.")
+};
+var reviewSchema = z3.object({
+  quote: z3.string().nullable().describe("Excerpt as published, truncated if long."),
+  score: z3.number().nullable(),
+  max: z3.number().describe("Scale for this review's score: 100 for critics, 10 for users."),
+  publication: z3.string().nullable().describe("Who ran it. Name it when quoting."),
+  author: z3.string().nullable(),
+  url: z3.string().nullable().describe("Original article. Link it when quoting."),
+  date: z3.string().nullable()
+});
+var getReviewsOutputShape = {
+  slug: z3.string(),
+  kind: z3.string(),
+  source_url: z3.string().describe("Metacritic page these reviews belong to. Cite it when an article link is missing."),
+  source: z3.string(),
+  sentiment: z3.string(),
+  reviews: z3.array(reviewSchema),
+  total_available: z3.number().int().describe("How many reviews Metacritic counts in total. Usually far more than it serves here."),
+  offset: z3.number().int(),
+  next_offset: z3.number().int().nullable().describe("Pass as 'offset' for the next page."),
+  notes: z3.array(z3.string())
+};
+async function runGetReviews(client, args) {
+  try {
+    const sourceUrl = titlePageUrl(args.kind, args.slug.trim());
+    const request = {
+      kind: args.kind,
+      slug: args.slug,
+      sentiment: args.sentiment,
+      limit: args.limit,
+      offset: args.offset
+    };
+    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 notes = [];
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (reviews.length === 0) {
+      if (args.offset > 0 && args.offset >= data.reviews.length) {
+        notes.push(
+          `offset=${args.offset} is past the end of a sample of ${data.reviews.length} ${args.source} reviews. Call again with offset=0.`
+        );
+      } else if (args.sentiment === "all") {
+        notes.push("Metacritic publishes no review in this slice.");
+      } else {
+        notes.push(
+          `Metacritic publishes no ${args.sentiment} review here. Call again with sentiment="all" to see the rest.`
+        );
+      }
+    }
+    if (data.itemCount > data.reviews.length) {
+      notes.push(
+        `${data.itemCount - data.reviews.length} entries in the sample could not be attributed and were skipped.`
+      );
+    }
+    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}`
+      );
+    }
+    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 head = `${index + 1}. ${review.score === null ? "" : `${review.score}/${max} `}${who || "anonymous"}`;
+      const quoted = (review.quote ?? "").split("\n").map((line) => `   ${line}`).join("\n");
+      return `${head}
+${quoted}
+   ${review.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}`;
+    return ok(
+      {
+        slug: args.slug,
+        kind: args.kind,
+        source_url: sourceUrl,
+        source: args.source,
+        sentiment: args.sentiment,
+        reviews,
+        total_available: data.totalResults,
+        offset: args.offset,
+        next_offset: nextOffset,
+        notes
+      },
+      summary
+    );
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/tools/getTitle.ts
+import { z as z4 } from "zod";
+var SECTIONS = ["basic", "scores", "awards", "production", "networks", "where_to_watch"];
+var getTitleDescription = [
+  "Read one Metacritic entry by slug and kind, both from search_titles.",
+  "Sections are opt-in because a full entry is large: 'basic' and 'scores' are the default and cover most questions.",
+  "'scores' fetches the critic and audience breakdowns, each with its own scale, so never compare the two numbers directly.",
+  "Sections gate the payload: asking for 'scores' alone returns no description, and 'basic' alone returns no scores.",
+  "'networks' lists the broadcasters of a show; 'where_to_watch' costs an extra request and covers films and shows only.",
+  "A long description paginates: when 'truncated' is true, call again with 'offset' set to 'next_offset'."
+].join(" ");
+var getTitleInputShape = {
+  slug: z4.string().min(1).describe("Identifier from search_titles, such as 'the-matrix'."),
+  kind: kindSchema,
+  sections: z4.array(z4.enum(SECTIONS)).default(["basic", "scores"]).describe("Which parts to return. Each extra section beyond the default costs a request."),
+  max_chars: z4.number().int().min(200).max(2e4).default(4e3).describe("Character budget for the description."),
+  offset: z4.number().int().min(0).default(0).describe("Where to resume the description.")
+};
+var getTitleOutputShape = {
+  title: titleSummarySchema,
+  description: z4.string().nullable(),
+  tagline: z4.string().nullable(),
+  genres: z4.array(z4.string()),
+  duration_minutes: z4.number().int().nullable().describe("Runtime in minutes for a film, or the length of a typical episode for a show."),
+  imdb_id: z4.string().nullable().describe("IMDb identifier, usable to cross-reference other sources."),
+  total_chars: z4.number().int().describe("Length of the full description."),
+  returned_chars: z4.number().int(),
+  offset: z4.number().int(),
+  next_offset: z4.number().int().nullable().describe("Pass as 'offset' to read the rest."),
+  truncated: z4.boolean(),
+  critic_score: scoreSchema.nullable(),
+  user_score: scoreSchema.nullable(),
+  awards: z4.array(
+    z4.object({
+      ceremony: z4.string().describe("Awards body, such as 'Academy Awards, USA'."),
+      wins: z4.number().int().nullable().describe("Null when the source records no win."),
+      nominations: z4.number().int().nullable()
+    })
+  ).optional().describe("One tally per ceremony. Metacritic publishes no per-category detail."),
+  networks: z4.array(z4.string()).optional().describe("Broadcasters, for shows."),
+  production: z4.array(z4.object({ name: z4.string(), id: z4.number().int().nullable() })).optional(),
+  where_to_watch: z4.array(z4.object({ provider: z4.string(), kind: z4.string(), url: z4.string().nullable() })).optional(),
+  notes: z4.array(z4.string())
+};
+async function runGetTitle(client, args) {
+  try {
+    const wanted = new Set(args.sections);
+    const notes = [];
+    const detail = await client.getDetail(args.kind, args.slug);
+    if (detail.cached) notes.push("Served from this server's short-lived in-memory cache.");
+    const item = detail.data;
+    let criticScore = null;
+    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)
+      ]);
+    }
+    const basic = wanted.has("basic");
+    const full = basic ? item.description ?? "" : "";
+    const { slice, nextOffset } = sliceAtLineBoundary(full, args.offset, args.max_chars);
+    if (basic && nextOffset !== null) {
+      notes.push(
+        `The description is longer than ${args.max_chars} characters. Call again with offset=${nextOffset} for the rest.`
+      );
+    }
+    if (basic && 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.`
+      );
+    }
+    if (!wanted.has("scores")) {
+      notes.push(
+        "Scores were not requested, so critic_score and user_score are null here regardless of what Metacritic publishes. Add 'scores' to sections to read them."
+      );
+    }
+    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,
+      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
+    };
+    if (wanted.has("awards")) structured.awards = item.awards;
+    if (wanted.has("production")) {
+      const CAP = 25;
+      structured.production = item.production.slice(0, CAP);
+      if (item.production.length > CAP) {
+        notes.push(
+          `${item.production.length} companies are credited and the first ${CAP} are shown. The list mixes producers with distributors and home-video labels across every territory.`
+        );
+      }
+    }
+    if (wanted.has("networks")) structured.networks = item.networks;
+    if (wanted.has("where_to_watch")) {
+      structured.where_to_watch = await watchOffers(client, item, args.kind, notes);
+    }
+    return ok(
+      structured,
+      render(item, slice, criticScore, userScore),
+      `${ATTRIBUTION} \u2014 ${item.sourceUrl}`
+    );
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+async function optionalScore(client, kind, slug, source, notes) {
+  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.`);
+    } else {
+      const reason = error instanceof McError ? error.code : "an unexpected error";
+      notes.push(
+        `The ${source} score could not be read (${reason}), so it is missing here rather than absent from Metacritic. Call again to retry.`
+      );
+    }
+    return null;
+  }
+}
+async function watchOffers(client, item, kind, notes) {
+  if (kind === "game") {
+    notes.push("Streaming offers do not apply to games.");
+    return [];
+  }
+  if (!item.imdbId) {
+    notes.push("This entry carries no IMDb id, which is what streaming offers are keyed by.");
+    return [];
+  }
+  try {
+    const { data } = await client.getWatchOffers(item.imdbId, kind);
+    return data;
+  } catch {
+    notes.push("Streaming offers could not be read for this entry.");
+    return [];
+  }
+}
+function render(item, description, critic, user) {
+  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];
+  if (item.genres.length > 0) lines.push(`Genres: ${item.genres.join(", ")}`);
+  if (critic?.score !== null && critic !== null) {
+    lines.push(
+      `Critics: ${critic.score}/${critic.max} from ${critic.reviewCount ?? "?"} reviews${critic.sentiment ? ` (${critic.sentiment})` : ""}`
+    );
+  }
+  if (user?.score !== null && user !== null) {
+    lines.push(
+      `Users: ${user.score}/${user.max} from ${user.reviewCount ?? "?"} ratings${user.sentiment ? ` (${user.sentiment})` : ""}`
+    );
+  }
+  if (description) lines.push("", description);
+  return lines.join("\n");
+}
+
+// src/tools/searchTitles.ts
+import { z as z5 } from "zod";
+var searchTitlesDescription = [
+  "Search Metacritic for films, shows and games by title.",
+  "Returns one compact row per match, carrying the critic Metascore, so a question about the critical verdict needs no second call.",
+  "Search rows carry no audience score: use get_title for that, or browse_titles, which does return it.",
+  "Use the slug and kind with get_title for the full entry, or with get_reviews for what critics wrote.",
+  "There is no paging: 'limit' is the only lever, and results always start from the most relevant match.",
+  "This searches titles only. It cannot find an entry from a plot detail, a person or a studio."
+].join(" ");
+var searchTitlesInputShape = {
+  query: z5.string().min(1).describe("Title or part of one, for example 'the matrix'."),
+  kind: z5.enum(["movie", "show", "game", "any"]).default("any").describe("Restrict results to one catalogue. Metacritic searches all three at once."),
+  limit: z5.number().int().min(1).max(50).default(10).describe("How many rows to return.")
+};
+var searchTitlesOutputShape = {
+  query: z5.string(),
+  results: z5.array(titleSummarySchema),
+  total_available: z5.number().int().describe(
+    "How many entries Metacritic counted. For a query of several words it counts entries matching any one of them, so the number is far larger than the useful matches and should not be read as a match count."
+  ),
+  notes: z5.array(z5.string())
+};
+async function runSearchTitles(client, args) {
+  try {
+    const upstreamLimit = args.kind === "any" ? args.limit : Math.min(50, args.limit * 3);
+    const { data, cached } = await client.search(args.query, upstreamLimit, 0);
+    const matching = args.kind === "any" ? data.titles : data.titles.filter((title) => title.kind === args.kind);
+    const results = matching.slice(0, args.limit).map(toTitleSummaryOut);
+    const windowExhausted = args.kind !== "any" && matching.length === results.length;
+    const notes = [];
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    const looseCount = /\s/.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 > 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.`
+      );
+    }
+    if (results.length === 0) {
+      notes.push(
+        args.kind === "any" ? "No entry matched. Metacritic matches on the title alone, so try a shorter fragment of it." : `No ${args.kind} matched. Other kinds may still match: call again with kind="any".`
+      );
+    } else if (windowExhausted && results.length < args.limit) {
+      notes.push(
+        `Every ${args.kind} in the window Metacritic returned is shown. There may be more further down its ranking, which this tool cannot reach.`
+      );
+    }
+    const summary = results.length === 0 ? `No Metacritic entry matched "${args.query}".` : `${results.length} entr${results.length === 1 ? "y" : "ies"} for "${args.query}":
+${renderTitleList(results)}`;
+    return ok({ query: args.query, results, total_available: data.totalResults, notes }, summary);
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
+// src/server.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+function createServer(options = {}) {
+  const config = options.config ?? loadConfig();
+  const logger = options.logger ?? createLogger(config.logLevel);
+  const client = new McClient({
+    config,
+    logger,
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  });
+  const server = new McpServer(
+    { name: "mcp-metacritic", version: PKG_VERSION },
+    {
+      instructions: "Tools for Metacritic: films, shows and games, their scores, and the reviews behind them. No API key is needed. Typical flow: search_titles to find an entry and its slug and kind, then get_title for the entry or get_reviews for what critics wrote. search_titles carries the critic Metascore, so a question about the critical verdict needs no second call, but it carries no audience score: read that with get_title, or with browse_titles. The two scores are on different scales: the critic Metascore runs to 100 and the audience score to 10, so never compare or average them without rescaling; every score is returned with its own 'max' for that reason. Use browse_titles when there is no title to look up, such as best rated or newest releases. When you repeat a review, name the publication and link the original article, and when you cite a score, credit Metacritic and link the entry: every result carries a source_url."
+    }
+  );
+  server.registerTool(
+    "search_titles",
+    {
+      title: "Search Metacritic",
+      description: searchTitlesDescription,
+      inputSchema: searchTitlesInputShape,
+      outputSchema: searchTitlesOutputShape,
+      annotations: READ_ONLY
+    },
+    async (args) => runSearchTitles(client, args)
+  );
+  server.registerTool(
+    "get_title",
+    {
+      title: "Read an entry",
+      description: getTitleDescription,
+      inputSchema: getTitleInputShape,
+      outputSchema: getTitleOutputShape,
+      annotations: READ_ONLY
+    },
+    async (args) => runGetTitle(client, args)
+  );
+  server.registerTool(
+    "get_reviews",
+    {
+      title: "Read reviews",
+      description: getReviewsDescription,
+      inputSchema: getReviewsInputShape,
+      outputSchema: getReviewsOutputShape,
+      annotations: READ_ONLY
+    },
+    async (args) => runGetReviews(client, args)
+  );
+  server.registerTool(
+    "browse_titles",
+    {
+      title: "Browse rankings",
+      description: browseTitlesDescription,
+      inputSchema: browseTitlesInputShape,
+      outputSchema: browseTitlesOutputShape,
+      annotations: READ_ONLY
+    },
+    async (args) => runBrowseTitles(client, args)
+  );
+  logger.info(
+    `ready: user-agent="${config.userAgent}", min interval ${config.minIntervalMs}ms, catalogue cache ${config.cacheTtlMs}ms, scores cache ${config.scoresCacheTtlMs}ms`
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const config = loadConfig();
+  const logger = createLogger(config.logLevel);
+  const server = createServer({ config, logger });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  const shutdown = () => {
+    void server.close().finally(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+main().catch((error) => {
+  process.stderr.write(
+    `[mcp-metacritic] fatal: ${error instanceof Error ? error.stack ?? error.message : String(error)}
+`
+  );
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map