# ZIP MCP
ZIP MCP 是一个功能强大的 ZIP 文件处理工具，支持常用的 ZIP 命令功能，包括创建、提取、列出、添加、删除、查看和验证 ZIP 文件。它严格遵循 MCP（Model Context Protocol）规范，可以无缝集成到支持 MCP 的 AI 开发环境中。
## 功能特性
- ✅ **创建 ZIP 文件**：支持单个文件、多个文件和目录的压缩
- ✅ **提取 ZIP 文件**：将 ZIP 文件内容提取到指定目录
- ✅ **列出 ZIP 内容**：查看 ZIP 文件中的条目列表
- ✅ **添加文件到 ZIP**：向现有 ZIP 文件添加新文件或目录
- ✅ **删除 ZIP 中的文件**：从 ZIP 文件中删除指定条目
- ✅ **查看 ZIP 中的文件内容**：直接查看 ZIP 中单个文件的内容
- ✅ **验证 ZIP 文件**：检查 ZIP 文件的完整性
- ✅ **递归操作**：支持递归处理目录
- ✅ **详细信息显示**：可查看文件大小、压缩大小和修改时间
- ✅ **MCP 协议支持**：严格遵循 Model Context Protocol 规范
- ✅ **JSON-RPC 2.0 规范**：使用标准的 JSON-RPC 2.0 格式
## 安装方法
### 1. 安装 Node.js
确保已安装 Node.js（建议版本 14+）。可以从 [Node.js 官网](https://nodejs.org/) 下载并安装。
### 2. 克隆或下载项目
将项目克隆或下载到本地目录：
```bash
git clone https://github.com/gniquil123/ZipMCP.git
cd ZipMCP
```
### 3. 安装依赖
在项目目录中运行以下命令安装依赖：
```bash
npm install
```
## MCP 安装和配置
### 1. MCP 简介
MCP（Model Context Protocol）是一种协议，它允许大型语言模型（LLMs）访问自定义的工具和服务。TRAE 中的智能体作为 MCP 客户端可以选择向 MCP Server 发起请求，以使用它们提供的工具。
### 2. ZIP MCP 配置文件
ZIP MCP 提供了示例配置文件 `mcp-config-example.json`，您可以根据需要修改：
```json
{
"mcpServers": {
"Zip": {
"command": "node",
"args": [
"这里配置为 index.js文件 的完整路径，注意路径分隔符要使用\\做转义"
],
"env": {
"ZIP_MCP_LOG_LEVEL": "info",
"ZIP_MCP_MAX_FILE_SIZE": "104857600",
"ZIP_MCP_TEMP_DIR": "./temp"
}
}
}
}
```
### 3. 配置参数说明
| 参数 | 描述 | 示例值 |
|------|------|--------|
| `command` | 运行 MCP 服务的命令 | `node` |
| `args` | 命令参数 | `["index.js"]` |
| `env` | 环境变量 | `{"ZIP_MCP_LOG_LEVEL": "info"}` |
### 4. 集成到 TRAE IDE
1. 打开 TRAE IDE
2. 进入设置页面
3. 找到 MCP 配置选项
4. 点击 "添加 MCP Server"
5. 填写配置信息，或导入 `mcp-config-example.json` 文件
6. 保存配置
7. 重启 TRAE IDE（如有必要）
### 5. 验证 MCP 配置
配置完成后，您可以通过以下方式验证：
1. 在 TRAE IDE 中打开一个 AI 对话
2. 尝试使用 ZIP MCP 工具，例如：
```
请使用 MCP 工具里的 Zip 来创建一个压缩包，包含 README.md 文件
```
3. 如果 AI 能够正确调用 ZIP MCP 工具，则配置成功
## 使用方法
### 命令行模式
适合直接在终端中使用：
```bash
node index.js <命令> [参数] [选项]
```
### MCP 模式
适合在支持 MCP 的 AI 开发环境中使用，AI 会自动生成正确的工具调用请求。
## 命令列表
### 命令行命令
| 命令 | 别名 | 描述 |
|------|------|------|
| create | c | 创建ZIP文件 |
| extract | e | 提取ZIP文件内容 |
| list | l | 列出ZIP文件内容 |
| add | a | 向现有ZIP文件添加文件 |
| delete | d | 从ZIP文件中删除文件 |
| view | v | 查看ZIP文件中的单个文件内容 |
| verify | V | 验证ZIP文件的完整性 |
### MCP 工具
| 工具名称 | 描述 |
|----------|------|
| zip.create | 创建ZIP文件 |
| zip.extract | 提取ZIP文件内容 |
| zip.list | 列出ZIP文件内容 |
| zip.add | 向现有ZIP文件添加文件 |
| zip.delete | 从ZIP文件中删除文件 |
| zip.view | 查看ZIP文件中的单个文件内容 |
| zip.verify | 验证ZIP文件的完整性 |
## 详细命令说明
### 1. 创建ZIP文件
**命令行语法**：
```bash
node index.js create <zipPath> <files...> [选项]
```
**选项**：
- `-r, --recursive`：递归添加目录内容
**示例**：
```bash
# 创建包含单个文件的ZIP
node index.js create archive.zip file.txt
# 创建包含多个文件的ZIP
node index.js create archive.zip file1.txt file2.txt
# 创建包含目录的ZIP（仅目录本身）
node index.js create archive.zip mydir
# 创建包含目录及其内容的ZIP（递归）
node index.js create -r archive.zip mydir
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.create",
"params": {
"zipPath": "archive.zip",
"files": ["file.txt", "file2.txt"],
"recursive": false
}
},
"id": 1
}
```
### 2. 提取ZIP文件
**命令行语法**：
```bash
node index.js extract <zipPath> [destDir]
```
**参数**：
- `destDir`：目标目录，默认为当前目录
**示例**：
```bash
# 提取到当前目录
node index.js extract archive.zip
# 提取到指定目录
node index.js extract archive.zip output_dir
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.extract",
"params": {
"zipPath": "archive.zip",
"destDir": "output_dir"
}
},
"id": 1
}
```
### 3. 列出ZIP文件内容
**命令行语法**：
```bash
node index.js list <zipPath> [选项]
```
**选项**：
- `-v, --verbose`：显示详细信息
**示例**：
```bash
# 简洁列出ZIP内容
node index.js list archive.zip
# 详细列出ZIP内容（包含大小、压缩大小和修改时间）
node index.js list -v archive.zip
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.list",
"params": {
"zipPath": "archive.zip",
"verbose": true
}
},
"id": 1
}
```
### 4. 向ZIP文件添加文件
**命令行语法**：
```bash
node index.js add <zipPath> <files...> [选项]
```
**选项**：
- `-r, --recursive`：递归添加目录内容
**示例**：
```bash
# 向ZIP添加单个文件
node index.js add archive.zip newfile.txt
# 向ZIP添加目录及其内容（递归）
node index.js add -r archive.zip newdir
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.add",
"params": {
"zipPath": "archive.zip",
"files": ["newfile.txt"],
"recursive": false
}
},
"id": 1
}
```
### 5. 从ZIP文件中删除文件
**命令行语法**：
```bash
node index.js delete <zipPath> <entries...>
```
**示例**：
```bash
# 从ZIP中删除单个文件
node index.js delete archive.zip file.txt
# 从ZIP中删除多个文件
node index.js delete archive.zip file1.txt file2.txt
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.delete",
"params": {
"zipPath": "archive.zip",
"entries": ["file.txt"]
}
},
"id": 1
}
```
### 6. 查看ZIP文件中的单个文件内容
**命令行语法**：
```bash
node index.js view <zipPath> <entryName>
```
**示例**：
```bash
# 查看ZIP中的文本文件内容
node index.js view archive.zip file.txt
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.view",
"params": {
"zipPath": "archive.zip",
"entryName": "file.txt"
}
},
"id": 1
}
```
### 7. 验证ZIP文件
**命令行语法**：
```bash
node index.js verify <zipPath>
```
**示例**：
```bash
# 验证ZIP文件的完整性
node index.js verify archive.zip
```
**MCP 调用示例**：
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.verify",
"params": {
"zipPath": "archive.zip"
}
},
"id": 1
}
```
## 示例工作流
### 命令行工作流
1. 创建包含目录内容的ZIP文件：
```bash
node index.js create -r project.zip src docs package.json
```
2. 查看ZIP文件内容：
```bash
node index.js list -v project.zip
```
3. 向ZIP文件添加新文件：
```bash
node index.js add project.zip README.md
```
4. 从ZIP文件中删除不需要的文件：
```bash
node index.js delete project.zip docs/temp.txt
```
5. 提取ZIP文件到指定目录：
```bash
node index.js extract project.zip extracted_project
```
6. 验证ZIP文件完整性：
```bash
node index.js verify project.zip
```
### AI 工作流
在支持 MCP 的 AI 开发环境中，您可以直接通过自然语言使用 ZIP MCP 工具：
```
请使用 MCP 工具里的 Zip 来创建一个包含 README.md 和 package.json 文件的压缩包，命名为 archive.zip
```
AI 会自动生成并发送 MCP 请求，调用 `zip.create` 工具完成操作。
## 注意事项
1. 本工具基于 Node.js 开发，需要 Node.js 环境支持
2. 支持 Windows、macOS 和 Linux 系统
3. 处理大文件时可能需要较长时间，请耐心等待
4. 请确保有足够的磁盘空间用于创建和提取 ZIP 文件
5. 递归操作时请谨慎，避免意外压缩过多文件
6. MCP 模式下，确保 MCP 配置正确，且服务能够正常启动
7. 如遇到 "客户端已关闭" 错误，请检查 MCP 配置和依赖安装
## 解决常见问题
### 1. "客户端已关闭" 错误
**原因**：
- MCP 服务未正确启动
- 依赖未安装
- 配置文件格式错误
**解决方案**：
1. 确保已安装所有依赖：`npm install`
2. 检查配置文件格式是否正确
3. 确保 Node.js 版本符合要求
4. 查看 MCP 服务日志，了解具体错误信息
### 2. 工具调用失败
**原因**：
- 参数格式错误
- 文件路径不存在
- 权限不足
**解决方案**：
1. 检查参数是否符合工具的 `inputSchema` 要求
2. 确保文件路径正确，且服务有访问权限
3. 检查目标目录是否可写
## 依赖库
- [adm-zip](https://www.npmjs.com/package/adm-zip)：用于 ZIP 文件的创建和处理
## 许可证
MIT License
## 更新日志
### v1.0.0 (2026-01-09)
- 初始版本发布
- 支持创建、提取、列出、添加、删除、查看和验证 ZIP 文件
- 支持递归操作
- 支持详细信息显示
- 提供 MCP 配置示例
- 支持持续运行的服务模式
- 修复了 "客户端已关闭" 问题
- 实现了严格的 JSON-RPC 2.0 规范
- 支持 MCP 协议的 `tools/list` 和 `tools/call` 方法
- 完整的工具元数据和 JSON Schema 支持
