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 官网 下载并安装。
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 工具完成操作。
注意事项
- 本工具基于 Node.js 开发,需要 Node.js 环境支持
- 支持 Windows、macOS 和 Linux 系统
- 处理大文件时可能需要较长时间,请耐心等待
- 请确保有足够的磁盘空间用于创建和提取 ZIP 文件
- 递归操作时请谨慎,避免意外压缩过多文件
- MCP 模式下,确保 MCP 配置正确,且服务能够正常启动
- 如遇到 "客户端已关闭" 错误,请检查 MCP 配置和依赖安装
解决常见问题
1. "客户端已关闭" 错误
原因:
- MCP 服务未正确启动
- 依赖未安装
- 配置文件格式错误
解决方案:
1. 确保已安装所有依赖:npm install
2. 检查配置文件格式是否正确
3. 确保 Node.js 版本符合要求
4. 查看 MCP 服务日志,了解具体错误信息
2. 工具调用失败
原因:
- 参数格式错误
- 文件路径不存在
- 权限不足
解决方案:
1. 检查参数是否符合工具的 inputSchema 要求
2. 确保文件路径正确,且服务有访问权限
3. 检查目标目录是否可写
依赖库
- adm-zip:用于 ZIP 文件的创建和处理
许可证
MIT License
更新日志
v1.0.0 (2026-01-09)
- 初始版本发布
- 支持创建、提取、列出、添加、删除、查看和验证 ZIP 文件
- 支持递归操作
- 支持详细信息显示
- 提供 MCP 配置示例
- 支持持续运行的服务模式
- 修复了 "客户端已关闭" 问题
- 实现了严格的 JSON-RPC 2.0 规范
- 支持 MCP 协议的
tools/list和tools/call方法 - 完整的工具元数据和 JSON Schema 支持