Wayback Machine

MCP Wayback Machine 服务

用于与 Internet Archive 的 Wayback Machine 交互的 MCP 服务和命令行工具。支持完整的 CDX 搜索、快照内容检索、截图列表、快照比较，以及可选身份验证，以获得更高的 SPN2 速率限制。

技术栈： TypeScript · Node.js 22+ · ES Modules · pnpm · Turbo · Zod

开始使用

需要 Node.js 22+ 和 pnpm。

pnpm install

可选凭据（可匿名访问，但通过身份验证的请求可获得更高的 SPN2 速率限制）：

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

请在 archive.org/account/s3.php 获取凭据。

构建、测试和代码检查

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

运行单个测试文件：

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

端到端测试会调用 Wayback Machine 的实时 API，需选择启用：

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

pnpm validate 是发布前必须通过的门槛。prepublishOnly 会自动运行它。

架构

src/bin.ts 是入口点。它会检测自身是作为命令行工具调用，还是作为 MCP 服务加载，并据此进行路由。

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

每个工具模块都会导出一个架构（由 ListToolsRequestSchema 使用）和一个执行函数（由 CallToolRequestSchema 使用）。新增工具时，必须在 server.ts 中注册这两项。

缓存 TTL 均为有意设置，请勿统一调整：

资源	TTL	原因
快照内容	24 h	捕获后不可变
可用性、CDX、迷你图	1 h	会增长，但不会发生变化
保存操作	30 min	对每个 URL 都是幂等的
保存状态轮询	30 s	活跃任务期间会变化

约定

• TypeScript 严格模式，启用 noUncheckedIndexedAccess 和 exactOptionalPropertyTypes——不使用 any，不使用 as 断言。
• 全面使用 ES Modules——package.json 中设置 "type": "module"。相对导入始终使用 .ts 扩展名（构建时通过 rewriteRelativeImportExtensions 重写为 .js）。
• Zod 是所有工具输入结构的唯一事实来源。schemas.ts 定义这些结构；zodToJsonSchema 会生成与 MCP 兼容的 JSON Schema。
• Prettier 格式化所有 TypeScript：4 个空格缩进、双引号、尾随逗号（es5）、80 个字符的打印宽度、LF 换行符。
• Conventional commits 由 commitlint 强制执行。允许的作用域：retrieve、save、search、status、fetch、http、validation、cli、build、release、ci、deps。提交消息必须使用英式英语。
• 测试与代码并置：单元测试位于 tests/tools/*.unit.test.ts 和 tests/utils/*.unit.test.ts；集成测试位于 tests/*.integration.test.ts。使用 Node.js 内置测试运行器，不使用 Jest 或 Vitest。
• erasableSyntaxOnly: true——不使用无法在不经过转换的情况下剥离的 TypeScript 语法（不使用 enum、装饰器或 namespace）。

注意事项

• 推送前运行 pnpm validate。 CI 会运行 check + test + coverage + untested-files。pnpm validate 通过 Turbo 在本地复现这些检查。
• Turbo 会积极使用缓存。 如果你修改了 Turbo 未跟踪为输入的配置文件，缓存的任务结果可能会过时。如果结果看起来不正确，请运行 pnpm turbo run <task> --force 清除缓存。
• 运行 test:e2e 必须设置 WAYBACK_LIVE_TESTS。 Turbo 配置通过 globalPassThroughEnv 传递该变量；不要在 .env 文件中设置它，而应在运行前于 shell 中导出。
• 覆盖率统计不包括 src/contexts.ts、src/cli.ts、src/bin.ts 和 src/tools/context.ts——这些是连接和入口文件。80% 的门槛适用于其余代码。
• 所有 Wayback Machine API 调用的速率限制为每分钟 15 次，并会自动处理 429 响应中的 Retry-After。使用模拟 HTTP 的测试必须遵守此限制——不要在单元测试中调用真实端点。
• noUncheckedIndexedAccess 意味着 Record<string, T> 查找返回 T | undefined。不要使用 ?? default 作为回退——请显式缩小类型范围，或重构为具体类型。
• Node 版本在 .tool-versions 中固定。CI 会针对 Node 22、24 和 26 进行测试。请勿使用 Node 22 中不可用的 Node API。

贡献

提交信息遵循 Conventional Commits 规范，并由 commitlint 在 PR 中检查。PR 以 main 为目标分支；CI 必须通过（check、test、coverage）。发布完全通过 semantic-release 在推送到 main 时自动完成。

发布后，别名包（wayback-machine-mcp、mcp-internet-archive、internet-archive-mcp、@mearman/mcp-wayback-machine）会由 CI 自动发布——请勿手动发布。

安装

作为 MCP 服务

CLI 简写

Claude Code（MCP）：

claude mcp add wayback-machine -- npx -y mcp-wayback-machine

Claude Code（插件市场）：

/plugin marketplace add https://github.com/Mearman/mcp-wayback-machine.git
/plugin install mcp-wayback-machine@mcp-wayback-machine

OpenAI Codex：

codex mcp add wayback-machine -- npx -y mcp-wayback-machine

如需包含可选凭据：

claude mcp add wayback-machine --env WAYBACK_ACCESS_KEY=xxx --env WAYBACK_SECRET_KEY=xxx -- npx -y mcp-wayback-machine

手动配置

添加到相应的配置文件中：

{
  "wayback-machine": {
    "command": "npx",
    "args": ["-y", "mcp-wayback-machine"],
    "env": {
      "WAYBACK_ACCESS_KEY": "your-access-key",
      "WAYBACK_SECRET_KEY": "your-secret-key"
    }
  }
}

Harness	配置文件	配置键
Claude Code	.mcp.json（项目）/ ~/.claude.json（用户）	mcpServers
Codex	~/.codex/config.toml	[mcp_servers.wayback-machine]
Gemini CLI	~/.gemini/settings.json	mcpServers
Crush	.crush.json / ~/.config/crush/crush.json	mcp
Cline	.cline/mcp.json	mcpServers
Cursor	.cursor/mcp.json	mcpServers
Zed	~/.config/zed/settings.json	context_servers
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	mcpServers

env 块为可选项——无需凭据，服务也可以匿名运行。

作为 CLI 工具

npx mcp-wayback-machine save https://example.com

或全局安装：

npm install -g mcp-wayback-machine
wayback save https://example.com

作为 Cloudflare Worker

将 MCP 服务部署为无状态 Cloudflare Worker。可在免费套餐上运行，无需付费绑定项——所有持久化状态均使用缓存 API，该 API 没有公布每日限额。

pnpm add -D wrangler
wrangler deploy

Worker 使用 SDK 的 StreamableHTTPServerTransport，并以无状态模式运行（不使用会话 ID），因此每个请求都是独立的，并能妥善处理冷启动。

环境变量（通过 wrangler secret put 设置）：

变量	必需	用途
WAYBACK_ACCESS_KEY	否	备用 IA S3 凭据，用于提高 SPN2 速率限制
WAYBACK_SECRET_KEY	否	备用 IA S3 凭据
MCP_AUTH_TOKEN	否	用于客户端身份验证的 Bearer 令牌

设置 MCP_AUTH_TOKEN 后，客户端必须发送 Authorization: Bearer <token>。未设置时，Worker 接受未经身份验证的请求。

每个请求的凭据。 客户端可以通过 HTTP 标头在每个请求中传入自己的 IA S3 凭据，覆盖服务端的环境变量：

X-Archive-Access-Key: <your-access-key>
X-Archive-Secret-Key: <your-secret-key>

这样，多个用户就可以共用一个 Worker 部署，同时各自使用自己的凭据来提高 SPN2 速率限制。如果两个标头都存在，它们的优先级高于 WAYBACK_ACCESS_KEY/WAYBACK_SECRET_KEY。如果缺少这些标头，Worker 将使用环境变量作为备用凭据。

Worker 专用文件不包含在主 tsconfig.json 中，而是通过 tsconfig.worker.json 单独进行类型检查（该配置会添加 @cloudflare/workers-types）。

架构。 stdio 和 Worker 部署通过可插拔接口共用相同的工具逻辑：

组件	Stdio	Worker
缓存	DiskCacheBackend（操作系统缓存目录）	CacheApiBackend（caches.open()）
速率限制	InMemoryRateLimiter	CacheApiRateLimiter
身份验证	无	StaticTokenAuthProvider（可选）
凭据	环境变量	请求标头，然后是环境变量

快速示例

Archive https://example.com to the Wayback Machine
Find all archived snapshots of https://example.com from 2023
What's the earliest archived version of https://example.com?
Compare the oldest and newest snapshots of https://example.com
Check how many times https://example.com has been archived

工具

save_url

使用 SPN2 API 将 URL 存档到 Wayback Machine。

参数

参数	必需	描述
url	是	要存档的 URL
captureScreenshot	否	截取 PNG 图片格式的屏幕截图
captureOutlinks	否	同时存档最多 100 个外链页面
ifNotArchivedWithin	否	如果在指定时间范围内已有存档则跳过，例如 "30d"
jsBehaviorTimeout	否	捕获前运行 JavaScript 的秒数（最长 30 秒）
forceGet	否	使用简单 HTTP GET，而不是浏览器渲染
delayWbAvailability	否	将索引延迟约 12 小时，以减轻服务端负载

get_archived_url

获取存档快照的内容和元数据。

参数

参数	必需	描述
url	是	要获取的 URL
timestamp	否	指定时间戳（YYYYMMDDhhmmss）或 "latest"
modifier	否	URL 修饰符：id_（原始内容）、im_（屏幕截图）、js_（JS）、cs_（CSS）

search_archives

通过 CDX API 搜索某个 URL 的存档版本。

参数

参数	必需	描述
url	是	要搜索的 URL 模式
matchType	否	exact、prefix、host 或 domain
from	否	开始日期（YYYYMMDD 或 YYYY-MM-DD）
to	否	结束日期（YYYYMMDD 或 YYYY-MM-DD）
limit	否	最大结果数（默认值为 10）
offset	否	跳过前 N 个结果
collapse	否	合并重复项，例如 "timestamp:8"（按小时）或 "digest"
filter	否	按字段正则表达式筛选，例如 ["statuscode:200", "!mimetype:image.*"]
resolveRevisits	否	将 warc/revisit 条目解析为原始元数据
showDupeCount	否	显示每个捕获的重复计数
page	否	分页页码
pageSize	否	每页结果数

### `check_archive_status`

检查 URL 的存档统计信息——抓取次数、按年份细分的数据，以及首次和最近一次抓取日期。

参数

参数	必填	描述
url	是	要检查的 URL

list_screenshots

列出某个 URL 的可用截图。

参数

参数	必填	描述
url	是	要查找截图的 URL
limit	否	结果数量上限（默认值为 10）

compare_snapshots

比较某个 URL 的两个存档快照。获取两者的原始内容，并提供一个可视化差异对比 URL。

参数

参数	必填	描述
url	是	要比较快照的 URL
timestampA	否	第一个时间戳。默认为最早的可用快照。
timestampB	否	第二个时间戳。默认为最新的可用快照。

clear_cache

清除所有缓存的 API 响应。需要获取最新数据或保存新 URL 后使用。

命令行用法

wayback save https://example.com
wayback get https://example.com
wayback get https://example.com --timestamp 20231225120000
wayback search https://example.com --from 2023-01-01 --to 2023-12-31 --limit 20
wayback status https://example.com
wayback screenshots https://example.com
wayback compare https://example.com
wayback compare https://example.com --timestamp-a 20230101000000 --timestamp-b 20240101000000

参考资料

• Internet Archive 开发者门户
• CDX Server 文档
• Save Page Now 2 (SPN2) API
• Bots、LLM 和自动化访问
• internet-archive-skills — 面向 ia Python CLI 的官方 Claude Code 技能；可与此服务配合使用。

许可证

知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议。