coolftp

coolFTP

**让 Claude 将你的网站部署到 SFTP 或 FTP 主机，并支持撤销，还会检查网站是否真的已上线。**在 Claude Code 中添加一行：

/plugin install coolftp --marketplace anivdel/coolFTP

然后说“为此项目设置 coolFTP”和“部署这个”。只有内容发生变化的文件才会上传，Git 提交会与部署记录在一起，部署后还会获取网站以确认其正常响应；说“撤销刚才的操作”即可恢复到上一个版本，无需 Git。适用于任何支持 SFTP 或 FTP 的主机：Hostinger、HostGator、Bluehost、GoDaddy、任何 cPanel 主机，以及你自己的 VPS。免费版支持 1 个站点，采用 MIT 许可证；Pro（一次性付费 $49）可解锁无限站点。网站：coolftp.com。

该插件、coolftp CLI 和 MCP 服务可在 macOS、Linux 和 Windows 上运行，要求 Node 18 或更高版本；Cursor、Codex 或任何可使用 shell 的 Agent 也能驱动它们。Windows 桌面应用是可选的配套应用：打开后，你可以实时查看 Agent 的每次调用，并点击批准删除、撤销和回滚操作。

打开桌面应用后，Agent 在删除任何内容前都会征求许可：

为什么选择 coolFTP

每个 FTP 客户端都默认由人来点击操作。coolFTP 则默认由人来监督，由 Agent 来执行。

• **基于哈希的部署。**服务器上的清单会记录每个已部署文件的 SHA-256 值。时间戳会骗人，哈希不会。
• **无需 Git 即可撤销。**每次部署都会先将要覆盖或删除的文件移至服务器上的备份文件夹。coolftp undo 会将它们恢复，即使工作树中有未提交的改动也一样。
• **结合 Git 的部署历史。**每次部署都会记录提交、分支、脏标记、消息、字节数、执行部署的 Agent，以及网站是否已验证上线。
• 一条命令回滚。coolftp rollback 会通过临时 Git 工作树恢复到上一个线上提交。
• **验证。**为站点提供公开 URL 后，每次部署都会获取变更过的页面，将静态文件与上传内容逐字节比较；如果网站没有响应，则以非零状态码退出。coolftp verify 可随时执行相同的检查。
• **桌面应用中的实时 Agent 动态和批准对话框。**打开应用时，删除操作、--delete 部署、回滚和撤销都必须等待你点击批准。部署会显示为进度卡片，Windows 通知会告知部署结果。
• **默认安全。**固定 SSH 主机密钥；使用 Windows 账户加密密码；首次部署保护机制会拒绝删除从未上传过的文件；变更文件会通过替换而非覆盖的方式更新；由服务器确认文件大小；支持断点续传。

packages/core   shared TypeScript library: transports, sites, hash manifest, sync, deploy
packages/cli    `coolftp` command line + `coolftp mcp` MCP server for agents
packages/app    Electron desktop app (two-pane browser, transfer queue, live agent feed)
site/           landing page for coolftp.com
scripts/        build + end-to-end test

安装

CLI 和 MCP 服务可在任何支持 Node 18 或更高版本的环境中运行：Windows、macOS、Linux、无头主机和 CI。

npm i -g coolftp
coolftp --version

也可以完全不安装：运行 npx coolftp ... 即可使用相同功能。

目前桌面应用仅支持 Windows：安装程序、便携版 .exe 和 Claude Desktop 扩展（.mcpb）及其 SHA-256 值均可在下载页面获取。

从源代码构建

npm install
npm run build
npm run app          # opens the desktop app
node packages/cli/dist/coolftp.js --help

若要从此检出版本获取全局 coolftp 命令，而不是通过 npm 安装，请运行：cd packages/cli && npm link。

添加服务器

# SFTP with your existing ~/.ssh key or the ssh-agent
coolftp site add coolftp.com --host coolftp.com --user deploy --root /var/www/html

# FTPS with a password (shared hosts)
coolftp site add oldhost --host ftp.oldhost.net --user me --protocol ftps --password '...' --root /public_html

coolftp site test coolftp.com

也可以使用应用中的 站点 按钮。Windows 上的站点配置位于 %USERPROFILE%\.coolftp\sites.json，其他系统上位于 ~/.config/coolftp/sites.json。（截至 0.1.4，Windows 文件夹为 %APPDATA%\coolftp；较新版本首次运行时会将其复制过来。COOLFTP_HOME 可用于覆盖文件夹。）在 Windows 上，该文件中的密码会通过 DPAPI 使用你的账户加密；在 macOS 和 Linux 上，在密钥链后端推出之前，密码会以明文形式存储，因此建议在这些系统上使用 SFTP 密钥。

链接项目并部署

cd my-site
coolftp init coolftp.com --local-dir dist --build "npm run build"
coolftp diff                       # preview
coolftp deploy -m "first deploy"
coolftp deploy --delete            # also remove remote files deleted locally
coolftp deploy --commit -m "msg"   # git add -A, git commit, then deploy
coolftp undo                       # put the previous versions back
coolftp verify                     # re-run the live checks
coolftp history

退出代码：0 表示已部署（如果网站有 URL，也已验证）；1 表示上传前或上传过程中发生故障；3 表示文件已上传，但在线检查未通过。-q 会隐藏进度和逐文件输出，但保留结果行、警告、错误和检查信息。部署超过 20 个文件时，每隔几秒打印一行进度，而不是每个文件打印一行；较长的计划会按文件夹汇总。

coolftp init 会写入 .coolftp.json：

{ "site": "coolftp.com", "localDir": "dist", "build": "npm run build", "ignore": ["*.map"] }

将其提交。添加 .coolftpignore（使用 gitignore 语法），列出任何绝不能上传的内容。.git、node_modules、.env*、*.log 和 coolFTP 文件始终会被排除。

如果网站的 FTP 根目录不是 Web 根目录（共享主机通常会让你登录到 public_html 上一级目录），请将项目指向正确的文件夹，并告知 coolFTP 网站的访问路径：

coolftp init myhost --remote-root /public_html --url https://example.com

此后每条命令都会以该文件夹为基准：coolftp push js/app.js js/app.js、coolftp ls、coolftp stat、coolftp cat、coolftp rm 都会解析到 /public_html，也就是 deploy 写入的位置。以 / 开头的路径仍是服务器上的绝对路径。url 会让已更改文件的 URL 和部署后的检查指向 https://example.com/js/app.js，而不是 FTP 路径。

push 会向服务器确认上传文件的大小，报告它创建的任何文件夹（如果单个文件触发了新的顶层文件夹，还会发出警告；这通常意味着 public_html/ 前缀已过时），并将推送到项目远程目录中的文件记录到部署清单中，以便下次部署时不再发送该文件。

Git Bash 会在程序收到参数之前，将以 / 开头的参数改写为 Windows 路径。coolFTP 在识别到 Git 安装路径前缀时会还原这些参数，并拒绝其他看起来像驱动器路径的参数，因此在 Git Bash 中也可以运行 coolftp ls /public_html。如果遇到拒绝提示，请使用相对路径或设置 MSYS_NO_PATHCONV=1。

让 Claude Code 来驱动

coolFTP 插件是一步完成的方式：它会启动 MCP 服务，教 Claude 安全地部署，添加 /coolftp:setup、/coolftp:deploy、/coolftp:undo 和 /coolftp:live，并在聊天旁边的实时面板中显示每次部署。在 Claude Code 中：

/plugin install coolftp --marketplace anivdel/coolFTP

输入 y 添加市场，然后选择作用范围。在 Claude 桌面应用中：点击提示词框旁边的 +，选择 Plugins，然后添加市场 anivdel/coolFTP，再添加 coolftp。它需要 Node 18 或更高版本，无需其他依赖；桌面应用为可选项。然后说“为此项目设置 coolFTP”。详见 plugins/coolftp。

手动配置 MCP 服务

适用于其他 MCP 客户端，或不使用插件、自己为 Claude Code 配置的情况。通过 npm 安装 CLI 后，在 macOS 和 Linux 上：

claude mcp add --scope user coolftp -- coolftp mcp

在 Windows 上，npm 会将 coolftp 安装为 .cmd shim，因此请通过 cmd 运行：

claude mcp add --scope user coolftp -- cmd /c coolftp mcp

如果没有全局安装：claude mcp add --scope user coolftp -- npx -y coolftp mcp（在 Windows 上同样需要通过 cmd /c 运行）。--scope user 会将其注册到此机器上的所有项目；去掉该参数则只会为当前项目注册。

Cursor、Windsurf 和其他 MCP 客户端在各自的 mcp.json 中使用相同的服务：

{ "mcpServers": { "coolftp": { "command": "coolftp", "args": ["mcp"] } } }

如果使用源代码检出版本而非 npm，请指向构建后的文件：

claude mcp add coolftp -- node "C:\path\to\cool FTP\packages\cli\dist\coolftp.js" mcp

提供的工具：coolftp_sites、coolftp_license、coolftp_status、coolftp_init、coolftp_diff、coolftp_deploy、coolftp_undo、coolftp_verify、coolftp_rollback、coolftp_history、coolftp_ls、coolftp_stat、coolftp_read、coolftp_write、coolftp_upload、coolftp_download、coolftp_mkdir、coolftp_delete、coolftp_rename。返回结果会为 Agent 汇总：提供计数和文件夹分类，而非数千条路径；每次部署都会提供 live 判定；超过 20 个文件后，传输日志会折叠。服务每次调用时都会检查桌面应用是否正在运行，因此可以在会话期间打开或关闭该应用。

在 Claude Desktop 应用中使用

同一个 MCP 服务也以 Claude Desktop 扩展的形式提供。npm run mcpb 会将其打包为 release/coolFTP-<version>.mcpb（下载页面提供已构建的文件）；在 Claude Desktop 中打开该文件并点击“安装”即可。Claude 会获得 coolftp_* 工具；只要桌面应用保持打开，每次调用仍会通过该应用路由，因此部署会显示在其中，而删除、撤销和回滚操作则会等你点击确认。聊天没有工作目录，因此请在扩展设置中设置 默认项目文件夹，或在聊天中指定文件夹；无论哪种方式，都会找到项目自己的 .coolftp.json。目前该软件包尚未签名，安装对话框会对此进行提示。

server.json 为 MCP Registry 描述了两种服务器形式：作为 coolftp npm 软件包（使用 npx coolftp mcp 运行），以及作为 .mcpb 软件包。npm run mcpb 会确保版本和软件包哈希保持最新。发布步骤（包括发布到 npm）见 docs/PUBLISHING.md。

Agent 驱动部署的安全保障

• 审批对话框。 桌面应用开启时，如果 Agent 调用要删除路径、使用 --delete 部署、回滚或撤销部署，应用会弹出对话框并等待你点击。两分钟内未响应则视为拒绝。你可以勾选复选框，在本次会话剩余时间内自动批准。
• 首次部署删除保护。 服务器上尚无清单时，如果目标文件夹包含 coolFTP 从未上传过的文件，则会拒绝执行 --delete。传入 --delete-untracked 可跳过此限制。
• 撤销。 部署覆盖或删除文件之前，线上副本会在服务器上重命名并移至 .coolftp/backup/<deployId>/，因此不会产生额外传输。coolftp undo 会恢复这些版本、删除本次部署新增的文件，而且撤销操作本身也可以撤销；--dry-run 会先显示操作内容，如果没有后续部署修改相关文件，则可使用 --to <deployId> 还原较早的部署。最近五次部署会保留备份（使用 coolftp init --keep-backups <n> 设置，设为 0 可关闭）。Deploys 选项卡中有“Undo”按钮。
• 回滚。 coolftp rollback 使用临时 Git 工作树恢复该项目上一次上线的提交，不会改动你的工作树。--to <commit|deployId> 可指定历史中的任意节点。应用的 Deploys 选项卡中也有相同的按钮。
• 验证。 为站点指定公开的 --url（或使用 coolftp init --url 为项目指定 URL），每次部署都会打印变更文件的 URL，抓取首页和最多四个页面并报告状态码，还会将最多四个静态文件与本地副本逐字节比较。状态检查失败时会以代码 3 退出；字节不匹配会报告为过期（服务器与外界之间仍有缓存或 CDN 在提供旧版本），但不会导致失败。coolftp verify 可随时重新运行检查；history 会显示每次部署的上线、失败或过期状态。MCP 结果会附带相同的判定，因此 Agent 不会把未经验证的部署报告为已上线。
• 上传确认。 对于最多包含 50 个文件的任务，每个上传文件都会从服务器读回大小，大小不匹配时会重试。变更文件会先上传到线上副本旁边，再通过重命名替换；清单也会以相同方式写入，因此连接中断不会留下写入不完整的文件或清单。
• 主机密钥固定。 首次使用时，SFTP 主机密钥会记录在 known_hosts.json 中；如果密钥发生变化，则会报出醒目的错误并拒绝连接。服务器合法重建后，可运行 coolftp site trust <name> 忘记已记录的密钥；运行 coolftp site keys 可列出这些密钥。
• 加密密码。 在 Windows 上，sites.json 中的密码和密钥口令会使用当前用户账户的 DPAPI 加密。命令行工具和应用共用此存储。
• 可恢复的部署。 传输最多重试三次。如果部署仍在中途失败，已传输到服务器的文件会写入清单，下次运行时不会重复传输。

任何可以使用 Shell 的 Agent 都能在已关联的项目中直接运行 coolftp deploy。CLI 会根据运行环境检测 Claude Code、Cursor、Codex、Gemini CLI 和 Aider，并据此标记调用；传入 --agent <name> 可覆盖此设置。

Claude 遵循的部署技能随插件一同提供，位于 plugins/coolftp/skills/deploy。

Agent 调用如何传递到应用

桌面应用运行时，会监听一个随机的 127.0.0.1 端口，并在同一文件夹中写入 hub.json，其中包含端口和每个会话专用的令牌。CLI 和 MCP 服务会查找此文件；如果应用有响应，它们就会将命令发送给应用，而不是自行运行。事件会以 NDJSON 流式传回，因此终端仍会显示进度，应用也会在 Agents 面板、传输队列和部署历史中显示同一调用。如果应用已关闭，CLI 会在进程内运行所有操作。--direct 可强制使用此方式。

部署如何决定上传内容

1. 扫描本地文件夹，并为文件计算哈希（SHA-256，按大小和修改时间缓存）。
2. 从服务器读取 <remoteRoot>/.coolftp/manifest.json。该文件将每个已部署路径映射到其哈希。
3. 通过最多四个 FTP 连接上传哈希不同或清单中缺失的文件（对于包含 8 个或更多文件的任务；使用 coolftp site add --connections <n> 更改连接数；SFTP 使用一个多路复用连接）。更改的文件会先上传到与线上文件相邻的位置，然后将线上文件移入备份文件夹，再将新文件重命名到原位置。清单中有记录但本地不存在的文件会报告为过期文件，只有使用 --delete 才会删除；该操作也会将这些文件移入备份文件夹。
4. 写入新清单（先写入临时文件名，再替换），并写入部署记录（git 提交、分支、是否有未提交更改、消息、Agent、计数、耗时、备份、连接数），清理超出保留数量的备份，然后运行线上检查，并将检查结果与记录一同保存。

如果服务器上还没有清单，系统会遍历远程目录并按大小进行比较；首次部署会创建清单。--force 会重新上传所有内容。

清单目录中会生成一个包含 Require all denied 的 .htaccess 文件。对于 nginx，请自行禁止访问 /.coolftp，或将 remoteRoot 指向网站根目录之外。

测试

npm run e2e

在临时目录中启动本地 FTP 服务器（ftp-srv）和本地 SFTP 服务器（ssh2，位于 scripts/lib/sftp-server.cjs），并通过 CLI 完成站点设置、初始化、首次部署删除保护、部署、清单差异检查、删除同步、--commit、从服务器端备份撤销和重做、备份清理、按上一次提交和部署 ID 回滚、推送（大小确认、新建文件夹警告、清单记录）、拉取、stat、重命名、mkdir、删除、通过四个 FTP 连接部署 30 个文件、通过本地 Web 服务器进行验证（部署通过、存在过期副本、站点无法访问且退出代码为 3、静默模式）、历史记录、加密密码、SSH 主机密钥固定（拒绝已替换的服务器密钥，随后信任新密钥），以及通过标准输入输出驱动 MCP 服务。总计 190 项检查。

无需真实主机即可试用

npm run dev:ftp     # ftp://demo:[email protected]:2121, remote root /public_html
npm run dev:sftp    # sftp://demo:[email protected]:2222, remote root /public_html

两种方式都会在临时文件夹中放入几个文件。添加一个指向其中一个文件夹的站点，在应用中连接，然后将任意文件夹部署到该站点。

Free 和 Pro

所有代码均采用 MIT 许可证。coolFTP Free 包含一个站点所需的全部功能。coolFTP Pro 一次性支付 49 美元即可使用无限数量的站点，并终身获得更新和优先支持，可在 coolftp.com 购买。

密钥格式为 CFP1.<payload>.<signature>，使用 Ed25519 签名，并通过 packages/core/src/license-pubkey.ts 中的公钥离线验证。有效密钥可在所有构建版本中解锁 Pro。密钥的 updatesUntil 会设置为 9999-12-31，因此也适用于较旧的构建版本；这些版本仍会检查该日期。

• node scripts/license/keygen.cjs 用于创建一次签名密钥对。私钥存放在 scripts/license/private/ 中（已加入 git 忽略）。请做好备份；丢失私钥会导致所有已签发的密钥失效。
• node scripts/license/issue.cjs --email [email protected] 用于手动签发密钥。
• npm run test:license 通过 CLI 测试激活、篡改、过期和移除。
• 使用 coolftp license、coolftp license activate <key>、coolftp license remove，或应用中的 Pro 按钮。

购买通过 Stripe Checkout 处理。site/api/stripe-webhook.php 接收 checkout.session.completed，使用私钥的 libsodium 副本签署密钥，将记录存储在网站根目录之外，并从 [email protected] 发送密钥邮件。site/api/resend.php 可根据电子邮件地址重新发送密钥，并设有速率限制。实际配置值填写在 site/api/config.php 中，该文件已加入 git 忽略；config.example.php 展示了配置结构。

打包应用

npm run dist

使用 electron-builder 和 packages/app/electron-builder.yml。输出文件位于 release/。构建产物未签名。