ftp-deploy-mcp 是一个 MCP（Model Context Protocol）服务器，为 AI 编程代理提供针对 FTP、FTPS 和 SFTP 服务器的文件部署、检查和传输能力。它被定位为“AI 编程代理的部署按钮”，使 Claude Code、Claude Desktop、Cursor、Windsurf、Trae、Antigravity 或任何 MCP 客户端能够列出、读取、上传、下载和部署文件到用户自有的服务器上。
用途方面，它面向需要从 AI 编码代理中安全地操作远程文件的场景，提供一组聚焦的 MCP 工具用于服务器发现、测试、列目录、读文件、上传、递归部署、下载、创建目录、重命名和删除。所有远程路径参数都相对于配置的远程根目录，当设置了 defaultServer 或仅有一个服务器时，server 参数可选。
主要能力包括：
- 多服务器配置：在一个本地配置文件中定义多个命名服务器。
- 递归部署：支持类似 gitignore 的部署排除规则、dry-run 预演以及每服务器的 readOnly 只读模式。
- 本地限制：通过 localRoot 限制 MCP 服务器可访问的本地文件范围，对 ftp_upload、ftp_deploy 和 ftp_download 均生效。
- 验证式暂存提升：上传和部署先写入不可预测的同级临时文件，校验实际字节数与 SHA256 后再通过一次重命名提升；验证或重命名失败不会触发删除最终目标或直接覆盖回退。下载则先验证独占的本地临时文件，同步并关闭后再提升。默认 overwrite:false 使用硬链接避免覆盖中途出现的文件，不支持硬链接的文件系统会失败关闭。
- SFTP 主机密钥固定：通过 hostKeySha256 固定主机密钥，并在受控轮换时支持数组形式；拒绝符号链接组件。
- 凭据保护：凭据在本地从配置、环境变量或 SSH 密钥加载，不会主动返回给模型；工具响应中不包含凭据文本。
- FileZilla 导入、交互式设置向导和只读 doctor 命令。
- 进度通知：仅当调用方提供进度令牌时发送递增计数，不包含路径或凭据文本。
- 响应兼容与分页：ftp_list 返回单页结果，包含 total、count、offset、limit、has_more、next_offset 等分页字段；除 ftp_read 外，成功时提供 MCP outputSchema 与匹配的 structuredContent。
- 注解：所有工具发布 MCP 注解说明只读、破坏性、幂等和开放世界行为，但注解只是客户端提示，不是安全边界。
使用方式： 目前需从源码安装。步骤为：安装 Node.js 22 或 24（最低 22）；执行 git clone https://github.com/alebgl77/ftp-deploy-mcp.git 并 cd ftp-deploy-mcp；执行 npm ci --omit=dev --ignore-scripts；执行 npm run setup，然后编辑生成的服务器配置，设置绝对 localRoot、替换凭据、配置 SFTP 主机密钥固定或 FTP/FTPS 安全确认；重启 MCP 客户端并尝试 dry run。Windows 可运行 install.cmd，macOS/Linux 可运行 ./install.sh 替代步骤 3–4。连接前应检查每个生成的服务器条目。 配置方面，显式配置路径优先级为：--config <path> 优先，其次是 FTP_MCP_CONFIG；显式配置为空、缺失、不可读或无效时会报错且不回退到其他文件。没有选择器时，按顺序取第一个找到的配置：./ftp-servers.json、~/.ftp-mcp/servers.json。教学示例中包含注释，但真实配置文件必须是严格 JSON，可从 ftp-servers.example.json 开始。任何字符串可包含 ${ENV:VARIABLE_NAME}，缺失变量会产生具名配置错误。 客户端接入方面，npm run setup 会检测支持的客户端，修改现有客户端配置前创建带时间戳的备份，并为仅 UI 客户端打印配置块。手动接入时需将命令中的路径替换为本检出的绝对路径。常见位置包括 Claude Code 的 .mcp.json、Cursor 的 ~/.cursor/mcp.json、Windsurf 的 ~/.codeium/windsurf/mcp_config.json。 注意：npm 包尚未发布，npx -y ftp-deploy-mcp 目前不可用；官方 MCP Registry 发布状态为待定，基于注册表的安装方式暂未提供。GitHub 源码发布与 npm、官方 MCP Registry 发布是分开的。
适用场景： 适合 AI 编码代理在开发或运维中需要将构建产物、静态资源或配置文件部署到自有的 FTP、FTPS 或 SFTP 服务器；需要受控的递归部署与排除规则；需要只读检查远程服务器内容；需要在本地限制可访问文件范围；以及需要 SFTP 主机密钥验证和多服务器管理的场合。
限制与安全：
- FTP/FTPS 最强的边界是服务器自身的账户隔离或 chroot；客户端规范化能拒绝明显穿越，但 FTP 缺乏可移植的 REALPATH/LSTAT 原语，无法证明服务器端符号链接停留在配置的子根内。
- SFTP 会验证主机固定并拒绝符号链接组件，但受攻击者控制的服务器仍可能在检查与操作之间改变文件系统状态。
- readOnly 减少通过该 MCP 服务器的意外写入，但不能替代远程服务器强制执行的只读凭据。
- FTP、insecureTLS、allowUnknownHostKey 和 allowUnsafeRemoteRoot 是明确的风险接受，不是安全功能。
- 默认部署排除包含 node_modules、.git、环境文件、日志、操作系统元数据、ftp-servers.json 以及任意深度的 .ftp-mcp 内容；保留的 .ftp-mcp-*.tmp 基名始终被排除。
- 同一 Node 进程内，同一规范化协议、主机名、端口和用户名的上传、部署、mkdir、重命名和删除按 FIFO 顺序执行；锁不协调其他 Node 进程、DNS 别名、其他账户或同一主机上的外部客户端。
- ftp_deploy 不是事务：若一个或多个传输失败，工具返回带部分部署摘要的 MCP 错误，已提升的文件不会回滚。
- 进程最多接纳 64 个工具调用，超出返回 CAPACITY_LIMIT。
- 内部准备为单次使用且限制在 10 秒内，不延长整体操作截止时间。
- 无遥测。
- 仓库测试套件使用本地 FTP 和 SFTP 服务器，不需要外部网络。
迁移说明（v0.1 到 v0.2）：为 upload、deploy、download 使用的每个服务器添加绝对 localRoot；为每个 SFTP 服务器添加经带外验证的 hostKeySha256，allowUnknownHostKey:true 仅作为临时明确风险接受，不要同时配置两者；FTP/FTPS 优先使用专用服务器端 chroot，可见根为 / 并将 root 设为 /，非根客户端路径现在需要 allowUnsafeRemoteRoot:true 且对服务器端符号链接仍不安全；将失败的 ftp_deploy 视为部分部署，重试前应检查摘要并协调远程树；重新运行 npm run setup 或更新 MCP 客户端命令，然后运行 npm run doctor 和 dry run。
