compress-mcp-server

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规范的工具实现
• 严格的参数验证和类型检查
• 详细的进度报告
• 精确的错误处理
• 友好的用户反馈
• 安全的文件处理（防止路径遍历攻击）
• 多种压缩格式支持
• 标准化的返回格式

架构设计

项目采用模块化、可扩展的架构，基于策略模式和工厂模式，使得添加新的压缩格式变得简单。

核心组件

1. 压缩处理器接口 (CompressionHandler)：

   • 定义了所有格式处理器必须实现的方法
   • 包括压缩、解压和内容列表三个主要功能
   • 提供格式检验和元数据访问方法

2. 格式注册表 (FormatRegistry)：

   • 管理所有已注册的格式处理器
   • 根据格式名称或文件扩展名查找对应处理器
   • 支持动态注册新的处理器

3. 统一压缩工具 (UnifiedCompressionTool)：

   • 提供单一工具入口
   • 解析参数并路由到相应的处理器实例
   • 标准化输入和输出

4. 公共工具类 (CompressionUtils)：

   • 提供所有处理器共享的通用功能
   • 处理路径规范化、文件存在检查等
   • 格式化错误消息和操作结果

扩展方式

添加新的压缩格式只需要以下步骤：

1. 创建新的格式处理器类，实现CompressionHandler接口
2. 在主程序中注册新的处理器
3. 无需修改统一工具接口或其他组件

例如，添加新的RAR格式支持：

// 1. 创建RAR处理器类
class RarHandler implements CompressionHandler {
  // 实现必要的方法
}

// 2. 在注册函数中添加
function registerHandlers() {
  // 现有处理器
  registry.register('gzip', new GzipHandler());
  
  // 添加新的RAR处理器
  registry.register('rar', new RarHandler());
}

架构优势

1. 关注点分离 - 每个处理器只关心自己的格式实现
2. 高度可扩展 - 轻松添加新的格式支持
3. 代码复用 - 共享通用功能，减少重复代码
4. 维护性好 - 修改一个格式不会影响其他格式
5. 便于测试 - 可以单独测试每个组件

实施步骤

1. 项目初始化与环境搭建

• 创建项目目录
• 初始化pnpm项目
• 安装必要依赖(fastmcp, typescript等)
• 配置TypeScript

2. 服务器基础架构设计

• 创建主服务器文件
• 配置服务器基本参数
• 设置服务器启动配置

3. 压缩工具功能实现

• 设计压缩文件工具
• 实现单文件压缩功能
• 实现多文件/目录压缩功能
• 支持多种压缩格式(tar.gz, zip, 7z)

4. 解压工具功能实现

• 设计解压文件工具
• 实现解压缩功能
• 添加解压路径选择功能

5. 资源管理功能

• 实现压缩文件预览功能
• 实现压缩文件内容列表功能

6. 用户交互优化

• 添加进度报告功能
• 实现错误处理机制
• 添加安全机制（路径验证等）
• 实现标准化返回格式

7. MCP规范兼容性

• 更新工具输出格式以符合MCP规范
• 添加isError标识
• 标准化content字段
• 使用类型化的text返回

8. 工具架构优化

• 重构为模块化架构
• 实现格式处理器接口
• 创建格式注册表
• 统一工具接口设计

9. 测试与部署

• 基本功能测试
• 编写单元测试
• 进行集成测试
• 优化性能
• 准备部署文档

当前进度

目前已完成基本的服务器架构设计和主要功能实现，支持多种压缩格式。最新版本采用模块化、可扩展的架构，便于后续扩展和维护。

支持的压缩格式:

1. gzip格式：适用于单个文件压缩
2. tar.gz格式：适用于文件夹压缩
3. ZIP格式：通用的压缩格式，支持文件和文件夹
4. 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                # 主入口点

下一步计划

1. 完成其他格式处理器的实现
2. 优化压缩和解压性能
3. 添加更多格式支持（如rar等）
4. 实现流式处理以支持更大文件
5. 添加文件加密/解密功能
6. 编写测试用例
7. 发布至NPM

安装方法

Installing via Smithery

To install 压缩功能服务器 for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @tuskermanshu/compress-mcp-server --client claude

Manual Installation

1. 克隆本仓库

git clone <仓库地址>
cd zip-mcp-server

2. 安装依赖

pnpm install

3. 构建项目

pnpm build

4. 运行服务器

# 直接启动
pnpm start

# 开发模式
pnpm dev

# 使用MCP Inspector测试
pnpm inspect

可用工具

统一压缩工具（推荐使用）

原版独立工具（已弃用）

支持的压缩格式

统一压缩工具详细说明

新版本采用统一的压缩工具接口，提供一致的用户体验和更简单的接口。

compression (统一压缩工具)

一站式工具，支持多种压缩格式和操作，包括压缩、解压和查看文件内容。

参数：

• operation: 操作类型（必需）
  • compress: 压缩文件或文件夹
  • decompress: 解压文件
  • list: 列出压缩文件内容
• format: 压缩格式（必需）
  • gzip: 单文件压缩格式
  • tar.gz: 文件夹压缩格式
  • zip: 通用ZIP压缩格式
  • 7z: 高压缩比7z格式
• sourcePath: 源文件或文件夹路径（必需）
• outputDirectory: 输出目录，默认为源文件/文件夹所在目录
• outputFileName: 输出文件名，默认基于源名称和格式自动生成
• compressionLevel: 压缩级别(1-9)，默认为6
• stripComponents: 解压时忽略的目录层级数量（仅用于解压tar.gz）
• previewLength: 列出内容时的预览长度（字节数），默认为1000

扩展指南

添加新的压缩格式

1. 在src/handlers目录下创建新的处理器类文件，例如rar-handler.ts
2. 实现CompressionHandler接口的所有方法
3. 在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

• 初始版本
• 支持多种独立的压缩和解压工具

安全说明

本项目实现了多种安全机制：

1. 路径验证 - 防止路径遍历攻击，确保用户不能访问系统上的任意文件
2. 参数验证 - 使用zod库进行严格的输入验证
3. 错误处理 - 捕获所有可能的错误并提供友好的提示，不泄露系统信息
4. 文件名安全检查 - 确保文件名不包含路径分隔符

贡献指南

欢迎对本项目做出贡献！请fork项目，创建分支，提交变更后发起pull request。

许可证

MIT许可证