wayback_snapshots

Instructions

Implementation Reference

• src/wayback/index.ts:82-117 (handler)

  The 'waybackSnapshots' function that executes the tool logic. It queries the Wayback Machine CDX API, parses the JSON response, and returns snapshot history including timestamps, status codes, MIME types, and archive URLs.

  export async function waybackSnapshots(url: string, limit = 100): Promise<WaybackSnapshotsResult> {
    await limiter.acquire();
  
    const params = new URLSearchParams({
      url,
      output: "json",
      fl: "timestamp,original,statuscode,mimetype",
      limit: String(limit),
    });
  
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 30000);
  
    try {
      const res = await fetch(`https://web.archive.org/cdx/search/cdx?${params}`, { signal: controller.signal });
      if (!res.ok) throw new Error(`Wayback CDX returned ${res.status}`);
  
      const data: string[][] = await res.json();
      const rows = data.slice(1);
  
      const snapshots: WaybackSnapshot[] = rows.map((row) => ({
        timestamp: row[0] ?? "",
        url: row[1] ?? "",
        statusCode: row[2] ?? "",
        mimeType: row[3] ?? "",
        archiveUrl: `https://web.archive.org/web/${row[0]}/${row[1]}`,
      }));
  
      const firstSeen = snapshots.length > 0 ? snapshots[0].timestamp : undefined;
      const lastSeen = snapshots.length > 0 ? snapshots[snapshots.length - 1].timestamp : undefined;
  
      return { url, totalSnapshots: snapshots.length, firstSeen, lastSeen, snapshots };
    } finally {
      clearTimeout(timeout);
    }
  }

• src/wayback/index.ts:20-34 (schema)

  Type definitions: WaybackSnapshot (individual snapshot with timestamp, url, statusCode, mimeType, archiveUrl) and WaybackSnapshotsResult (overall result with url, totalSnapshots, firstSeen, lastSeen, snapshots array).

  interface WaybackSnapshot {
    timestamp: string;
    url: string;
    statusCode: string;
    mimeType: string;
    archiveUrl: string;
  }
  
  interface WaybackSnapshotsResult {
    url: string;
    totalSnapshots: number;
    firstSeen?: string;
    lastSeen?: string;
    snapshots: WaybackSnapshot[];
  }

• src/protocol/tools.ts:393-402 (registration)

  Tool registration as a ToolDef constant 'waybackSnapshotsTool', with name 'wayback_snapshots', description, Zod schema (url required string, limit optional number), and execute handler that calls waybackSnapshots().

  const waybackSnapshotsTool: ToolDef = {
    name: "wayback_snapshots",
    description: "Get Wayback Machine snapshot history for a specific URL. Returns timestamps, status codes, and direct archive links. Shows first/last seen dates.",
    schema: {
      url: z.string().describe("URL to get snapshot history for"),
      limit: z.number().optional().describe("Maximum snapshots to return (default: 100)"),
    },
    execute: async (args) =>
      json(await waybackSnapshots(args.url as string, args.limit as number | undefined)),
  };

• src/protocol/tools.ts:17-17 (helper)

  Import statement bringing 'waybackSnapshots' from '../wayback/index.js' into the tools registration module.

  import { waybackUrls, waybackSnapshots } from "../wayback/index.js";

• src/index.ts:32-32 (registration)

  Tool listed in the top-level tool registry under 'Wayback Machine' category with tools ['wayback_urls', 'wayback_snapshots'].

  { label: "Wayback Machine", env: null, tools: ["wayback_urls", "wayback_snapshots"] },