Compress Files
基于TypeScript和fastmcp框架实现的具有文件压缩和解压功能的MCP服务器。
项目概述
本项目使用Model Context Protocol (MCP)技术，结合fastmcp框架，实现一个可以提供文件压缩和解压缩服务的MCP服务器。服务器将能够接收客户端的压缩和解压缩请求，处理文件，并返回结果。
技术栈
- TypeScript
- fastmcp
- pnpm (包管理)
- node-zlib (用于gzip压缩功能)
- tar & tar-stream (用于文件夹压缩/解压)
- jszip (用于ZIP格式支持)
- node-7z (用于7z格式支持)
- zod (用于参数验证)
项目特点
- 完全符合MCP规范的工具实现
- 严格的参数验证和类型检查
- 详细的进度报告
- 精确的错误处理
- 友好的用户反馈
- 安全的文件处理（防止路径遍历攻击）
- 多种压缩格式支持
- 标准化的返回格式
架构设计
项目采用模块化、可扩展的架构，基于策略模式和工厂模式，使得添加新的压缩格式变得简单。
核心组件
- 压缩处理器接口 (CompressionHandler)：
- 定义了所有格式处理器必须实现的方法 - 包括压缩、解压和内容列表三个主要功能 - 提供格式检验和元数据访问方法
- 格式注册表 (FormatRegistry)：
- 管理所有已注册的格式处理器 - 根据格式名称或文件扩展名查找对应处理器 - 支持动态注册新的处理器
- 统一压缩工具 (UnifiedCompressionTool)：
- 提供单一工具入口 - 解析参数并路由到相应的处理器实例 - 标准化输入和输出
- 公共工具类 (CompressionUtils)：
- 提供所有处理器共享的通用功能 - 处理路径规范化、文件存在检查等 - 格式化错误消息和操作结果
扩展方式
添加新的压缩格式只需要以下步骤：
- 创建新的格式处理器类，实现CompressionHandler接口
- 在主程序中注册新的处理器
- 无需修改统一工具接口或其他组件
例如，添加新的RAR格式支持：
// 1. 创建RAR处理器类
class RarHandler implements CompressionHandler {
// 实现必要的方法
}
// 2. 在注册函数中添加
function registerHandlers() {
// 现有处理器
registry.register('gzip', new GzipHandler());
// 添加新的RAR处理器
registry.register('rar', new RarHandler());
}架构优势
- 关注点分离 - 每个处理器只关心自己的格式实现
- 高度可扩展 - 轻松添加新的格式支持
- 代码复用 - 共享通用功能，减少重复代码
- 维护性好 - 修改一个格式不会影响其他格式
- 便于测试 - 可以单独测试每个组件
实施步骤
1. 项目初始化与环境搭建
- [x] 创建项目目录
- [x] 初始化pnpm项目
- [x] 安装必要依赖(fastmcp, typescript等)
- [x] 配置TypeScript
2. 服务器基础架构设计
- [x] 创建主服务器文件
- [x] 配置服务器基本参数
- [x] 设置服务器启动配置
3. 压缩工具功能实现
- [x] 设计压缩文件工具
- [x] 实现单文件压缩功能
- [x] 实现多文件/目录压缩功能
- [x] 支持多种压缩格式(tar.gz, zip, 7z)
4. 解压工具功能实现
- [x] 设计解压文件工具
- [x] 实现解压缩功能
- [x] 添加解压路径选择功能
5. 资源管理功能
- [x] 实现压缩文件预览功能
- [x] 实现压缩文件内容列表功能
6. 用户交互优化
- [x] 添加进度报告功能
- [x] 实现错误处理机制
- [x] 添加安全机制（路径验证等）
- [x] 实现标准化返回格式
7. MCP规范兼容性
- [x] 更新工具输出格式以符合MCP规范
- [x] 添加isError标识
- [x] 标准化content字段
- [x] 使用类型化的text返回
8. 工具架构优化
- [x] 重构为模块化架构
- [x] 实现格式处理器接口
- [x] 创建格式注册表
- [x] 统一工具接口设计
9. 测试与部署
- [x] 基本功能测试
- [ ] 编写单元测试
- [ ] 进行集成测试
- [ ] 优化性能
- [ ] 准备部署文档
当前进度
目前已完成基本的服务器架构设计和主要功能实现，支持多种压缩格式。最新版本采用模块化、可扩展的架构，便于后续扩展和维护。
支持的压缩格式:
- gzip格式：适用于单个文件压缩
- tar.gz格式：适用于文件夹压缩
- ZIP格式：通用的压缩格式，支持文件和文件夹
- 7z格式：高压缩率格式，支持文件和文件夹
所有工具都经过全面升级，具有以下功能：
- 严格的参数验证和类型检查（使用zod）
- 安全的文件路径处理（防止路径遍历攻击）
- 详细的进度报告（支持实时进度百分比）
- 精确的错误处理和友好的错误信息
- 标准化的MCP返回格式
目录结构
src/
├── handlers/ # 各种格式的具体处理器实现
│ ├── gzip-handler.ts # GZIP格式处理器
│ ├── tar-gz-handler.ts # TAR.GZ格式处理器
│ ├── zip-handler.ts # ZIP格式处理器
│ └── 7z-handler.ts # 7Z格式处理器
├── interfaces/ # 接口定义
│ └── compression-handler.ts # 压缩处理器接口
├── registry/ # 处理器注册表
│ └── format-registry.ts # 格式注册表实现
├── tools/ # MCP工具定义
│ ├── unified-compression.ts # 统一压缩工具
│ └── legacy/ # 旧版工具（保持兼容）
├── utils/ # 通用工具类
│ └── compression-utils.ts # 压缩相关通用功能
└── index.ts # 主入口点下一步计划
- 完成其他格式处理器的实现
- 优化压缩和解压性能
- 添加更多格式支持（如rar等）
- 实现流式处理以支持更大文件
- 添加文件加密/解密功能
- 编写测试用例
- 发布至NPM
安装方法
Installing via Smithery
To install 压缩功能服务器 for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @tuskermanshu/compress-mcp-server --client claudeManual Installation
- 克隆本仓库
git clone
cd zip-mcp-server- 安装依赖
pnpm install- 构建项目
pnpm build- 运行服务器
# 直接启动
pnpm start
# 开发模式
pnpm dev
# 使用MCP Inspector测试
pnpm inspect可用工具
统一压缩工具（推荐使用）
| 工具名称 | 描述 | 主要参数 |
|---|---|---|
compression | 统一的压缩/解压/列表工具，支持多种格式 | operation, format, sourcePath, outputDirectory, outputFileName, compressionLevel, stripComponents, previewLength |
原版独立工具（已弃用）
| 工具名称 | 描述 | 主要参数 |
|---|---|---|
zip | 压缩单个文件为gzip格式 | sourceFilePath, outputDirectory, outputFileName, compressionLevel |
unzip | 解压gzip格式的文件 | sourceFilePath, outputDirectory, outputFileName |
list-zip-contents | 列出压缩文件的内容预览 | sourceFilePath, previewLength |
zip-folder | 压缩文件夹为tar.gz格式 | sourceFolderPath, outputDirectory, outputFileName, compressionLevel |
unzip-folder | 解压tar.gz格式的压缩文件夹 | sourceArchivePath, outputDirectory, stripComponents |
zip-archive | 使用ZIP格式压缩文件或文件夹 | sourcePath, outputDirectory, outputFileName, compressionLevel |
7z-archive | 使用7z格式压缩文件或文件夹 | sourcePath, outputDirectory, outputFileName, compressionLevel |
支持的压缩格式
| 格式 | 特点 | 适用场景 |
|---|---|---|
| gzip (.gz) | 单文件压缩，速度快 | 单个文本文件，日志文件等 |
| tar.gz | 保留目录结构，Unix/Linux常用 | 文件夹压缩，特别是在Unix/Linux系统 |
| ZIP (.zip) | 通用格式，兼容性好 | 跨平台场景，需要分享给Windows用户 |
| 7z (.7z) | 高压缩比 | 大文件压缩，需要更高压缩率 |
统一压缩工具详细说明
新版本采用统一的压缩工具接口，提供一致的用户体验和更简单的接口。
compression (统一压缩工具)
一站式工具，支持多种压缩格式和操作，包括压缩、解压和查看文件内容。
参数：
operation: 操作类型（必需）
- compress: 压缩文件或文件夹 - decompress: 解压文件 - list: 列出压缩文件内容
format: 压缩格式（必需）
- gzip: 单文件压缩格式 - tar.gz: 文件夹压缩格式 - zip: 通用ZIP压缩格式 - 7z: 高压缩比7z格式
sourcePath: 源文件或文件夹路径（必需）outputDirectory: 输出目录，默认为源文件/文件夹所在目录outputFileName: 输出文件名，默认基于源名称和格式自动生成compressionLevel: 压缩级别(1-9)，默认为6stripComponents: 解压时忽略的目录层级数量（仅用于解压tar.gz）previewLength: 列出内容时的预览长度（字节数），默认为1000
扩展指南
添加新的压缩格式
- 在
src/handlers目录下创建新的处理器类文件，例如rar-handler.ts - 实现
CompressionHandler接口的所有方法 - 在
src/index.ts中的registerHandlers函数中注册新的处理器
// src/handlers/rar-handler.ts
export class RarHandler implements CompressionHandler {
// 实现所有必要的接口方法
}
// src/index.ts
function registerHandlers() {
// ...其他处理器
registry.register('rar', new RarHandler());
}不需要修改任何其他代码，统一工具会自动支持新的格式。
使用示例
使用Claude或其他支持MCP的工具连接到本服务器后，可以使用以下示例命令：
使用统一工具压缩文件(gzip):
compression工具可以处理多种压缩格式，例如:
{
"operation": "compress",
"format": "gzip",
"sourcePath": "/path/to/file.txt",
"compressionLevel": 6
}使用统一工具压缩文件夹(tar.gz):
compression工具可以处理文件夹压缩:
{
"operation": "compress",
"format": "tar.gz",
"sourcePath": "/path/to/folder",
"compressionLevel": 9
}使用统一工具解压ZIP文件:
compression工具可以解压多种格式:
{
"operation": "decompress",
"format": "zip",
"sourcePath": "/path/to/archive.zip",
"outputDirectory": "/path/to/output"
}使用统一工具查看7z文件内容:
compression工具可以列出压缩文件内容:
{
"operation": "list",
"format": "7z",
"sourcePath": "/path/to/archive.7z"
}版本历史
v2.1.0
- 重构为模块化、可扩展架构
- 实现格式处理器接口设计
- 创建格式注册表
- 改进错误处理和进度报告
v2.0.0
- 重构为统一压缩工具接口
- 支持一致的参数结构
- 改进错误处理和进度报告
v1.0.0
- 初始版本
- 支持多种独立的压缩和解压工具
安全说明
本项目实现了多种安全机制：
- 路径验证 - 防止路径遍历攻击，确保用户不能访问系统上的任意文件
- 参数验证 - 使用zod库进行严格的输入验证
- 错误处理 - 捕获所有可能的错误并提供友好的提示，不泄露系统信息
- 文件名安全检查 - 确保文件名不包含路径分隔符
贡献指南
欢迎对本项目做出贡献！请fork项目，创建分支，提交变更后发起pull request。
许可证
MIT许可证