A lightweight batch decompression tool for compressed files based on TypeScript, Bun and Node-7z, supporting decompression of various formats of compressed files (such as zip, 7z, etc.) and password-protected file decompression 📦🔑

简体中文 | English

• 📂 Recursively decompress all compressed files in a directory, maintaining the original directory structure
• 🗂️ Supports multiple compression formats (zip, rar, 7z, etc.)
• 🔐 Supports decompression of password-protected compressed files
• ⚡ Supports concurrent decompression, fully utilizing multi-core CPU performance
• 🚫 Can filter specific files or directories through command line parameters
• ⚙️ Supports custom maximum concurrency
• 🔑 Supports specifying different passwords for different files
• 📊 Detailed processing logs and statistics
• 📍 Supports specifying whether to create subdirectories with the same name
• 🙈 Supports ignoring specific files/directories when scanning compressed files, hidden files are ignored by default
• 📄 Supports decompressing single files
• 📝 Log output location can be controlled
• 🤖 Supports Model Context Protocol (MCP) for AI integration

Make sure you have Bun environment installed:

curl -fsSL https://bun.sh/install | bash

Install globally via bun:

bun add uzdir -g

Or clone the project and install dependencies:

git clone <repository-url>
cd uzdir
bun install

After installation, you can directly use the uzdir command:

uzdir -i <input directory> -o <output directory> [-p <password>] [--filter <filter path>] [--maxConcurrency <concurrency>] [--zipFormat <format>] [--passwordMap <password mapping file>] [--fullpath <true|false>]

Or run in the project directory:

bun run uzdir -- -i <input directory> -o <output directory> [-p <password>] [--filter <filter path>] [--maxConcurrency <concurrency>] [--zipFormat <format>] [--passwordMap <password mapping file>] [--fullpath <true|false>]

UZDir supports the Model Context Protocol (MCP), allowing AI models to directly interact with the tool. This enables AI assistants to decompress files and create password maps programmatically.

To start the MCP server, run:

uzdir mcp

The MCP server implements the standard MCP protocol and provides two tools:

1. extract_directory - Recursively decompresses all specified compressed files in a directory
2. create_password_map - Creates a password mapping file

When an AI model connects to the MCP server, it can discover and use these tools through the standard MCP protocol.

UZDir supports switching between English (default) and Chinese languages:

# View current language and available languages
uzdir lang

# Switch to Chinese
uzdir lang zh_CN

# Switch to English
uzdir lang en_US

Language settings are persisted in the configuration file at ~/.uzdir/config.json.

• -i, --input <dir>: Input directory path or compressed file path (required)
• -o, --output <dir>: Output directory path (required)
• -p, --password <password>: Decompression password (optional, no password by default)
• --filter <filterpaths>: File paths to filter (relative paths within the compressed package), multiple paths separated by commas (optional). Supports glob wildcards:
  • * Matches any name in a single-level directory
  • ** Matches any name in multi-level nested directories
• --maxConcurrency <number>: Maximum concurrency (optional, defaults to CPU core count)
• --zipFormat <formats>: Compressed file formats, multiple formats separated by commas (optional, defaults to .zip,.rar)
• --passwordMap <filepath>: Password mapping JSON file path (optional)
• --ignore <patterns>: Patterns to ignore files/directories, multiple patterns separated by commas, supports simple glob patterns, hidden files are ignored by default
• --log: Whether to output logs to the output directory, default is false
• --fullpath <flag>: Whether to use full path decompression (i.e. create subdirectories with the same name), default is true, setting to false, 0 or '0' and other falsy values will extract all decompressed files to one directory
• -v, --version: Show version information

Using the --passwordMap parameter, you can specify different passwords for different compressed files. This parameter accepts a JSON file path with the following format:

{
  "/absolute/path/to/file1.zip": "password1",
  "/absolute/path/to/file2.7z": "password2",
  "sensitive_folder": "folder_password",
  "protected.rar": "rar_password",
  ".7z": "7z_default_password"
}

Password matching rules:

1. 🔎 Priority matching of complete absolute paths
2. 🧩 Then matching partial paths
3. 📄 Next matching file names
4. 🎯 Finally matching file formats (extensions)
5. 🛡️ If none match, use the default password provided by the -p parameter

Using the --ignore parameter, you can ignore specific files or directories when scanning compressed files. Supports simple glob patterns:

• *.tmp.zip - Ignore all .tmp.zip files
• temp* - Ignore all files/directories starting with temp
• backup - Ignore files/directories named backup

By default, all hidden files and directories starting with . are ignored.

UZDir supports two decompression path modes:

1. Full Path Mode (Default): Use --fullpath true (default value)

   • Maintain the complete directory structure in the compressed file and create subdirectories with the same name

2. Non-Full Path Mode: Use --fullpath false, --fullpath 0 and other falsy values

   • Do not create subdirectories with the same name, only extract files to the specified directory

UZDir supports controlling the log output location:

1. Default Location: Logs are output to the $HOME/.uzdir/logs directory by default
2. Output Directory: Using the --log parameter can output logs to the specified output directory

Decompress all ZIP files in a directory:

uzdir -i ./zips -o ./output

Decompress a single compressed file:

uzdir -i archive.zip -o ./output

Decompress compressed files in multiple formats:

uzdir -i ./archives -o ./output --zipFormat ".zip,.7z,.rar"

Decompress with password:

uzdir -i ./zips -o ./output -p mypassword

Decompress using password mapping file:

uzdir -i ./zips -o ./output --passwordMap passwords.json

Use default password and password mapping file simultaneously:

uzdir -i ./zips -o ./output -p defaultpassword --passwordMap passwords.json

Decompress and filter specific files:

uzdir -i ./zips -o ./output --filter unwanted.txt

Decompress and filter multiple files/directories:

uzdir -i ./zips -o ./output --filter unwanted.txt,temp_folder,__MACOSX

Filter files using glob wildcards:

uzdir -i ./zips -o ./output --filter "*/__MACOSX,**/.DS_Store,*.tmp"

Set maximum concurrency:

uzdir -i ./zips -o ./output --maxConcurrency 4

Decompress without creating subdirectories with the same name:

uzdir -i ./zips -o ./output --fullpath false

Use ignore patterns:

uzdir -i ./zips -o ./output --ignore "*.tmp.zip,*.log.zip,backup.7z"

Output logs to the output directory:

uzdir -i ./zips -o ./output --log

The project includes a test script that can be run with the following command:

bun run test

This will execute the preset test command, decompressing compressed files in the test/from directory to the test/to directory.

• Bun - Runtime environment
• TypeScript - Programming language
• commander - Command line argument parsing
• node-7z - 7-Zip wrapper

MIT