mcp-wayback-machine

MCP Wayback Machine Server

MCP server and CLI tool for interacting with the Internet Archive's Wayback Machine. Supports full CDX search, snapshot content retrieval, screenshot listing, snapshot comparison, and optional authentication for higher SPN2 rate limits.

Stack: TypeScript · Node.js 22+ · ES Modules · pnpm · Turbo · Zod

Getting started

Requires Node.js 22+ and pnpm.

pnpm install

Optional credentials (anonymous access works, but authenticated requests get higher SPN2 rate limits):

export WAYBACK_ACCESS_KEY="your-access-key"
export WAYBACK_SECRET_KEY="your-secret-key"

Obtain credentials at archive.org/account/s3.php.

Build, test, and lint

pnpm validate          # typecheck + lint + build + test + untested-files check (the full CI gate)
pnpm check             # typecheck + lint + build only
pnpm build             # compile TypeScript to dist/
pnpm test              # run unit and integration tests
pnpm test:coverage     # run tests with coverage (80% line/branch/function threshold)
pnpm lint              # lint with ESLint
pnpm lint:fix          # auto-fix lint issues

To run a single test file:

node --test tests/tools/save.unit.test.ts

End-to-end tests hit the live Wayback Machine API and are opt-in:

pnpm test:e2e          # sets WAYBACK_LIVE_TESTS=1 internally via turbo

pnpm validate is the gate that must pass before a release. prepublishOnly runs it automatically.

Architecture

src/bin.ts is the entry point. It detects whether it is invoked as a CLI or loaded as an MCP server and routes accordingly.

src/
  bin.ts          — entry point; dispatches to CLI or MCP server
  cli.ts          — Commander-based CLI implementation
  server.ts       — MCP server wiring (ListTools + CallTool handlers)
  contexts.ts     — shared context (rate limiter, cache, credentials)
  schemas.ts      — Zod schemas for all tool inputs; single source of truth
  tools/
    save.ts       — save_url tool (SPN2 API)
    retrieve.ts   — get_archived_url tool
    search.ts     — search_archives tool (CDX API)
    status.ts     — check_archive_status tool (sparkline API)
    screenshots.ts — list_screenshots tool
    compare.ts    — compare_snapshots tool
    cache.ts      — clear_cache tool
    context.ts    — injects shared context into tool handlers
  utils/
    http.ts       — fetch wrapper with rate limiting and Retry-After handling
    cache.ts      — in-memory + disk cache with per-endpoint TTLs
    rate-limit.ts — 15 req/min token bucket
    validation.ts — shared Zod validation helpers

Each tool module exports a schema (consumed by ListToolsRequestSchema) and an execution function (consumed by CallToolRequestSchema). New tools need both registrations in server.ts.

Caching TTLs are intentional — do not normalise them:

Resource	TTL	Reason
Snapshot content	24 h	Immutable once captured
Availability, CDX, sparkline	1 h	Grows but never mutates
Save operations	30 min	Idempotent per URL
Save status polling	30 s	Changes during active jobs

Conventions

• TypeScript strict mode with noUncheckedIndexedAccess and exactOptionalPropertyTypes — no any, no as assertions.
• ES Modules throughout — "type": "module" in package.json. Always use .ts extensions in relative imports (rewritten to .js at build time via rewriteRelativeImportExtensions).
• Zod is the single source of truth for all tool input shapes. schemas.ts defines them; zodToJsonSchema derives the MCP-compatible JSON Schema.
• Prettier formats all TypeScript: 4-space indent, double quotes, trailing commas (es5), 80-char print width, LF line endings.
• Conventional commits are enforced by commitlint. Allowed scopes: retrieve, save, search, status, fetch, http, validation, cli, build, release, ci, deps. Commit messages must use British English.
• Test colocation: unit tests in tests/tools/*.unit.test.ts and tests/utils/*.unit.test.ts; integration tests in tests/*.integration.test.ts. Use the Node.js built-in test runner — no Jest or Vitest.
• erasableSyntaxOnly: true — no TypeScript syntax that cannot be stripped without transformation (no enum, no decorators, no namespace).

Gotchas