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

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 工具，则配置成功

使用方法

命令行模式

适合直接在终端中使用：

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
}

示例工作流

命令行工作流

1. 创建包含目录内容的ZIP文件：

   node index.js create -r project.zip src docs package.json
   

2. 查看ZIP文件内容：

   node index.js list -v project.zip
   

3. 向ZIP文件添加新文件：

   node index.js add project.zip README.md
   

4. 从ZIP文件中删除不需要的文件：

   node index.js delete project.zip docs/temp.txt
   

5. 提取ZIP文件到指定目录：

   node index.js extract project.zip extracted_project
   

6. 验证ZIP文件完整性：

   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：用于 ZIP 文件的创建和处理

许可证

MIT License

更新日志

v1.0.0 (2026-01-09)

• 初始版本发布
• 支持创建、提取、列出、添加、删除、查看和验证 ZIP 文件
• 支持递归操作
• 支持详细信息显示
• 提供 MCP 配置示例
• 支持持续运行的服务模式
• 修复了 "客户端已关闭" 问题
• 实现了严格的 JSON-RPC 2.0 规范
• 支持 MCP 协议的 tools/list 和 tools/call 方法
• 完整的工具元数据和 JSON Schema 支持