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. 克隆或下载项目
将项目克隆或下载到本地目录：
git clone https://github.com/gniquil123/ZipMCP.git
cd ZipMCP
3. 安装依赖
在项目目录中运行以下命令安装依赖：
npm install
MCP 安装和配置
1. MCP 简介
MCP（Model Context Protocol）是一种协议，它允许大型语言模型（LLMs）访问自定义的工具和服务。TRAE 中的智能体作为 MCP 客户端可以选择向 MCP Server 发起请求，以使用它们提供的工具。
2. ZIP MCP 配置文件
ZIP MCP 提供了示例配置文件 mcp-config-example.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
- 打开 TRAE IDE
- 进入设置页面
- 找到 MCP 配置选项
- 点击 "添加 MCP Server"
- 填写配置信息，或导入
mcp-config-example.json文件 - 保存配置
- 重启 TRAE IDE（如有必要）
5. 验证 MCP 配置
配置完成后，您可以通过以下方式验证：
- 在 TRAE IDE 中打开一个 AI 对话
- 尝试使用 ZIP MCP 工具，例如：
请使用 MCP 工具里的 Zip 来创建一个压缩包，包含 README.md 文件 - 如果 AI 能够正确调用 ZIP MCP 工具，则配置成功
使用方法
命令行模式
适合直接在终端中使用：
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文件
命令行语法：
node index.js create <zipPath> <files...> [选项]
选项：
-r, --recursive：递归添加目录内容
示例：
# 创建包含单个文件的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 调用示例：
{
"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文件
命令行语法：
node index.js extract <zipPath> [destDir]
参数：
destDir：目标目录，默认为当前目录
示例：
# 提取到当前目录
node index.js extract archive.zip
# 提取到指定目录
node index.js extract archive.zip output_dir
MCP 调用示例：
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.extract",
"params": {
"zipPath": "archive.zip",
"destDir": "output_dir"
}
},
"id": 1
}
3. 列出ZIP文件内容
命令行语法：
node index.js list <zipPath> [选项]
选项：
-v, --verbose：显示详细信息
示例：
# 简洁列出ZIP内容
node index.js list archive.zip
# 详细列出ZIP内容（包含大小、压缩大小和修改时间）
node index.js list -v archive.zip
MCP 调用示例：
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.list",
"params": {
"zipPath": "archive.zip",
"verbose": true
}
},
"id": 1
}
4. 向ZIP文件添加文件
命令行语法：
node index.js add <zipPath> <files...> [选项]
选项：
-r, --recursive：递归添加目录内容
示例：
# 向ZIP添加单个文件
node index.js add archive.zip newfile.txt
# 向ZIP添加目录及其内容（递归）
node index.js add -r archive.zip newdir
MCP 调用示例：
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.add",
"params": {
"zipPath": "archive.zip",
"files": ["newfile.txt"],
"recursive": false
}
},
"id": 1
}
5. 从ZIP文件中删除文件
命令行语法：
node index.js delete <zipPath> <entries...>
示例：
# 从ZIP中删除单个文件
node index.js delete archive.zip file.txt
# 从ZIP中删除多个文件
node index.js delete archive.zip file1.txt file2.txt
MCP 调用示例：
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.delete",
"params": {
"zipPath": "archive.zip",
"entries": ["file.txt"]
}
},
"id": 1
}
6. 查看ZIP文件中的单个文件内容
命令行语法：
node index.js view <zipPath> <entryName>
示例：
# 查看ZIP中的文本文件内容
node index.js view archive.zip file.txt
MCP 调用示例：
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.view",
"params": {
"zipPath": "archive.zip",
"entryName": "file.txt"
}
},
"id": 1
}
7. 验证ZIP文件
命令行语法：
node index.js verify <zipPath>
示例：
# 验证ZIP文件的完整性
node index.js verify archive.zip
MCP 调用示例：
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"tool": "zip.verify",
"params": {
"zipPath": "archive.zip"
}
},
"id": 1
}
示例工作流
命令行工作流
-
创建包含目录内容的ZIP文件：
node index.js create -r project.zip src docs package.json -
查看ZIP文件内容：
node index.js list -v project.zip -
向ZIP文件添加新文件：
node index.js add project.zip README.md -
从ZIP文件中删除不需要的文件：
node index.js delete project.zip docs/temp.txt -
提取ZIP文件到指定目录：
node index.js extract project.zip extracted_project -
验证ZIP文件完整性：
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 服务未正确启动
- 依赖未安装
- 配置文件格式错误
解决方案：
- 确保已安装所有依赖：
npm install - 检查配置文件格式是否正确
- 确保 Node.js 版本符合要求
- 查看 MCP 服务日志，了解具体错误信息
2. 工具调用失败
原因：
- 参数格式错误
- 文件路径不存在
- 权限不足
解决方案：
- 检查参数是否符合工具的
inputSchema要求 - 确保文件路径正确，且服务有访问权限
- 检查目标目录是否可写
依赖库
- adm-zip：用于 ZIP 文件的创建和处理
许可证
MIT License
更新日志
v1.0.0 (2026-01-09)
- 初始版本发布
- 支持创建、提取、列出、添加、删除、查看和验证 ZIP 文件
- 支持递归操作
- 支持详细信息显示
- 提供 MCP 配置示例
- 支持持续运行的服务模式
- 修复了 "客户端已关闭" 问题
- 实现了严格的 JSON-RPC 2.0 规范
- 支持 MCP 协议的
tools/list和tools/call方法 - 完整的工具元数据和 JSON Schema 支持