Content
# Compress Files
[](https://smithery.ai/server/@tuskermanshu/compress-mcp-server)
An MCP server implemented based on TypeScript and the fastmcp framework, featuring file compression and decompression capabilities.
## Project Overview
This project utilizes Model Context Protocol (MCP) technology, combined with the fastmcp framework, to create an MCP server that provides file compression and decompression services. The server will be able to receive compression and decompression requests from clients, process the files, and return the results.
## Technology Stack
- TypeScript
- fastmcp
- pnpm (package management)
- node-zlib (for gzip compression)
- tar & tar-stream (for folder compression/decompression)
- jszip (for ZIP format support)
- node-7z (for 7z format support)
- zod (for parameter validation)
## Project Features
- Fully compliant tool implementation with MCP specifications
- Strict parameter validation and type checking
- Detailed progress reporting
- Accurate error handling
- Friendly user feedback
- Secure file handling (prevention of path traversal attacks)
- Support for multiple compression formats
- Standardized return format
## Architectural Design
The project adopts a modular and extensible architecture, based on the strategy pattern and factory pattern, making it easy to add new compression formats.
### Core Components
1. **CompressionHandler Interface**:
- Defines the methods that all format handlers must implement
- Includes three main functionalities: compress, decompress, and list contents
- Provides format validation and metadata access methods
2. **FormatRegistry**:
- Manages all registered format handlers
- Looks up corresponding handlers by format name or file extension
- Supports dynamic registration of new handlers
3. **UnifiedCompressionTool**:
- Provides a single entry point for tools
- Parses parameters and routes to the appropriate handler instance
- Standardizes input and output
4. **CompressionUtils**:
- Provides common functionalities shared by all handlers
- Handles path normalization, file existence checks, etc.
- Formats error messages and operation results
### Extension Method
To add a new compression format, simply follow these steps:
1. Create a new format handler class that implements the CompressionHandler interface
2. Register the new handler in the main program
3. No need to modify the unified tool interface or other components
For example, to add support for the new RAR format:
```typescript
// 1. Create RAR handler class
class RarHandler implements CompressionHandler {
// Implement necessary methods
}
// 2. Add in the registration function
function registerHandlers() {
// Existing handlers
registry.register('gzip', new GzipHandler());
// Add new RAR handler
registry.register('rar', new RarHandler());
}
```
### Architectural Advantages
1. **Separation of Concerns** - Each handler only focuses on its own format implementation
2. **Highly Extensible** - Easily add support for new formats
3. **Code Reusability** - Share common functionalities, reducing duplicate code
4. **Good Maintainability** - Modifying one format does not affect others
5. **Ease of Testing** - Each component can be tested individually
## Implementation Steps
### 1. Project Initialization and Environment Setup
- [x] Create project directory
- [x] Initialize pnpm project
- [x] Install necessary dependencies (fastmcp, typescript, etc.)
- [x] Configure TypeScript
### 2. Server Infrastructure Design
- [x] Create main server file
- [x] Configure basic server parameters
- [x] Set up server startup configuration
### 3. Compression Tool Functionality Implementation
- [x] Design compression file tool
- [x] Implement single file compression functionality
- [x] Implement multi-file/directory compression functionality
- [x] Support multiple compression formats (tar.gz, zip, 7z)
### 4. Decompression Tool Functionality Implementation
- [x] Design decompression file tool
- [x] Implement decompression functionality
- [x] Add decompression path selection functionality
### 5. Resource Management Functionality
- [x] Implement preview functionality for compressed files
- [x] Implement content listing functionality for compressed files
### 6. User Interaction Optimization
- [x] Add progress reporting functionality
- [x] Implement error handling mechanism
- [x] Add security mechanisms (path validation, etc.)
- [x] Implement standardized return format
### 7. MCP Specification Compatibility
- [x] Update tool output format to comply with MCP specifications
- [x] Add isError flag
- [x] Standardize content field
- [x] Use typed text returns
### 8. Tool Architecture Optimization
- [x] Refactor into a modular architecture
- [x] Implement format handler interface
- [x] Create format registry
- [x] Design unified tool interface
### 9. Testing and Deployment
- [x] Basic functionality testing
- [ ] Write unit tests
- [ ] Conduct integration testing
- [ ] Optimize performance
- [ ] Prepare deployment documentation
## Current Progress
The basic server architecture design and main functionality implementation have been completed, supporting multiple compression formats. The latest version adopts a modular and extensible architecture, facilitating future expansion and maintenance.
### Supported Compression Formats:
1. **gzip format**: Suitable for single file compression
2. **tar.gz format**: Suitable for folder compression
3. **ZIP format**: A universal compression format that supports files and folders
4. **7z format**: A high compression ratio format that supports files and folders
All tools have been comprehensively upgraded with the following features:
- Strict parameter validation and type checking (using zod)
- Secure file path handling (preventing path traversal attacks)
- Detailed progress reporting (supporting real-time progress percentage)
- Accurate error handling and friendly error messages
- Standardized MCP return format
## Directory Structure
```
src/
├── handlers/ # Specific handler implementations for various formats
│ ├── gzip-handler.ts # GZIP format handler
│ ├── tar-gz-handler.ts # TAR.GZ format handler
│ ├── zip-handler.ts # ZIP format handler
│ └── 7z-handler.ts # 7Z format handler
├── interfaces/ # Interface definitions
│ └── compression-handler.ts # Compression handler interface
├── registry/ # Handler registry
│ └── format-registry.ts # Format registry implementation
├── tools/ # MCP tool definitions
│ ├── unified-compression.ts # Unified compression tool
│ └── legacy/ # Legacy tools (for compatibility)
├── utils/ # Common utility classes
│ └── compression-utils.ts # Common functionalities related to compression
└── index.ts # Main entry point
```
## Next Steps
1. Complete the implementation of other format handlers
2. Optimize compression and decompression performance
3. Add support for more formats (e.g., rar)
4. Implement streaming processing to support larger files
5. Add file encryption/decryption functionality
6. Write test cases
7. Publish to NPM
## Installation Methods
### Installing via Smithery
To install the compression server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@tuskermanshu/compress-mcp-server):
```bash
npx -y @smithery/cli install @tuskermanshu/compress-mcp-server --client claude
```
### Manual Installation
1. Clone this repository
```bash
git clone <repository-url>
cd zip-mcp-server
```
2. Install dependencies
```bash
pnpm install
```
3. Build the project
```bash
pnpm build
```
4. Run the server
```bash
# Start directly
pnpm start
# Development mode
pnpm dev
# Test with MCP Inspector
pnpm inspect
```
## Available Tools
### Unified Compression Tool (Recommended)
| Tool Name | Description | Main Parameters |
|-----------|-------------|-----------------|
| `compression` | A unified tool for compressing/decompressing/listing, supporting multiple formats | operation, format, sourcePath, outputDirectory, outputFileName, compressionLevel, stripComponents, previewLength |
### Original Standalone Tools (Deprecated)
| Tool Name | Description | Main Parameters |
|-----------|-------------|-----------------|
| `zip` | Compress a single file to gzip format | sourceFilePath, outputDirectory, outputFileName, compressionLevel |
| `unzip` | Decompress files in gzip format | sourceFilePath, outputDirectory, outputFileName |
| `list-zip-contents` | List the contents of a compressed file | sourceFilePath, previewLength |
| `zip-folder` | Compress a folder to tar.gz format | sourceFolderPath, outputDirectory, outputFileName, compressionLevel |
| `unzip-folder` | Decompress a tar.gz compressed folder | sourceArchivePath, outputDirectory, stripComponents |
| `zip-archive` | Compress files or folders using ZIP format | sourcePath, outputDirectory, outputFileName, compressionLevel |
| `7z-archive` | Compress files or folders using 7z format | sourcePath, outputDirectory, outputFileName, compressionLevel |
## Supported Compression Formats
| Format | Features | Applicable Scenarios |
|--------|----------|----------------------|
| gzip (.gz) | Single file compression, fast speed | Single text files, log files, etc. |
| tar.gz | Preserves directory structure, commonly used in Unix/Linux | Folder compression, especially on Unix/Linux systems |
| ZIP (.zip) | Universal format, good compatibility | Cross-platform scenarios, needs to be shared with Windows users |
| 7z (.7z) | High compression ratio | Large file compression, requires higher compression rates |
## Unified Compression Tool Detailed Description
The new version adopts a unified compression tool interface, providing a consistent user experience and a simpler interface.
### compression (Unified Compression Tool)
A one-stop tool that supports multiple compression formats and operations, including compressing, decompressing, and viewing file contents.
Parameters:
- `operation`: Type of operation (required)
- `compress`: Compress files or folders
- `decompress`: Decompress files
- `list`: List contents of compressed files
- `format`: Compression format (required)
- `gzip`: Single file compression format
- `tar.gz`: Folder compression format
- `zip`: Universal ZIP compression format
- `7z`: High compression ratio 7z format
- `sourcePath`: Path of the source file or folder (required)
- `outputDirectory`: Output directory, defaults to the directory of the source file/folder
- `outputFileName`: Output file name, automatically generated based on source name and format by default
- `compressionLevel`: Compression level (1-9), defaults to 6
- `stripComponents`: Number of directory levels to ignore when decompressing (only for tar.gz)
- `previewLength`: Preview length (in bytes) when listing contents, defaults to 1000
## Extension Guide
### Adding a New Compression Format
1. Create a new handler class file in the `src/handlers` directory, for example, `rar-handler.ts`
2. Implement all methods of the `CompressionHandler` interface
3. Register the new handler in the `registerHandlers` function in `src/index.ts`
```typescript
// src/handlers/rar-handler.ts
export class RarHandler implements CompressionHandler {
// Implement all necessary interface methods
}
// src/index.ts
function registerHandlers() {
// ...other handlers
registry.register('rar', new RarHandler());
}
```
No other code modifications are needed; the unified tool will automatically support the new format.
## Usage Examples
After connecting to this server using Claude or other MCP-supporting tools, you can use the following example commands:
### Compressing a file using the unified tool (gzip):
```
The compression tool can handle various compression formats, for example:
{
"operation": "compress",
"format": "gzip",
"sourcePath": "/path/to/file.txt",
"compressionLevel": 6
}
```
### Compressing a folder using the unified tool (tar.gz):
```
The compression tool can handle folder compression:
{
"operation": "compress",
"format": "tar.gz",
"sourcePath": "/path/to/folder",
"compressionLevel": 9
}
```
### Decompressing a ZIP file using the unified tool:
```
The compression tool can decompress various formats:
{
"operation": "decompress",
"format": "zip",
"sourcePath": "/path/to/archive.zip",
"outputDirectory": "/path/to/output"
}
```
### Viewing contents of a 7z file using the unified tool:
```
The compression tool can list contents of compressed files:
{
"operation": "list",
"format": "7z",
"sourcePath": "/path/to/archive.7z"
}
```
## Version History
### v2.1.0
- Refactored into a modular and extensible architecture
- Implemented format handler interface design
- Created format registry
- Improved error handling and progress reporting
### v2.0.0
- Refactored into a unified compression tool interface
- Supported consistent parameter structure
- Improved error handling and progress reporting
### v1.0.0
- Initial version
- Supported multiple standalone compression and decompression tools
## Security Notes
This project implements various security mechanisms:
1. **Path Validation** - Prevents path traversal attacks, ensuring users cannot access arbitrary files on the system
2. **Parameter Validation** - Uses the zod library for strict input validation
3. **Error Handling** - Catches all possible errors and provides friendly prompts without leaking system information
4. **File Name Safety Checks** - Ensures file names do not contain path separators
## Contribution Guidelines
Contributions to this project are welcome! Please fork the project, create a branch, submit changes, and initiate a pull request.
## License
MIT License
