Wayback Machine

MCP Wayback Machine サーバー

Internet Archive の Wayback Machine と連携するための MCP サーバーおよび CLI ツールです。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 で取得できます。

ビルド、テスト、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

単一のテストファイルを実行するには、次のコマンドを使用します。

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 がエントリーポイントです。CLI として実行されたか、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	キャプチャ後は変更されない
Availability、CDX、スパークライン	1 h	増加するが、変更されることはない
保存操作	30 min	URL ごとに冪等
保存状況のポーリング	30 s	処理中に変化する

規約

• noUncheckedIndexedAccess と exactOptionalPropertyTypes を有効にした TypeScript strict モードを使用します。any と as アサーションは禁止です。
• 全体を通して ES Modules を使用します。package.json では "type": "module" を指定します。相対インポートでは常に .ts 拡張子を使います（ビルド時に rewriteRelativeImportExtensions により .js に書き換えられます）。
• Zod をすべてのツール入力形式の唯一の信頼できる情報源とします。schemas.ts で定義し、zodToJsonSchema で MCP 互換の JSON Schema を生成します。
• Prettier で TypeScript 全体をフォーマットします。インデントは 4 スペース、ダブルクォート、末尾のカンマ（es5）、印字幅は 80 文字、改行コードは LF です。
• commitlint により Conventional Commits を適用します。許可されるスコープは 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 ファイルには設定せず、実行前にシェルでエクスポートしてください。
• カバレッジの対象外となるのは src/contexts.ts、src/cli.ts、src/bin.ts、src/tools/context.ts です。これらは配線やエントリーポイントのファイルです。80% のしきい値は、残りのコードに適用されます。
• レート制限は、Wayback Machine API のすべての呼び出しを合わせて 15 req/min です。 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 の規約を適用し、PR では commitlint によるリントチェックを受けます。PR のマージ先は main です。CI の check、test、coverage が成功している必要があります。リリースは main へのプッシュ時に semantic-release によって完全に自動化されます。

リリース後、エイリアスパッケージ（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"
    }
  }
}

実行環境	設定ファイル	設定キー
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 として

ステートレスな Cloudflare Worker として MCP サーバーをデプロイします。有料バインディングなしで 無料プラン で動作します。永続状態はすべて、公開されている日次制限のない Cache API を使用します。

pnpm add -D wrangler
wrangler deploy

Worker は SDK の StreamableHTTPServerTransport をステートレスモード（セッション ID なし）で使用するため、各リクエストは独立しており、コールドスタートにも適切に対応できます。

環境変数（wrangler secret put で設定）：

変数	必須	用途
WAYBACK_ACCESS_KEY	いいえ	SPN2 のレート制限を緩和するための IA S3 認証情報のフォールバック
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 から除外され、@cloudflare/workers-types を追加する tsconfig.worker.json で個別に型チェックされます。

アーキテクチャ。 stdio と Worker のデプロイでは、プラグイン可能なインターフェースを介して同じツールロジックを共有します。

コンポーネント	stdio	Worker
キャッシュ	DiskCacheBackend（OS のキャッシュディレクトリ）	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 を N 秒間実行します（最大 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	いいえ	先頭からスキップする結果数
collapse	いいえ	重複をまとめます。例："timestamp:8"（1 時間単位）、"digest"
filter	いいえ	フィールドの正規表現で絞り込みます。例：["statuscode:200", "!mimetype:image.*"]
resolveRevisits	いいえ	warc/revisit エントリーを元のメタデータに解決します
showDupeCount	いいえ	各キャプチャの重複数を表示します
page	いいえ	ページネーション用のページ番号
pageSize	いいえ	1 ページあたりの結果数

### `check_archive_status`

URL のアーカイブ統計情報を確認します。キャプチャ数、年別の内訳、最初と最後のキャプチャ日時を取得します。

パラメーター

パラメーター	必須	説明
url	はい	確認する URL

list_screenshots

URL で利用可能なスクリーンショットを一覧表示します。

パラメーター

パラメーター	必須	説明
url	はい	スクリーンショットを検索する URL
limit	いいえ	結果の最大数（デフォルトは 10）

compare_snapshots

URL の 2 つのアーカイブ済みスナップショットを比較します。両方の生コンテンツを取得し、ビジュアル差分の URL を提供します。

パラメーター

パラメーター	必須	説明
url	はい	スナップショットを比較する URL
timestampA	いいえ	1 つ目のタイムスタンプ。デフォルトでは利用可能な最も古いものが使用されます。
timestampB	いいえ	2 つ目のタイムスタンプ。デフォルトでは利用可能な最新のものが使用されます。

clear_cache

キャッシュされた API レスポンスをすべて消去します。最新のデータが必要な場合や、新しい URL の保存後に使用してください。

CLI の使用方法

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
• ボット、LLM、自動アクセス
• internet-archive-skills — ia Python CLI 向けの公式 Claude Code スキルです。このサーバーを補完します。

ライセンス

クリエイティブ・コモンズ 表示—非営利—継承 4.0 国際。