Mearman/mcp-wayback-machine

> 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.
bash
pnpm install
Optional credentials (anonymous access works, but authenticated requests get higher SPN2 rate limits):
bash
export WAYBACKACCESSKEY="your-access-key"
export WAYBACKSECRETKEY="your-secret-key"
Obtain credentials at archive.org/account/s3.php.
## Build, test, and lint
bash
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:
bash
node --test tests/tools/save.unit.test.ts
End-to-end tests hit the live Wayback Machine API and are opt-in:
bash
pnpm test:e2e # sets WAYBACKLIVETESTS=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 — saveurl tool (SPN2 API)
retrieve.ts — getarchivedurl tool
search.ts — searcharchives tool (CDX API)
status.ts — checkarchivestatus tool (sparkline API)
screenshots.ts — listscreenshots tool
compare.ts — comparesnapshots tool
cache.ts — clearcache 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.