archive-zip-unzip-bomb-guard

mcp-zip

今いる会話の中で、ZIP の作成、内容の確認、展開ができます。フォルダーを glob で指定して圧縮できます （**/*.csv、node_modules 以外すべて）。アーカイブを展開せずに、中から README を 1 つ読み取れます。 誰かから送られてきた ZIP の中身を尋ねれば、開く前に、絶対パス、..、シンボリックリンク、 重複した名前、そして 199 KB のファイル内に 200 MB あると申告するエントリーについて教えてくれます。1 か月分の請求書、 見積書、エクスポートを 1 つのファイルにまとめて、会計士に送れます。すべてお使いのマシン上で実行されます。アップロードも、 アカウントも、API キーも、ネットワークへの接続も一切必要ありません。

公式 MCP レジストリ に登録されています（io.github.theluckystrike/zip-archive-create-extract-bomb-guard）。

@theluckystrike/mcp-zip の npm 公開は保留中のため、現時点で npx -y @theluckystrike/mcp-zip を実行すると 404 が返されます。それまでは、ワンクリックで使える .mcpb バンドル、またはクローンしてビルドする方法をご利用ください。

インストール

Claude Desktop の場合、~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に設定します。

{
  "mcpServers": {
    "zip": { "command": "npx", "args": ["-y", "@theluckystrike/mcp-zip"] }
  }
}

Claude Code の場合：

claude mcp add zip -- npx -y @theluckystrike/mcp-zip

Cursor の場合、.cursor/mcp.json に設定します。

{
  "mcpServers": {
    "zip": { "command": "npx", "args": ["-y", "@theluckystrike/mcp-zip"] }
  }
}

ツール

ツール	機能
zip_create	ファイル、または glob パターンで指定したディレクトリーツリーを新しい .zip に圧縮します
zip_list	各エントリーのサイズ、圧縮サイズ、圧縮率を表示し、危険な内容があればすべて警告します
zip_extract	パストラバーサル、シンボリックリンク、ZIP 爆弾を防ぐガードと dry_run を備えて、ディレクトリーに展開します
zip_add	既存のアーカイブにファイルを追加します
zip_extract_text	展開せずに、テキストエントリーを 1 つインラインで読み取ります
zip_bundle_month	兄弟サーバーから 1 か月分の請求書、見積書、エクスポートを 1 つのファイルにまとめます
zip_history	作成したものと、今月の無料利用枠の残りを確認できます
license_status, license_activate	Free または Pro の確認と、キーの有効化を行います

Free と Pro の違い

	Free	Pro
暦月あたりのアーカイブ数	20	無制限
アーカイブのサイズ	最大 25 MB	無制限
アーカイブあたりのエントリー数	最大 200	無制限
読み取り：zip_list、zip_extract、zip_extract_text	無制限	無制限
ZIP 爆弾、パストラバーサル、シンボリックリンクに対するガード	あり	あり

読み取りは使用量にカウントされません。無料プランに制限があるのは、書き込みだけです。誰かから送られてきたアーカイブこそ、開く前に確認する必要があるものであり、安全確認の前にペイウォールを設けることになれば、その安全確認をペイウォールで遮ることになるからです。

Pro を入手するには、https://mcp.zovo.one/buy/zip をご覧ください。1 回限りの $19、またはスイート内のすべてのサーバーを利用できる $39 で、いずれも永久ライセンスです。キーはオフラインで検証され、外部に情報が送信されることはありません。

手書きのライターではなくfflateを選んだ理由

選択肢は、fflate（純粋なJS、依存関係なし、同期的なzipSync／inflateSync）と、依存関係がまったく不要なnode:zlibを使ってSTORE／DEFLATEライターを書くことでした。

どちらを選んでも、ここではコンテナ形式を記述します。このサーバーはsrc/zipfile.tsで中央ディレクトリを自前で読み取ります。サイズ、名前、メソッド、CRC、外部属性など、およそ200行にわたります。サーバーの各ガードは、展開する前にヘッダーから判断するため、これは必須です。{name: bytes}を返すライブラリでは、中身を確認できる時点ですでに爆弾が展開されています。そのため、ライブラリを使う理由は「形式の実装を省けること」ではありませんでした。

残るのは圧縮処理ですが、ここは自分で実装すべきではありません。node:zlibでも処理できますが、raw-deflate呼び出しは非同期が前提で、呼び出しごとにスレッドプールを経由します。また、同期版は呼び出すたびにネイティブストリームを作成します。小さなファイルを200個まとめる場合、これが200回発生します。fflateのdeflateSyncは、ネイティブハンドルを使わない純粋なJSの実装で、200個のファイルを74ミリ秒で圧縮します（以下で計測）。さらに、パッケージにネイティブビルドの手順を追加せずに済みます。これはこのスイート全体のルールです。npxがどこでも動作する必要があります。

トレードオフは明確です。fflateはアーカイブを1つのバッファーに構築するため、このサーバーはストリーミングできるかのように装わず、512 MBを超える入力を拒否します。また、ZIP64（4 GB超、または65,535件を超えるエントリー）は読み取りません。誤読するのではなく、ZIP64であることを検出して拒否します。

計測結果：ファイルの種類ではなく、繰り返しが圧縮率を左右します

以下のファイルはすべて、このマシンでレベル6を指定してZIP圧縮しました。「種類」は人がファイルをどう呼ぶか、「圧縮率」は実際の結果を示しています。

ファイル	種類	バイト数	圧縮後	圧縮率
mcp-pdfの12ページの請求書	PDF	15,125	14,118	1.07x
mcp-docxの400段落の契約書	DOCX	9,897	7,311	1.35x
値にばらつきのある請求CSV 4,000行	CSV	321,329	134,049	2.40x
このサーバー自身のindex.ts	ソースコード	39,498	11,938	3.31x
package-lock.json	JSON	138,835	33,223	4.18x
アプリのログ20,000行	ログ	1,603,390	106,261	15.09x
クライアント名40件を繰り返した請求CSV 4,000行	CSV	338,549	4,094	82.69x
ゼロバイト50 MB	爆弾	52,428,800	51,294	1022x

PDFとDOCXはほとんどサイズが変わりません。中身を見れば意外ではありません。どちらもすでにdeflate形式のコンテナなので、もう一度ZIP圧縮しても、圧縮ではなくパッケージングにすぎません。請求書を1か月分まとめるのは、1つのファイルにする点では有用ですが、容量の削減にはなりません。

興味深いのは、CSVの2行です。同じツール、同じ形式、同じようなサイズでも、34倍の差があります。クライアント名40件を繰り返すデータは82.69倍に圧縮され、値がすべて異なるデータは2.40倍でした。「CSVである」という情報だけでは、どちらなのかは予測できません。

計測結果：爆弾の上限を50倍ではなく100倍にする理由

圧縮爆弾は圧縮率で拒否されます。そこで、ゼロのファイルが達する1022倍より十分に低く、上限を低めに設定したくなるのは自然です。しかし、上の表が示すように、それは誤りです。経費トラッカーからzip_bundle_monthが収集するような実際のCSVエクスポートでは、82.69倍に達しました。これは100倍の上限の83％に相当し、50倍を大きく上回ります。爆弾より十分に低くなるように調整した上限では、実際の月次エクスポートまで拒否してしまいます。そうなると、利用者はすべての処理でmax_ratioを渡すようになり、ガードが恒久的に無効化されます。

そのため、圧縮率は2番目のガードであり、1番目ではありません。最初にチェックするのは合計サイズです。選択したエントリーについて、申告されている展開後のサイズを合計し、上限（デフォルトでは1 GB。変更するにはmax_total_mbを指定します）と比較します。199 KBのファイルから200 MBが展開されるかどうかは、個々のエントリーを評価せずにアーカイブ全体について判断できるからです。どちらの情報も中央ディレクトリから読み取れるため、爆弾を拒否するのに展開処理は一切必要ありません。

refuse a 500 MB bomb (497.8 KB on disk)   3 ms, nothing inflated, out_dir not even created

実測：上限付き出力バッファーは爆弾対策にはなりません

fflate.inflateSync(data, { out: new Uint8Array(n) }) で解決するように見えます。バッファーに上限を設ければ、被害も抑えられるというわけです。しかし、実際にはそうではなく、問題が起きても気づきにくい形で現れます。100,000 バイトのエントリーを 10 バイトのバッファーに展開すると、10 バイトが返され、例外は発生しません。100 KB のエントリーに対してヘッダーが 10 バイトと宣言しているアーカイブは、10 バイトのファイルとして展開され、成功と報告されますが、切り詰められたことは見えません。

つまり、バッファーでメモリを制限し、中央ディレクトリの CRC-32 でバイト列を検証します。このサーバーが書き出すすべてのエントリーは、ディスクに書き込まれる前にヘッダーと照合してチェックサムが検証され、不一致があればエントリー名を示して拒否されます。このチェックにより、偽りのヘッダーによるサイレントなデータ損失を、エラーとして明示できます。

処理時間

M シリーズのノートパソコン、stdio 経由、1 回あたり、コールドストア：

操作	実測値
zip_create、200 ファイル、4.0 MB	74 ms
zip_list、200 エントリー	2 ms
zip_extract、200 エントリー	47 ms
zip_extract_text、1 エントリー	1 ms
500 MB の爆弾を拒否	3 ms
テストスイート全体、38 テスト、5 ファイル	3.9 s

プライバシー

すべての処理はお使いのマシン上で完結します。このサーバーにはネットワークコードが一切ありません。fetch も HTTP クライアントもテレメトリーもありません。アーカイブは指定した場所に書き込まれ、作成したものを記録する小さなレジストリは ~/.local/share/mcp-servers/zip/（または $XDG_DATA_HOME）に保存されます。ライセンスキーは公開鍵を使ってオフラインで検証されます。

Zip パスワードには対応しておらず、渡された場合は無視せず拒否します。従来の Zip 暗号は破られており、AES Zip 暗号化はベンダー拡張で、ツール間で仕様が統一されていません。そのため、ここで作成した「パスワード保護」アーカイブは、誤解を招くものになってしまいます。

theluckystrike が開発しました。サポート：[email protected]

これらのドキュメントを MCP サーバーとして使用する

あらゆる MCP クライアント（Claude、Cursor、Windsurf、VS Code）から、インストール不要で GitMCP 経由でこのリポジトリのドキュメントを直接読み取れます。

• ドキュメント MCP URL：https://gitmcp.io/theluckystrike/mcp-zip