archive-org-mcp 1.0.0 → 1.0.2

package/README.md

@@ -23,3 +23,21 @@ node dist/index.js
 ## Source
 
 Public free APIs only. See `src/api.ts` for exact endpoints.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `snapshot_timeline`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-archive-org-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -120,3 +120,16 @@ export declare const m1_WaybackError: {
 };
 export declare const m1_getSnapshotText: (timestamp: string, originalUrl: string, maxChars?: number) => Promise<string>;
 export declare const m1_getSnapshots: (url: string, limit?: number) => Promise<m1_Snapshot[]>;
+export interface SnapshotTimelineArgs {
+    url: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+}
+export declare function snapshotTimeline(args: SnapshotTimelineArgs): Promise<string>;
+export interface SearchProfileArgs {
+    query: string;
+    mediatype?: string;
+    limit?: number;
+}
+export declare function searchProfile(args: SearchProfileArgs): Promise<string>;

package/dist/api.js

@@ -181,3 +181,213 @@ export const m1_getAvailability = m1.getAvailability;
 export const m1_WaybackError = m1.WaybackError;
 export const m1_getSnapshotText = m1.getSnapshotText;
 export const m1_getSnapshots = m1.getSnapshots;
+// ---- muxE tools:
+// The five existing tools either print a short list of Archive items or list the
+// newest few Wayback snapshots. The new ones answer two questions neither asks:
+// what a search term actually looks like across the catalogue, and how one URL's
+// archived history is distributed over time rather than merely listed.
+const CDX_TIMELINE = "https://web.archive.org/cdx/search/cdx";
+const ADVANCED = "https://archive.org/advancedsearch.php";
+const IA_UA = "archive-org-mcp/1.0";
+/**
+ * Fetches and returns the body unparsed. The two APIs here differ: advancedsearch
+ * always answers JSON and reports its own problems in an `error` field, while the
+ * CDX API occasionally answers a non JSON body of its own, so the caller reports
+ * what actually came back instead of the fetch layer assuming JSON.
+ */
+async function iaText(url, seconds) {
+    let res;
+    try {
+        res = await fetch(url, { headers: { "User-Agent": IA_UA }, signal: AbortSignal.timeout(seconds * 1000) });
+    }
+    catch (e) {
+        if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
+            throw new ArchiveError(`The Internet Archive did not answer within ${seconds} seconds on this route; its index query is slow for a very widely captured URL, so narrow the year range or lower the limit.`);
+        }
+        throw new ArchiveError(`The Internet Archive could not be reached: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!res.ok)
+        throw new ArchiveError(`Internet Archive error ${res.status}`);
+    const body = await res.text();
+    if (body.trim()) {
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed && typeof parsed.error === "string") {
+                throw new ArchiveError(`The Internet Archive said: ${parsed.error}`);
+            }
+        }
+        catch (e) {
+            if (e instanceof ArchiveError)
+                throw e;
+            // not JSON, which is the caller's business to report
+        }
+    }
+    return { text: body, contentType: res.headers.get("content-type") ?? "not reported" };
+}
+async function iaJson(url, seconds) {
+    const body = await iaText(url, seconds);
+    try {
+        return JSON.parse(body.text);
+    }
+    catch {
+        throw new ArchiveError(`The Internet Archive answered ${body.contentType} rather than JSON on this route.`);
+    }
+}
+const cdxStamp = (ts) => /^\d{14}$/.test(ts) ? `${ts.slice(0, 4)}-${ts.slice(4, 6)}-${ts.slice(6, 8)} ${ts.slice(8, 10)}:${ts.slice(10, 12)} UTC` : ts;
+const yearOf = (ts) => (/^\d{14}$/.test(ts) ? ts.slice(0, 4) : "unknown year");
+export async function snapshotTimeline(args) {
+    const asked = (args?.url ?? "").trim();
+    if (!asked)
+        throw new ArchiveError("Provide the URL whose archived history you want.");
+    // the existing snapshot tools take a bare host like example.com/page.html, so
+    // accept that shape too rather than being stricter than the rest of the server
+    const target = /^https?:\/\//i.test(asked) ? asked : `https://${asked}`;
+    if (!/^https?:\/\/[^/\s]+/.test(target))
+        throw new ArchiveError("Provide a URL such as example.com/page.html.");
+    const yearCheck = (value, label) => {
+        if (value === undefined)
+            return undefined;
+        const n = Math.floor(Number(value));
+        if (!Number.isInteger(n) || n < 1996 || n > 2100)
+            throw new ArchiveError(`${label} must be a whole year between 1996 and 2100.`);
+        return n;
+    };
+    const from = yearCheck(args?.from, "from");
+    const to = yearCheck(args?.to, "to");
+    if (from !== undefined && to !== undefined && from > to)
+        throw new ArchiveError("from must not be after to.");
+    const limit = Math.max(1, Math.min(Math.floor(Number(args?.limit ?? 500) || 500), 3000));
+    const params = new URLSearchParams({
+        url: target,
+        output: "json",
+        fl: "timestamp,statuscode,mimetype,digest,length",
+        filter: "statuscode:200",
+        limit: String(limit),
+    });
+    if (from !== undefined)
+        params.set("from", String(from));
+    if (to !== undefined)
+        params.set("to", String(to));
+    const raw = (await iaJson(`${CDX_TIMELINE}?${params.toString()}`, 45));
+    if (!Array.isArray(raw) || raw.length <= 1) {
+        const window = from !== undefined || to !== undefined ? ` between ${from ?? "the start"} and ${to ?? "now"}` : "";
+        return `The Wayback Machine holds no successful snapshot of ${target}${window}.`;
+    }
+    // the CDX API returns a header row, and the column order it uses is not
+    // guaranteed to be the order asked for, so the columns are read by name
+    const header = (raw[0] ?? []).map((h) => String(h).toLowerCase());
+    const at = (row, name) => {
+        const i = header.indexOf(name);
+        return i >= 0 ? (row[i] ?? "") : "";
+    };
+    const rows = raw.slice(1).map((r) => ({
+        timestamp: at(r, "timestamp"),
+        original: at(r, "original") || target,
+        statusCode: at(r, "statuscode"),
+        mimeType: at(r, "mimetype"),
+        digest: at(r, "digest"),
+        length: at(r, "length"),
+    }));
+    if (!rows.some((r) => r.timestamp)) {
+        throw new ArchiveError("The Wayback Machine returned rows without a readable timestamp column.");
+    }
+    const stamps = rows.map((r) => r.timestamp).filter((t) => /^\d{14}$/.test(t)).sort();
+    const digests = new Set(rows.map((r) => r.digest).filter(Boolean));
+    const types = new Map();
+    const years = new Map();
+    let bytes = 0;
+    let counted = 0;
+    for (const r of rows) {
+        if (r.mimeType)
+            types.set(r.mimeType, (types.get(r.mimeType) ?? 0) + 1);
+        years.set(yearOf(r.timestamp), (years.get(yearOf(r.timestamp)) ?? 0) + 1);
+        const size = Number(r.length);
+        if (Number.isFinite(size) && size > 0) {
+            bytes += size;
+            counted += 1;
+        }
+    }
+    const lines = [
+        `Archived history of ${target}${asked !== target ? ` (asked for ${asked})` : ""}${from !== undefined || to !== undefined ? `, ${from ?? 1996} to ${to ?? "the present"}` : ""}:`,
+        `  successful snapshots returned: ${rows.length}${rows.length >= limit ? ` (the request limit was ${limit}, so there may be more)` : ""}`,
+        `  distinct content digests: ${digests.size}, so ${rows.length - digests.size} capture(s) repeat a page already archived`,
+    ];
+    if (stamps.length) {
+        lines.push(`  first snapshot: ${cdxStamp(stamps[0])}`, `  last snapshot: ${cdxStamp(stamps[stamps.length - 1])}`);
+    }
+    if (counted) {
+        lines.push(`  payload captured: ${bytes.toLocaleString("en-US")} bytes across ${counted} snapshot(s) that report a length`);
+    }
+    if (types.size) {
+        lines.push("  media types captured:");
+        for (const [k, n] of [...types.entries()].sort((a, b) => b[1] - a[1]))
+            lines.push(`    ${k}: ${n}`);
+    }
+    if (years.size) {
+        const sortedYears = [...years.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+        lines.push(`  captures per year across ${sortedYears.length} year(s):`);
+        for (const [y, n] of sortedYears.slice(0, 25))
+            lines.push(`    ${y}: ${n}`);
+        if (sortedYears.length > 25)
+            lines.push(`    and ${sortedYears.length - 25} more year(s) not listed here`);
+    }
+    lines.push("  the existing snapshot tool lists the newest captures one by one; this is the distribution behind that list.");
+    return lines.join("\n");
+}
+export async function searchProfile(args) {
+    const query = (args?.query ?? "").trim();
+    if (!query)
+        throw new ArchiveError("Provide search terms.");
+    const mediatype = (args?.mediatype ?? "").trim().toLowerCase();
+    if (mediatype && !/^[a-z]+$/.test(mediatype))
+        throw new ArchiveError("A media type is a single word like software, audio, movies or texts.");
+    const limit = Math.max(10, Math.min(Math.floor(Number(args?.limit ?? 200) || 200), 500));
+    const q = mediatype ? `(${query}) AND mediatype:${mediatype}` : query;
+    const fields = ["identifier", "year", "mediatype", "downloads", "collection", "item_size"].map((f) => `fl[]=${f}`).join("&");
+    const url = `${ADVANCED}?q=${encodeURIComponent(q)}&${fields}&rows=${limit}&page=1&output=json`;
+    const parsed = (await iaJson(url, 60));
+    const docs = parsed.response?.docs ?? [];
+    const numFound = typeof parsed.response?.numFound === "number" ? parsed.response.numFound : docs.length;
+    if (!docs.length)
+        return `The Internet Archive holds nothing matching "${query}"${mediatype ? ` in ${mediatype}` : ""}.`;
+    const types = new Map();
+    const years = new Map();
+    const collections = new Map();
+    const downloads = [];
+    let withYear = 0;
+    for (const d of docs) {
+        const type = typeof d.mediatype === "string" ? d.mediatype : "not reported";
+        types.set(type, (types.get(type) ?? 0) + 1);
+        const year = d.year != null ? String(d.year).slice(0, 4) : "not reported";
+        years.set(year, (years.get(year) ?? 0) + 1);
+        if (d.year != null)
+            withYear += 1;
+        for (const c of Array.isArray(d.collection) ? d.collection : [])
+            collections.set(String(c), (collections.get(String(c)) ?? 0) + 1);
+        if (typeof d.downloads === "number" && Number.isFinite(d.downloads))
+            downloads.push(d.downloads);
+    }
+    const top = (m, n) => [...m.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, n).map(([k, v]) => `${k} (${v})`);
+    const lines = [
+        `What the Internet Archive holds for "${query}"${mediatype ? ` in ${mediatype}` : ""}:`,
+        `  items in the catalogue: ${numFound.toLocaleString("en-US")}`,
+        `  items read for this profile: ${docs.length}${numFound > docs.length ? `, so every breakdown below is a sample of the first ${docs.length} and not of all ${numFound.toLocaleString("en-US")}` : ""}`,
+    ];
+    lines.push(`  media types in the sample: ${top(types, 10).join(", ") || "none reported"}`);
+    lines.push(`  items with no year recorded: ${docs.length - withYear} of ${docs.length}`);
+    const knownYears = [...years.entries()].filter(([y]) => y !== "not reported").sort((a, b) => b[1] - a[1]);
+    lines.push(`  most common years in the sample: ${knownYears.slice(0, 12).map(([y, n]) => `${y} (${n})`).join(", ") || "none reported"}`);
+    lines.push(`  distinct collections touched: ${collections.size}`);
+    lines.push(`    ${top(collections, 10).join(", ") || "none reported"}`);
+    if (downloads.length) {
+        const sorted = [...downloads].sort((a, b) => a - b);
+        const total = downloads.reduce((a, b) => a + b, 0);
+        const median = sorted.length % 2 ? sorted[Math.floor(sorted.length / 2)] : Math.round((sorted[sorted.length - 1] + sorted[sorted.length]) / 2);
+        lines.push(`  downloads across the ${downloads.length} item(s) that report it: total ${total.toLocaleString("en-US")}, median ${median.toLocaleString("en-US")}, highest ${sorted[sorted.length - 1].toLocaleString("en-US")}, lowest ${sorted[0].toLocaleString("en-US")}`);
+    }
+    else {
+        lines.push("  no item in the sample reports a download count.");
+    }
+    lines.push("  every figure above is tallied from the rows the search returned, and the sample size is stated rather than implied.");
+    return lines.join("\n");
+}

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/license.js

@@ -0,0 +1,78 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "archive-org-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "snapshot_timeline",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { m0_fmtSize, m0_formatItem, m0_getItemDetails, m0_searchItems, m1_formatSnapshot, m1_getAvailability, m1_getSnapshots, m1_getSnapshotText } from './api.js';
+import { m0_fmtSize, m0_formatItem, m0_getItemDetails, m0_searchItems, m1_formatSnapshot, m1_getAvailability, m1_getSnapshots, m1_getSnapshotText, snapshotTimeline, searchProfile } from './api.js';
+import { premiumRequired } from "./license.js";
 const text = (value) => ({ content: [{ type: 'text', text: value }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -108,5 +109,45 @@ export function createServer() {
             return textError(errorMessage(e));
         }
     });
+    server.registerTool("snapshot_timeline", {
+        title: "Snapshot timeline",
+        description: "The shape of one URL's archived history rather than a list of it: how many successful snapshots exist in a year range, how many distinct content digests they hold, how many captures just repeat a page already archived, the media types captured, the payload size and captures per year. The get_snapshots tool returns the newest few with no digest, no date range and no totals.",
+        inputSchema: z.object({
+            url: z.string().describe("Full URL, e.g. 'example.com/page.html'"),
+            from: z.number().int().min(1996).max(2100).describe("Earliest year to include.").optional(),
+            to: z.number().int().min(1996).max(2100).describe("Latest year to include.").optional(),
+            limit: z.number().int().min(1).max(3000).default(500).describe("How many snapshots to read, up to 3000."),
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: snapshot_timeline ----
+        const paywallMessage = await premiumRequired("snapshot_timeline");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await snapshotTimeline(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("search_profile", {
+        title: "Search profile",
+        description: "What a search term looks like across the Internet Archive rather than eight rows of it: the catalogue total, the media type split, how many items carry no year, the most common years, the collections involved and the download distribution, with the sample size stated. The search_items tool only prints a short list.",
+        inputSchema: z.object({
+            query: z.string().describe("Search terms, e.g. 'Windows 95'"),
+            mediatype: z.string().describe("Restrict to one media type, e.g. software or audio.").optional(),
+            limit: z.number().int().min(10).max(500).default(200).describe("How many items to read for the profile, 10 to 500."),
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await searchProfile(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archive-org-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Internet Archive search, item metadata, and Wayback snapshots.",
   "type": "module",
   "main": "dist/index.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/mrfentmen/awesome-mcps",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "archive-org-mcp",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
       }

package/src/api.ts

@@ -235,3 +235,226 @@ export const m1_getAvailability = m1.getAvailability;
 export const m1_WaybackError = m1.WaybackError;
 export const m1_getSnapshotText = m1.getSnapshotText;
 export const m1_getSnapshots = m1.getSnapshots;
+
+// ---- muxE tools:
+// The five existing tools either print a short list of Archive items or list the
+// newest few Wayback snapshots. The new ones answer two questions neither asks:
+// what a search term actually looks like across the catalogue, and how one URL's
+// archived history is distributed over time rather than merely listed.
+const CDX_TIMELINE = "https://web.archive.org/cdx/search/cdx";
+const ADVANCED = "https://archive.org/advancedsearch.php";
+const IA_UA = "archive-org-mcp/1.0";
+
+interface CdxRow {
+  timestamp: string;
+  original: string;
+  statusCode: string;
+  mimeType: string;
+  digest: string;
+  length: string;
+}
+
+interface IaBody {
+  text: string;
+  contentType: string;
+}
+
+/**
+ * Fetches and returns the body unparsed. The two APIs here differ: advancedsearch
+ * always answers JSON and reports its own problems in an `error` field, while the
+ * CDX API occasionally answers a non JSON body of its own, so the caller reports
+ * what actually came back instead of the fetch layer assuming JSON.
+ */
+async function iaText(url: string, seconds: number): Promise<IaBody> {
+  let res: Response;
+  try {
+    res = await fetch(url, { headers: { "User-Agent": IA_UA }, signal: AbortSignal.timeout(seconds * 1000) });
+  } catch (e) {
+    if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
+      throw new ArchiveError(`The Internet Archive did not answer within ${seconds} seconds on this route; its index query is slow for a very widely captured URL, so narrow the year range or lower the limit.`);
+    }
+    throw new ArchiveError(`The Internet Archive could not be reached: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!res.ok) throw new ArchiveError(`Internet Archive error ${res.status}`);
+  const body = await res.text();
+  if (body.trim()) {
+    try {
+      const parsed = JSON.parse(body) as { error?: string };
+      if (parsed && typeof parsed.error === "string") {
+        throw new ArchiveError(`The Internet Archive said: ${parsed.error}`);
+      }
+    } catch (e) {
+      if (e instanceof ArchiveError) throw e;
+      // not JSON, which is the caller's business to report
+    }
+  }
+  return { text: body, contentType: res.headers.get("content-type") ?? "not reported" };
+}
+
+async function iaJson(url: string, seconds: number): Promise<unknown> {
+  const body = await iaText(url, seconds);
+  try {
+    return JSON.parse(body.text) as unknown;
+  } catch {
+    throw new ArchiveError(`The Internet Archive answered ${body.contentType} rather than JSON on this route.`);
+  }
+}
+
+const cdxStamp = (ts: string): string =>
+  /^\d{14}$/.test(ts) ? `${ts.slice(0, 4)}-${ts.slice(4, 6)}-${ts.slice(6, 8)} ${ts.slice(8, 10)}:${ts.slice(10, 12)} UTC` : ts;
+
+const yearOf = (ts: string): string => (/^\d{14}$/.test(ts) ? ts.slice(0, 4) : "unknown year");
+
+export interface SnapshotTimelineArgs {
+  url: string;
+  from?: number;
+  to?: number;
+  limit?: number;
+}
+
+export async function snapshotTimeline(args: SnapshotTimelineArgs): Promise<string> {
+  const asked = (args?.url ?? "").trim();
+  if (!asked) throw new ArchiveError("Provide the URL whose archived history you want.");
+  // the existing snapshot tools take a bare host like example.com/page.html, so
+  // accept that shape too rather than being stricter than the rest of the server
+  const target = /^https?:\/\//i.test(asked) ? asked : `https://${asked}`;
+  if (!/^https?:\/\/[^/\s]+/.test(target)) throw new ArchiveError("Provide a URL such as example.com/page.html.");
+  const yearCheck = (value: number | undefined, label: string): number | undefined => {
+    if (value === undefined) return undefined;
+    const n = Math.floor(Number(value));
+    if (!Number.isInteger(n) || n < 1996 || n > 2100) throw new ArchiveError(`${label} must be a whole year between 1996 and 2100.`);
+    return n;
+  };
+  const from = yearCheck(args?.from, "from");
+  const to = yearCheck(args?.to, "to");
+  if (from !== undefined && to !== undefined && from > to) throw new ArchiveError("from must not be after to.");
+  const limit = Math.max(1, Math.min(Math.floor(Number(args?.limit ?? 500) || 500), 3000));
+  const params = new URLSearchParams({
+    url: target,
+    output: "json",
+    fl: "timestamp,statuscode,mimetype,digest,length",
+    filter: "statuscode:200",
+    limit: String(limit),
+  });
+  if (from !== undefined) params.set("from", String(from));
+  if (to !== undefined) params.set("to", String(to));
+  const raw = (await iaJson(`${CDX_TIMELINE}?${params.toString()}`, 45)) as string[][];
+  if (!Array.isArray(raw) || raw.length <= 1) {
+    const window = from !== undefined || to !== undefined ? ` between ${from ?? "the start"} and ${to ?? "now"}` : "";
+    return `The Wayback Machine holds no successful snapshot of ${target}${window}.`;
+  }
+  // the CDX API returns a header row, and the column order it uses is not
+  // guaranteed to be the order asked for, so the columns are read by name
+  const header = (raw[0] ?? []).map((h) => String(h).toLowerCase());
+  const at = (row: string[], name: string): string => {
+    const i = header.indexOf(name);
+    return i >= 0 ? (row[i] ?? "") : "";
+  };
+  const rows: CdxRow[] = raw.slice(1).map((r) => ({
+    timestamp: at(r, "timestamp"),
+    original: at(r, "original") || target,
+    statusCode: at(r, "statuscode"),
+    mimeType: at(r, "mimetype"),
+    digest: at(r, "digest"),
+    length: at(r, "length"),
+  }));
+  if (!rows.some((r) => r.timestamp)) {
+    throw new ArchiveError("The Wayback Machine returned rows without a readable timestamp column.");
+  }
+  const stamps = rows.map((r) => r.timestamp).filter((t) => /^\d{14}$/.test(t)).sort();
+  const digests = new Set(rows.map((r) => r.digest).filter(Boolean));
+  const types = new Map<string, number>();
+  const years = new Map<string, number>();
+  let bytes = 0;
+  let counted = 0;
+  for (const r of rows) {
+    if (r.mimeType) types.set(r.mimeType, (types.get(r.mimeType) ?? 0) + 1);
+    years.set(yearOf(r.timestamp), (years.get(yearOf(r.timestamp)) ?? 0) + 1);
+    const size = Number(r.length);
+    if (Number.isFinite(size) && size > 0) {
+      bytes += size;
+      counted += 1;
+    }
+  }
+  const lines = [
+    `Archived history of ${target}${asked !== target ? ` (asked for ${asked})` : ""}${from !== undefined || to !== undefined ? `, ${from ?? 1996} to ${to ?? "the present"}` : ""}:`,
+    `  successful snapshots returned: ${rows.length}${rows.length >= limit ? ` (the request limit was ${limit}, so there may be more)` : ""}`,
+    `  distinct content digests: ${digests.size}, so ${rows.length - digests.size} capture(s) repeat a page already archived`,
+  ];
+  if (stamps.length) {
+    lines.push(`  first snapshot: ${cdxStamp(stamps[0])}`, `  last snapshot: ${cdxStamp(stamps[stamps.length - 1])}`);
+  }
+  if (counted) {
+    lines.push(`  payload captured: ${bytes.toLocaleString("en-US")} bytes across ${counted} snapshot(s) that report a length`);
+  }
+  if (types.size) {
+    lines.push("  media types captured:");
+    for (const [k, n] of [...types.entries()].sort((a, b) => b[1] - a[1])) lines.push(`    ${k}: ${n}`);
+  }
+  if (years.size) {
+    const sortedYears = [...years.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    lines.push(`  captures per year across ${sortedYears.length} year(s):`);
+    for (const [y, n] of sortedYears.slice(0, 25)) lines.push(`    ${y}: ${n}`);
+    if (sortedYears.length > 25) lines.push(`    and ${sortedYears.length - 25} more year(s) not listed here`);
+  }
+  lines.push("  the existing snapshot tool lists the newest captures one by one; this is the distribution behind that list.");
+  return lines.join("\n");
+}
+
+export interface SearchProfileArgs {
+  query: string;
+  mediatype?: string;
+  limit?: number;
+}
+
+export async function searchProfile(args: SearchProfileArgs): Promise<string> {
+  const query = (args?.query ?? "").trim();
+  if (!query) throw new ArchiveError("Provide search terms.");
+  const mediatype = (args?.mediatype ?? "").trim().toLowerCase();
+  if (mediatype && !/^[a-z]+$/.test(mediatype)) throw new ArchiveError("A media type is a single word like software, audio, movies or texts.");
+  const limit = Math.max(10, Math.min(Math.floor(Number(args?.limit ?? 200) || 200), 500));
+  const q = mediatype ? `(${query}) AND mediatype:${mediatype}` : query;
+  const fields = ["identifier", "year", "mediatype", "downloads", "collection", "item_size"].map((f) => `fl[]=${f}`).join("&");
+  const url = `${ADVANCED}?q=${encodeURIComponent(q)}&${fields}&rows=${limit}&page=1&output=json`;
+  const parsed = (await iaJson(url, 60)) as { response?: { numFound?: number; docs?: Array<Record<string, unknown>> } };
+  const docs = parsed.response?.docs ?? [];
+  const numFound = typeof parsed.response?.numFound === "number" ? parsed.response.numFound : docs.length;
+  if (!docs.length) return `The Internet Archive holds nothing matching "${query}"${mediatype ? ` in ${mediatype}` : ""}.`;
+  const types = new Map<string, number>();
+  const years = new Map<string, number>();
+  const collections = new Map<string, number>();
+  const downloads: number[] = [];
+  let withYear = 0;
+  for (const d of docs) {
+    const type = typeof d.mediatype === "string" ? d.mediatype : "not reported";
+    types.set(type, (types.get(type) ?? 0) + 1);
+    const year = d.year != null ? String(d.year).slice(0, 4) : "not reported";
+    years.set(year, (years.get(year) ?? 0) + 1);
+    if (d.year != null) withYear += 1;
+    for (const c of Array.isArray(d.collection) ? d.collection : []) collections.set(String(c), (collections.get(String(c)) ?? 0) + 1);
+    if (typeof d.downloads === "number" && Number.isFinite(d.downloads)) downloads.push(d.downloads);
+  }
+  const top = (m: Map<string, number>, n: number): string[] =>
+    [...m.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, n).map(([k, v]) => `${k} (${v})`);
+  const lines = [
+    `What the Internet Archive holds for "${query}"${mediatype ? ` in ${mediatype}` : ""}:`,
+    `  items in the catalogue: ${numFound.toLocaleString("en-US")}`,
+    `  items read for this profile: ${docs.length}${numFound > docs.length ? `, so every breakdown below is a sample of the first ${docs.length} and not of all ${numFound.toLocaleString("en-US")}` : ""}`,
+  ];
+  lines.push(`  media types in the sample: ${top(types, 10).join(", ") || "none reported"}`);
+  lines.push(`  items with no year recorded: ${docs.length - withYear} of ${docs.length}`);
+  const knownYears = [...years.entries()].filter(([y]) => y !== "not reported").sort((a, b) => b[1] - a[1]);
+  lines.push(`  most common years in the sample: ${knownYears.slice(0, 12).map(([y, n]) => `${y} (${n})`).join(", ") || "none reported"}`);
+  lines.push(`  distinct collections touched: ${collections.size}`);
+  lines.push(`    ${top(collections, 10).join(", ") || "none reported"}`);
+  if (downloads.length) {
+    const sorted = [...downloads].sort((a, b) => a - b);
+    const total = downloads.reduce((a, b) => a + b, 0);
+    const median = sorted.length % 2 ? sorted[Math.floor(sorted.length / 2)] : Math.round((sorted[sorted.length - 1] + sorted[sorted.length]) / 2);
+    lines.push(`  downloads across the ${downloads.length} item(s) that report it: total ${total.toLocaleString("en-US")}, median ${median.toLocaleString("en-US")}, highest ${sorted[sorted.length - 1].toLocaleString("en-US")}, lowest ${sorted[0].toLocaleString("en-US")}`);
+  } else {
+    lines.push("  no item in the sample reports a download count.");
+  }
+  lines.push("  every figure above is tallied from the rows the search returned, and the sample size is stated rather than implied.");
+  return lines.join("\n");
+}

package/src/license.ts

@@ -0,0 +1,88 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "archive-org-mcp"
+
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set<string>([
+  "snapshot_timeline",
+])
+
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`
+
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key"
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h"
+
+const OK_CACHE_MS = 60 * 60 * 1000
+const BAD_CACHE_MS = 60 * 1000
+
+type Check = { valid: boolean; reason?: string }
+
+const seen = new Map<string, Check & { at: number }>()
+
+const REASONS: Record<string, string> = {
+  missing_key: "no key is set",
+  invalid_format: "that key is not a valid MCP Marketplace key",
+  not_found: "that key was not found",
+  revoked: "that key has been revoked",
+  rotated: "that key was rotated, use your new one",
+  expired: "that key has expired, renew it",
+  rate_limited: "there were too many checks just now, try again shortly",
+  network_error: "the license server could not be reached",
+}
+
+function blocked(tool: string, reason: string): string {
+  const why = REASONS[reason] ?? `the license server answered "${reason}"`
+  return `"${tool}" needs a license key, but ${why}. ` +
+    `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`
+}
+
+async function verify(key: string): Promise<Check> {
+  const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+    method: "POST",
+    headers: {
+      apikey: PUBLISHABLE_KEY,
+      Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ key, slug: SLUG }),
+    // an unusable key answers 400 with a JSON body, so read the body either way
+    signal: AbortSignal.timeout(15000),
+  })
+  const data = (await res.json()) as Check
+  if (typeof data?.valid !== "boolean") return { valid: false, reason: "unexpected_response" }
+  return data
+}
+
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool: string): Promise<string | null> {
+  if (!PREMIUM.has(tool)) return null
+
+  const key = process.env.MCP_LICENSE_KEY
+  if (!key) return blocked(tool, "missing_key")
+
+  const hit = seen.get(key)
+  if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+    return hit.valid ? null : blocked(tool, hit.reason ?? "invalid")
+  }
+
+  let result: Check
+  try {
+    result = await verify(key)
+  } catch {
+    result = { valid: false, reason: "network_error" }
+  }
+  seen.set(key, { ...result, at: Date.now() })
+  return result.valid ? null : blocked(tool, result.reason ?? "invalid")
+}

package/src/server.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
-import { m0_ArchiveError, m0_fmtSize, m0_formatItem, m0_getItemDetails, m0_searchItems, m1_WaybackError, m1_formatSnapshot, m1_getAvailability, m1_getSnapshots, m1_getSnapshotText } from './api.js'
+import { m0_ArchiveError, m0_fmtSize, m0_formatItem, m0_getItemDetails, m0_searchItems, m1_WaybackError, m1_formatSnapshot, m1_getAvailability, m1_getSnapshots, m1_getSnapshotText, snapshotTimeline, searchProfile } from './api.js'
+import { premiumRequired } from "./license.js"
 
 const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }] })
 const textError = (t: string) => ({ content: [{ type: "text" as const, text: t }], isError: true as const })
@@ -131,5 +132,46 @@ server.registerTool(
       }
     }
   )
+  server.registerTool(
+    "snapshot_timeline",
+    {
+      title: "Snapshot timeline",
+      description: "The shape of one URL's archived history rather than a list of it: how many successful snapshots exist in a year range, how many distinct content digests they hold, how many captures just repeat a page already archived, the media types captured, the payload size and captures per year. The get_snapshots tool returns the newest few with no digest, no date range and no totals.",
+      inputSchema: z.object(
+    {
+      url: z.string().describe("Full URL, e.g. 'example.com/page.html'"),
+      from: z.number().int().min(1996).max(2100).describe("Earliest year to include.").optional(),
+      to: z.number().int().min(1996).max(2100).describe("Latest year to include.").optional(),
+      limit: z.number().int().min(1).max(3000).default(500).describe("How many snapshots to read, up to 3000."),
+    }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+      // ---- paywall: snapshot_timeline ----
+      const paywallMessage = await premiumRequired("snapshot_timeline")
+      if (paywallMessage) return { content: [{ type: "text" as const, text: paywallMessage }], isError: true }
+      // ---- paywall: end ----
+      try { return text(await snapshotTimeline(args)) } catch (e) { return textError(errorMessage(e)) }
+    }
+  )
+
+  server.registerTool(
+    "search_profile",
+    {
+      title: "Search profile",
+      description: "What a search term looks like across the Internet Archive rather than eight rows of it: the catalogue total, the media type split, how many items carry no year, the most common years, the collections involved and the download distribution, with the sample size stated. The search_items tool only prints a short list.",
+      inputSchema: z.object(
+    {
+      query: z.string().describe("Search terms, e.g. 'Windows 95'"),
+      mediatype: z.string().describe("Restrict to one media type, e.g. software or audio.").optional(),
+      limit: z.number().int().min(10).max(500).default(200).describe("How many items to read for the profile, 10 to 500."),
+    }),
+      annotations: READ_ONLY,
+    },
+    async (args) => {
+      try { return text(await searchProfile(args)) } catch (e) { return textError(errorMessage(e)) }
+    }
+  )
+
   return server
 }