ZIP MCP Server

ZIP MCP サーバー

中文 | 英語

プロジェクトの紹介

ZIP MCP サーバーは、fastMCP と zip.js を基盤とする圧縮サーバーで、Model Context Protocol（MCP）を実装しています。このプロジェクトでは、パラメーターを完全に制御できる ZIP 圧縮、解凍、圧縮パッケージ情報の照会機能を提供します。

機能

• ファイルとデータの圧縮および解凍に対応
• 複数ファイルをまとめた圧縮に対応
• 圧縮レベルの制御を提供（0-9）
• パスワード保護と暗号化強度の設定に対応
• 圧縮パッケージのメタデータを照会する機能を提供
• 解凍時に ZIP エントリのパスを検証し、パストラバーサルによる書き込みを防止

セキュリティ

バージョン 1.0.6 以降では、decompress ツールにおける任意のファイル書き込みの問題が修正されています。以前は、悪意のある ZIP エントリ名（例：../outside.txt）が出力ディレクトリと結合され、意図した展開先のルート外に書き込まれる可能性がありました。現在は展開先のルートを一度解決したうえで各エントリのパスを検証し、絶対パス、ドライブ文字を含むパス、.. セグメント、および出力ディレクトリの外に出るパスを拒否します。

この問題を責任ある形で報告してくださった Ryan（[email protected]）に感謝します。

プロジェクト構成

zip-mcp
├── src
│   ├── index.ts               # Application entry point
│   ├── utils
│   │   ├── compression.ts     # Compression and decompression implementation
│   │   └── safePath.ts        # Safe ZIP entry path validation
├── tsconfig.json              # TypeScript configuration file
├── package.json               # npm configuration file
└── README.md                  # Project documentation

インストール

npm を使用して ZIP MCP サーバーをグローバルにインストールできます。

npm install -g zip-mcp

MCP の設定

インストール後、MCP JSON 設定で ZIP MCP を設定できます。

{
  "mcpServers": {
    "zip-mcp": {
      "command": "zip-mcp",
      "args": []
    }
  }
}

AI クライアントでの MCP JSON の設定

• Claude クライアント：https://modelcontextprotocol.io/quickstart/user
• Raycast：MCP プラグインのインストールが必要です
• Cursor：https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

MCP ツールの説明

ZIP MCP サーバーは以下のツールを提供しており、MCP プロトコルを通じて呼び出すことができます。

圧縮ツール（compress）

ローカルのファイルまたはディレクトリを ZIP ファイルに圧縮します。

パラメーター：

• input：圧縮するファイルまたはディレクトリのパス（文字列または文字列配列）
• output：出力する ZIP ファイルのパス
• options：圧縮オプション（任意）
  • level：圧縮レベル（0-9、デフォルトは 5）
  • password：パスワード保護
  • encryptionStrength：暗号化強度（1-3）
  • overwrite：既存のファイルを上書きするかどうか（ブール値）

戻り値：

• 成功：成功情報を含むテキストコンテンツ
• 失敗：エラー情報を含むテキストコンテンツ

解凍ツール（decompress）

ローカルの ZIP ファイルを指定したディレクトリに解凍します。書き込み前にエントリのパスを検証するため、.. や絶対パスを使って output の外にファイルを展開することはできません。

パラメーター：

• input：ZIP ファイルのパス
• output：出力ディレクトリのパス
• options：解凍オプション（任意）
  • password：解凍パスワード
  • overwrite：既存のファイルを上書きするかどうか（ブール値）
  • createDirectories：存在しないディレクトリを作成するかどうか（ブール値）

戻り値：

• 成功：解凍結果の情報を含むテキストコンテンツ
• 失敗：エラー情報を含むテキストコンテンツ

ZIP 情報ツール（getZipInfo）

ローカルの ZIP ファイルのメタデータ情報を取得します。

パラメーター：

• input：ZIP ファイルのパス
• options：オプション（任意）
  • password：解凍パスワード

戻り値：

• 成功：ZIP ファイルの詳細情報を含むテキストコンテンツ。以下の情報が含まれます。
  • ファイルの総数
  • 合計サイズ
  • 圧縮後のサイズ
  • 圧縮率
  • 各ファイルの詳細情報
• 失敗：エラー情報を含むテキストコンテンツ

テストツール（echo）

サービスが正常に動作しているかをテストするため、入力されたメッセージを返します。

パラメーター：

• message：返されるメッセージ

戻り値：

• 入力されたメッセージと現在のタイムスタンプを含むテキストコンテンツ

例

MCP クライアントを使用してツールを呼び出す例：

// Compress files
await client.executeTool("compress", {
  input: "/path/to/files/or/directory",
  output: "/path/to/output.zip",
  options: {
    level: 9,
    comment: "Test compression",
    password: "secret",
    overwrite: true,
  },
});

// Decompress files
await client.executeTool("decompress", {
  input: "/path/to/archive.zip",
  output: "/path/to/extract/directory",
  options: {
    password: "secret",
    overwrite: true,
    createDirectories: true,
  },
});

// Get ZIP info
await client.executeTool("getZipInfo", {
  input: "/path/to/archive.zip",
  options: {
    password: "secret",
  },
});

// Test service
await client.executeTool("echo", {
  message: "Hello, ZIP MCP Server!",
});

お問い合わせ

• メール： [email protected]
• ブログ： https://7gugu.com