ftp-deploy-mcp

专门设计的部署控制可确保凭据不会出现在工具响应中，支持只读服务和试运行，并通过 localRoot 限制本地文件访问。此代码库配有全面的端到端测试套件，可在本地 FTP 和 SFTP 服务上运行。不会收集遥测数据。

**可用性：**版本 0.3.2 已发布至 npm 和 Official MCP Registry。 使用 npx -y [email protected] 可运行该版本。 GitHub 发布版本 是单独的源代码发行版；main 可能包含后续更改。 在注册表中可见表示该版本可用，但不代表依赖项已锁定解析，也不代表其他提交已通过资格认证。请参阅发布指南。

**部署模式：**十个基础工具提供可控传输和试运行。 启用 stateDir 后，会添加四个持久化工具，支持 MCP 确认、明确恢复，以及对已确认更改进行保守回滚。这些保证仅适用于可选的持久化工作流；旧版 ftp_deploy 不提供事务或回滚功能。

文档

文档	英文	法语
概览和安装	README	README
变更	更新日志	修改记录
贡献	指南	指南
安全策略	策略	策略
安全模型	模型	模型
发布流程	指南	指南
Agent 评估	说明	说明
Agent 性能和客户端集成	指南	指南
脚本化 MCP 一致性测试	指南	指南
CLI 和 MCP 语言	指南	指南
MCP 错误约定	约定	约定
已验证的分阶段传输	指南	指南
扫描和准入限制	限制	限制
持久化状态存储	库	库
持久化工作流模型	模型	模型
MIT 许可证	规范文本	参考译文

架构和场景

在双语交互式 HTML 指南中查看当前和目标架构图以及示例场景。 该指南及其英文 / 法文构建说明位于仓库中，不包含在 npm 包内。克隆仓库后，在本地打开 site/index.html，并使用其中的语言选择器。

已验证部署流程动画

如需减少动态效果，请查看静态完成状态图像。 请参阅视觉系统来源和生成说明。

视觉方向的探索借助了 ChatGPT Image；最终 README 资源以确定性方式渲染。其来源和准确提示词说明了这些资源仅用于示例，不构成认证。

首次从源码安装

1. 安装受支持的 Node.js 版本：22、24 或 26（最低要求：22）。
2. 运行 git clone https://github.com/alebgl77/ftp-deploy-mcp.git，然后 运行 cd ftp-deploy-mcp。
3. 运行 npm ci --omit=dev --ignore-scripts。
4. 运行 npm run setup，然后编辑生成的服务配置：设置绝对路径 localRoot，替换凭据，并配置 SFTP 主机密钥固定值，或配置下文所述的 FTP/FTPS 安全确认。
5. 重启 MCP 客户端并尝试一次试运行：

Call ftp_deploy with:
{"server":"prod","local_dir":"dist","remote_dir":"/","dry_run":true}

Windows 用户可以运行 install.cmd，macOS/Linux 用户可以运行 ./install.sh，以替代第 3–4 步。首次连接前请检查生成的每个服务条目。

安装指定标签版本时，请在安装前检出该确切标签。npm ci 使用唯一权威的 package-lock.json，其中包含六个精确的直接依赖版本固定项和经过审核的依赖 关系图。请将其与源码一同保留。--ignore-scripts 会禁用自动依赖生命周期 脚本；设置操作是独立且明确的步骤。

发布后，v0.3.2 源码安装包名为 ftp-deploy-mcp-0.3.2-source.tar.gz：共 90 个文件，包含该锁文件。请先 确认其已发布并核对校验和，再将其解压到一个新目录：

tar --ignore-zeros -xzf ftp-deploy-mcp-0.3.2-source.tar.gz
cd package
npm ci --omit=dev --ignore-scripts
node src/index.js setup

此安装包不包含仓库测试和维护脚本；GitHub 自动生成的源码 ZIP/tar 则包含完整 仓库。单独的 npm .tgz 包含 89 个文件，不含锁文件，并遵循 npm 依赖解析 规则。它不保证安装锁定的依赖版本。验证方法和限制请参阅 发布指南。

协议与安全矩阵

协议	传输身份验证	远程根目录行为	推荐用途
SFTP	已加密。必须设置 hostKeySha256，除非显式设置 allowUnknownHostKey: true 并接受冒充风险。	realpath/lstat 检查会拒绝符号链接组件，并将操作限制在 root 之下。恶意或状态变化的服务端仍可能在验证和使用之间制造竞态。	首选。请固定通过带外方式核验的指纹。
FTPS	证书验证成功时已加密。设置 insecureTLS: true 还必须设置 allowInsecure: true，并会禁用中间人攻击防护。	客户端子根目录无法可靠地充当防符号链接隔离区。除非设置 allowUnsafeRemoteRoot: true，否则不允许将 root 设为 / 以外的值。	使用专用的服务端 chroot 账户，使其可见根目录为 /。
FTP	明文传输。除非设置 allowInsecure: true 并接受流量拦截和凭据泄露风险，否则会被拒绝。	与 FTPS 存在相同限制：真正的边界是服务端账户/chroot，而不是客户端按路径进行的词法检查。	仅用于遗留场景，在可信网络中搭配专用的 chroot 账户使用。

三种协议都会对 ftp_upload、ftp_deploy 和 ftp_download 强制执行 localRoot。这会限制 MCP 服务可以访问的本地文件。

你将获得

• 十个专用 MCP 工具，用于发现服务、测试、列出、读取、上传、递归部署、 下载、创建目录、重命名和删除。
• 配置 stateDir 后，可使用四个额外的持久化工作流工具；确认和回滚遵循 文档说明的限制。
• 在一个本地配置中配置多个命名服务。
• 类似 Gitignore 的部署排除规则、试运行和每个服务的 readOnly 模式。
• FileZilla 导入、交互式设置向导和只读 doctor 命令。
• 凭据从本地配置、环境变量或 SSH 密钥加载，且不会主动返回给模型。

服务配置

显式指定的配置路径具有最高优先级：

1. --config <path>
2. 未指定 --config 时，使用 FTP_MCP_CONFIG

显式指定的配置为空、缺失、不可读或无效时，会报告错误，不会回退到其他文件。MCP 工具仍可用于报告配置问题。--config 必须带路径参数。

如果未使用上述任一选择方式，则使用找到的第一个配置文件：

1. ./ftp-servers.json
2. ~/.ftp-mcp/servers.json

下面的教学示例是带注释的 JSON。实际配置文件必须是严格的 JSON；请从 ftp-servers.example.json 开始。

{
  "defaultServer": "prod",
  "stateDir": "/home/alice/.local/state/ftp-deploy-mcp",
  "requirePlan": true,
  "servers": {
    "prod": {
      "protocol": "sftp",
      "host": "ssh.example.com",
      "port": 22,
      "user": "deploy",
      "password": "${ENV:PROD_PASSWORD}",
      "privateKeyPath": "~/.ssh/id_ed25519",
      "passphrase": "${ENV:PROD_KEY_PASSPHRASE}",
      "localRoot": "/home/alice/projects/site",
      "root": "/var/www/site",
      "hostKeySha256": "SHA256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "readOnly": false
    }
  }
}

请替换由全 A 组成的指纹；它对真实主机刻意设置为不可用。在受控的密钥轮换期间，将 hostKeySha256 用作数组：

"hostKeySha256": [
  "SHA256:old_verified_43_character_base64_value_here",
  "SHA256:new_verified_43_character_base64_value_here"
]

上面的示例标签展示了格式，但不是有效的固定值。每个实际条目都恰好由 SHA256: 加上 43 个未填充的 base64 字符组成。

字段参考

字段	适用于	含义
stateDir	顶层	可选的绝对路径、规范化的持久状态目录，与每个 localRoot 在规范化后均不重叠。启用后会公布四个持久工作流工具。
requirePlan	顶层	设置 stateDir 时，默认为 true。除 ftp_deploy 的试运行外，会阻止旧版远程变更工具；设为 false 时，这些工具仍可使用，但受同一持久别名锁保护。
stateLimits	顶层	可选的严格持久配额，适用于状态、备份、计划、操作、计划文件/字节数、日志字节数/事件数及备份文件数。
protocol	全部	必填：ftp、ftps 或 sftp。
host / port / user	全部	连接端点和账户。默认端口为 21、隐式 FTPS 的 990，以及 SFTP 的 22。
password	全部	密码或 ${ENV:NAME} 占位符。
privateKeyPath / passphrase	SFTP	SSH 私钥路径和可选的密码短语。支持展开前导 ~。这些用于验证用户身份，不用于验证服务端。
localRoot	全部	上传、部署和下载时必填。必须解析为已存在的绝对本地目录；支持前导 ~。拒绝相对路径及逃逸出目录的符号链接/联接。相对工具路径会在此目录内解析，绝对工具路径也必须保持在此目录内。
root	全部	远程根目录，默认为 /。工具路径会在此目录下解析。SFTP 会执行服务端 realpath/lstat 检查。FTP/FTPS 需要服务端 chroot 才能确保边界可信。
hostKeySha256	SFTP	必填的指纹字符串或非空固定指纹数组。格式：SHA256:<43-character unpadded base64>。不能与 allowUnknownHostKey 同时使用。
allowUnknownHostKey	SFTP	紧急兼容覆盖选项。设为 true 时会接受未经验证的服务端身份，并在结果中明确警告。
readOnly	全部	阻止上传、部署、创建目录、重命名和删除。仍可进行部署试运行。
operationTimeoutMs	全部	工具截止时间，包含排队和连接时间，默认为 120000 ms。整数范围为 100 到 3600000。原生传输超时同样适用。
maxTransferBytes	全部	每个文件的实际字节数上限，默认为 268435456（256 MiB），最大为 1099511627776（1 TiB）。必须为正的安全整数。
maxDeployFiles	全部	每次部署选中文件数上限，默认为 10000，最大为 100000。必须为正的安全整数；不限制完整目录扫描。
maxScanEntries	全部	每次部署访问的本地条目数，包含根目录、排除的条目和链接。默认为 100000，最大为 1000000；必须为正的安全整数。
maxScanDepth	全部	根目录下的目录深度上限，包含边界（深度 0）。默认为 64，最大为 256；必须为正的安全整数。
maxDeployBytes	全部	每次部署的源文件累计字节数上限，默认为 1073741824（1 GiB），最大为 1099511627776（1 TiB）。失败的尝试仍会占用其预留额度。
implicitTLS	FTPS	使用隐式 TLS，通常使用端口 990。
insecureTLS	FTPS	禁用证书验证。需要设置 allowInsecure: true。
allowInsecure	FTP/FTPS	明确接受明文 FTP 或未经验证的 FTPS。这不会使连接变得安全。
allowUnsafeRemoteRoot	FTP/FTPS	允许将 root 设为 / 以外的路径，即使符号链接逃逸风险尚未解决。仅当了解服务端账户边界时才使用。

任何字符串都可以包含 ${ENV:VARIABLE_NAME}。缺少变量时会产生包含变量名的配置错误。

带外验证 SFTP 指纹

不要仅信任即将通过待验证连接获取的指纹。

1. 从托管服务提供商经过身份验证的控制面板或支持渠道获取 SHA-256 主机密钥指纹，或通过单独经过身份验证的渠道向管理员获取。
2. 如果你管理该主机，请使用其可信控制台运行类似以下命令：ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256。
3. 在将完整的 SHA256:... 值填入 hostKeySha256 之前，先进行比对。ssh-keyscan 可以收集候选密钥，但仅凭它无法验证该密钥的身份。

轮换时，请先带外验证新指纹，临时配置新旧两个固定指纹，轮换服务器密钥，确认连接使用预期的密钥，然后移除旧指纹。不要将 allowUnknownHostKey 用作轮换捷径。

工具参考

所有远程路径参数均相对于已配置的远程 root。如果已设置 defaultServer 或仅有一个服务器，则 server 参数为可选。

工具	主要参数	用途
ftp_list_servers	无	显示服务器元数据和当前安全警告，绝不显示密码。
ftp_test	server?	连接并列出可见根目录。
ftp_list	server?、path?、limit?、offset?	列出远程目录。limit 默认为 50（1–200）；offset 默认为 0。
ftp_read	server?、path、max_bytes?	读取有大小限制的文本文件；不允许读取二进制数据。
ftp_upload	server?、local_path、remote_path?	从 localRoot 上传一个文件。
ftp_deploy	server?、local_dir、remote_dir?、include?、exclude?、dry_run?	从 localRoot 递归部署目录。
ftp_download	server?、remote_path、local_path、overwrite?	下载到 localRoot。
ftp_mkdir	server?、path	递归创建远程目录。
ftp_rename	server?、from_path、to_path	重命名或移动。
ftp_delete	server?、path、recursive?	删除文件，或在明确启用递归时删除目录。
ftp_plan_deploy	server?、local_dir、remote_dir?、include?、exclude?、ttl_seconds?	发布不可变、会过期的持久化计划。仅在配置 stateDir 时可用。
ftp_apply_deploy	plan_id、idempotency_key、resume?	确认、关联并明确恢复持久化应用操作。
ftp_deploy_status	plan_id / operation_id 中的一个（且仅一个）、offset?、limit?、if_journal_seq?	在不访问网络或写入状态的情况下，读取无锁分页持久化快照。
ftp_rollback_deploy	operation_id、resume?	确认并明确恢复对已持久确认文件的保守回滚。

持久化工作流保证

持久化工具要求使用官方 MCP input_required 确认流程；没有布尔值回退方案。签名请求状态会绑定会话、方法、计划摘要、操作、幂等键哈希、恢复选项、日志序列和过期时间。拒绝、无效、过期或不受支持的交互不会产生远程影响。仅关联时只能查看状态；任何非终态远程变更都要求 resume:true。

保证级别为 observable_state_reconciled：单文件替换取决于服务端，多文件原子性和恰好执行一次均不成立，回滚仅涵盖已持久确认的文件。SFTP 支持在现有规范父目录下替换文件和创建新文件；FTP/FTPS 仅支持替换现有普通文件。持久化执行绝不会创建父目录、清除远程多余文件、自动回滚，或回滚 SATISFIED_UNOWNED。

共享同一个规范 stateDir 的协作进程会在构造适配器前，对确切的服务端别名进行串行化。这不是分布式远程锁，也不会协调不同的别名或状态目录。存在重叠的可写别名、别名重命名、混合二进制版本升级，或进程在持有持久锁时被终止，都需要操作人员谨慎处理：升级前应暂停操作，并离线恢复陈旧锁。外部写入方和 ABA 变更不在可观测身份保证范围内。

经验证的暂存提升

上传和部署会写入一个不可预测的同级临时文件，根据本地源文件验证其实际字节数和 SHA256，然后通过一次重命名完成提升。验证或重命名失败时，绝不会删除最终目标，也不会回退为直接覆盖。下载会验证一个独占的本地临时文件，同步并关闭后，再提升完整文件。默认的 overwrite:false 会使用硬链接，避免覆盖期间出现的文件；不支持硬链接的文件系统会安全失败。

本地和 SFTP 替换会保留现有普通目标文件的权限位（0777）；FTP/FTPS 无法以可移植的方式保留权限，因此账户创建默认值、umask 和 ACL 策略需要适合目标位置。重命名行为取决于服务端和文件系统。旧版上传/部署不保证通用原子替换、站点事务或回滚。回读会增加网络流量。参见传输保证、限制和清理。

执行、取消与争用

在单个 Node 进程内，对于相同的规范化协议、主机名、端口和用户名，上传、部署、mkdir、重命名和删除操作按先进先出顺序执行。服务器别名和根目录共用同一把锁。下载操作按规范化的本地目标路径串行执行，即使来自不同服务器也是如此。只读远程操作可以并行执行。

MCP 取消和截止时间会关闭活动传输，并停止后续部署文件。错误会标明 CANCELLED 或 TIMEOUT；TARGET_BUSY 表示正在等待其他操作。超时调用可能在底层操作完成前返回，但在操作完成并清理之前，锁仍由该操作持有。不会自动重试结果不确定的变更操作。重试前请检查远程端和本地端是否存在部分变更；旧版变更调用不是事务性部署，也不提供回滚。

内部准备只能使用一次，且最多持续 10 秒，不会延长整体操作的截止时间。实际工作和清理完成前，准入名额会一直保留。准备好的上下文只会释放一次，包括在取消后才到达的情况；准备被取消或过期后，不会调用处理程序。准备回调本身可能产生影响。持久化工具遵循相同的完成处理规则。请参阅资源限制。

只有调用方提供进度令牌时，才会发送进度通知；计数器递增，且不包含路径或凭据文本。锁无法协调其他 Node 进程、DNS 别名、其他账户，或同一主机上的外部客户端。

响应兼容性、分页与注解

ftp_list 返回单页，而不是不受限制的目录列表。成功响应包含分页字段 total、count、offset、limit、has_more 和 next_offset。例如，请求 {"server":"prod","path":"/assets","limit":2,"offset":2} 可能包含以下有意省略部分内容的摘录。摘录省略了必需的顶层字段 server、path 和 security_warning，以及必需的逐条目字段 size_bytes 和 modified_at：

{
  "structuredContent": {
    "entries": [
      { "name": "app.css", "type": "file" },
      { "name": "app.js", "type": "file" }
    ],
    "total": 6,
    "count": 2,
    "offset": 2,
    "limit": 2,
    "has_more": true,
    "next_offset": 4
  }
}

为保持兼容性，现有的人类可读 content 文本会予以保留。成功时，除 ftp_read 外，每个工具都会公开 MCP outputSchema，并返回与之匹配的 structuredContent；ftp_read 成功时仍是有界的纯文本工具。九个结构化架构中的每一个都接受严格的成功结果结构或严格的 {error} 封装。工具执行错误会返回 isError: true，并提供本地化文本、结构化错误代码、请求 UUID、效果观察结果和安全重试指南。未知工具仍会被视为协议错误。请参阅错误约定。

进程最多允许 64 个工具调用，包括取消后仍在清理的工作线程。超出的调用会返回 CAPACITY_LIMIT。本地部署扫描采用异步方式，并有单独的限制；关于精确计数、SCAN_LIMIT 和已修正的自定义排除行为，请参阅资源限制。

所有工具都会发布 MCP 注解，描述其只读性、破坏性、幂等性和开放世界行为。这些注解是提供给客户端的提示，并非安全边界；请使用服务器凭据、readOnly、localRoot 以及上述协议控制来实施访问控制。ftp_deploy 的结构化结果包含摘要和有界样本，而非详尽的文件列表。

ftp_deploy 不是事务。如果一个或多个传输失败，该工具会返回 MCP 错误以及部分部署摘要；失败前已完成提升的文件不会回滚。

默认部署排除项包括 node_modules、.git、环境文件、日志、操作系统元数据、ftp-servers.json，以及任意深度下的 .ftp-mcp 内容。保留名称 .ftp-mcp-*.tmp 始终会被排除，即使显式的 include 模式匹配它也是如此，因此部署不会选中部分下载所用的临时文件。

客户端设置

npm run setup 会检测受支持的客户端，在更改现有客户端配置前创建带时间戳的备份，并输出仅适用于 UI 客户端的配置块。 如需手动连接客户端，请将下方路径替换为此检出目录的绝对路径：

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

常见位置包括 Claude Code 的 .mcp.json、Cursor 的 ~/.cursor/mcp.json，以及 Windsurf 的 ~/.codeium/windsurf/mcp_config.json。Claude Desktop 和其他客户端可通过其 MCP 设置接受相同的命令／参数结构。

也可以通过 npx -y [email protected] 启动已发布的 npm 包。更新前请核实准确版本；固定此版本并不会同时锁定 npm 的传递依赖解析结果。

FileZilla 导入与诊断

node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json
npm run doctor

导入的密码可能会解码为明文。请将输出保存在版本控制之外，限制其权限，添加 localRoot，并在连接前检查所有关于不安全传输或 FTP/FTPS 远程根目录的警告。 doctor 为只读操作，会报告配置和客户端连接情况，但不会打印密码。

从 v0.1 迁移到 v0.2

上方的可用性链接列出已发布的 0.3.2 版本。以下迁移步骤说明 v0.1 之后引入的安全变更；无需重新发布或移动现有发布标签。

1. 为每个用于上传、部署或下载的服务添加绝对路径 localRoot。
2. 为每个 SFTP 服务添加通过带外方式验证的 hostKeySha256。仅在临时、明确接受风险时使用 allowUnknownHostKey: true；不要同时配置这两个字段。
3. 对于 FTP/FTPS，优先使用专用的服务端 chroot，使其可见根目录为 /，并将 root 设为 /。非根目录客户端路径现在需要设置 allowUnsafeRemoteRoot: true，且无法防范服务端符号链接带来的风险。
4. 将失败的 ftp_deploy 视为部分部署：检查其摘要，并在重试前协调远程目录树。
5. 重新运行 npm run setup，或将 MCP 客户端命令更新为此检出目录，然后运行 npm run doctor 和一次试运行。

发布测试会检查新写入的敏感配置是否采用原子替换；仅凭版本号无法保证这一点。有关资格审核和发布步骤，请参阅 docs/RELEASE.md。

安全与限制

• FTP/FTPS 最强的安全边界是服务端自身的账户隔离或 chroot。客户端规范化会拒绝明显的路径遍历，但 FTP 缺少可移植的 REALPATH/LSTAT 原语，无法证明服务端符号链接始终位于配置的子根目录内。
• SFTP 会验证主机固定值，并使用 realpath/lstat 拒绝符号链接组件。攻击者控制的服务端仍可能在检查与操作之间更改文件系统状态。
• readOnly 可减少通过此 MCP 服务意外写入的情况，但不能替代由远程服务强制执行的只读凭据。
• FTP、insecureTLS、allowUnknownHostKey 和 allowUnsafeRemoteRoot 都是明确接受风险的选项，并非安全功能。

请阅读完整的安全模型和私密信息披露政策。

开发

npm test
npm run eval:scripted
node src/index.js --version
node src/index.js --help

测试套件使用本地 FTP 和 SFTP 服务，无需外部网络。欢迎贡献；请参阅 CONTRIBUTING.md。维护者应使用发布指南。可复现、托管于外部且只读的 Agent 评估，记录在 evaluations/README.md 中。

在源码检出目录中，npm run eval:scripted 会通过真实的 SDK 客户端和处理程序，使用内存远程适配器，以两种语言运行 43 个用例：共 86 项脚本化服务端一致性测试结果。报告和限制请参阅脚本化一致性指南；此命令不会评估模型，也不能替代单独的真实传输测试。

许可证

MIT — 请参阅 LICENSE。

作者

由驻巴黎的 Agentic AI 架构师兼外部 CAIO Alexandre Beguel 构建并维护。他致力于生产级 GenAI、LLMOps、LLM FinOps 和证据优先的 AI 治理。beguel.com · LinkedIn · 英语、法语和西班牙语个人资料