v0.3.2 — Publication verification hardening

Full Changelog: v0.3.1...v0.3.2

v0.3.1 — Reproducible release qualification

Full Changelog: v0.3.0...v0.3.1

v0.3.0 — Durable, secure deployments

What's Changed

• Qualify v0.2.1 across platforms and remove SFTP latency by @alebgl77 in #11
• perf: reduce agent discovery and response processing overhead by @alebgl77 in #12
• test: stabilize lazy adapter deadline checks on macOS by @alebgl77 in #13

Full Changelog: v0.2.0...v0.3.0

v0.2.0 — Verified staged transfers, local confinement and a bilingual EN/FR interface

The GitHub tag and release are cut from this commit. Publication to npm and to
the MCP registry is still pending, so npx -y ftp-deploy-mcp and registry-based
installation do not work yet; install from source. Package and server metadata
are aligned at 0.2.0. All changes below are relative to 0.1.0, the only version
ever released.

Added

• Bilingual command line. --lang en and --lang fr (also --lang=fr) select
  the language of general and subcommand help, setup prompts and choices,
  connection-test labels, doctor diagnostics, import-filezilla warnings and
  server startup messages. The new FTP_MCP_LANG environment variable sets the
  same default, and the option takes precedence over it, including over an
  invalid environment value. The option is read before the subcommand parser and
  may appear before or after the subcommand. Only en and fr are accepted; an
  invalid or incomplete option exits unsuccessfully before setup or
  import-filezilla writes anything. OS locale variables such as LANG are
  never consulted. See languages.
• Localized MCP contracts. Tool titles, descriptions, input field descriptions,
  business success text and error messages follow the selected language. The ten
  tool names, structured result field names and public error codes are stable and
  are not translated, and no tool argument selects a language.
• setup writes FTP_MCP_LANG into the MCP client entries it generates,
  including en, so a configured server keeps its setup language after a
  restart. The paste-ready Trae snippet carries the same setting.
• Structured error envelope on every tool error. Alongside the isError text,
  results now carry structuredContent.error with schema_version, code,
  message, retryable, a per-call request_id UUID, next_action and
  effects. Upload, download and deployment errors can add a strict partial
  block (completed_files, completed_bytes, failed_files, optional
  total_files, and final). request_id is not a durable operation
  identifier; there is no journal, rollback or recovery command. This release
  returns retryable: false for every error and never retries an uncertain
  mutation. See the error contract.
• Six per-server configuration keys, each with an enforced default and maximum.
  Tool arguments cannot override them, and values must be positive safe integers:
  operationTimeoutMs (default 120000 ms, accepted range 100–3600000),
  maxTransferBytes (default 268435456, maximum 1099511627776),
  maxDeployFiles (default 10000, maximum 100000),
  maxDeployBytes (default 1073741824, maximum 1099511627776),
  maxScanEntries (default 100000, maximum 1000000) and
  maxScanDepth (default 64, maximum 256). These defaults apply to servers that
  do not set them, so a deployment that succeeded on 0.1.0 can now be refused
  with TRANSFER_LIMIT or SCAN_LIMIT before any connection is opened.
  BREAKING — operationTimeoutMs also introduces a deadline 0.1.0 never
  had: every tool call now aborts with TIMEOUT after 120000 ms by default,
  and unlike the other limits it fires mid-flight rather than refusing up
  front, so a large or slow ftp_deploy that ran to completion on 0.1.0 can
  stop part-way with files already promoted and no rollback. Raise
  operationTimeoutMs (up to 3600000) for slow links. See
  verified transfers and
  resource limits.
• Process-wide admission control. One Node isolate admits at most 64 concurrent
  tool calls; the 65th returns the new CAPACITY_LIMIT with effects:none,
  retryable:false and next_action:retry. This is a concurrency cap, not a
  lifetime quota: a slot is released when its worker and cleanup actually settle,
  including after cancellation or timeout, and there is no queue or automatic
  retry. Admission happens after schema validation and before preparation.
• MCP cancellation and per-call deadlines. A peer notifications/cancelled
  aborts the operation and the SDK suppresses its result, so clients must not
  expect a delivered CANCELLED envelope; the separate internal deadline
  returns TIMEOUT. Cancellation and expiry stop later stages and close the
  transport, but do not undo effects already accepted by the server. A public
  transport decorator corrects the installed SDK's cancellation gap for the
  numeric correlation ID 0 and the empty string ""; other IDs, including the
  string "0", keep native SDK behaviour.
• Serialized mutations. Writing tools take a FIFO lock on the remote endpoint
  (protocol, host, port, user) and ftp_download takes one on the canonical
  local destination, so two calls cannot interleave writes on the same target.
  Locks are held until the underlying worker actually settles, not until the
  response is sent, and they coordinate only within one Node.js process.
• Per-server localRoot boundary for ftp_upload, ftp_deploy, and
  ftp_download. The root must be absolute (with ~ expansion supported);
  traversal and local symlink/junction escapes are refused.
• SFTP host-key pinning through hostKeySha256, accepting one SHA-256
  fingerprint or a non-empty array for controlled key rotation.
• Explicit allowUnknownHostKey override for operators who temporarily accept
  an unverified SFTP server identity.
• Explicit allowUnsafeRemoteRoot override for FTP/FTPS operators who accept
  the unresolved symlink risk of a client-side sub-root.
• MCP output schemas and successful structured responses for every tool except
  the intentionally text-only ftp_read, plus annotations for all ten tools.
• Bilingual documentation set, each page in English and French:
  security model,
  release process,
  error contract,
  languages,
  verified transfers,
  resource limits,
  state storage,
  workflow model and
  scripted MCP conformance. CONTRIBUTING,
  SECURITY, LICENSE and this changelog gain French counterparts, joining the
  README pair that already shipped in 0.1.0; both README languages were
  rewritten for this release.
• A bilingual interactive HTML guide under site/, generated from
  site/project-data.json and site/i18n.json and verified in CI by
  scripts/build-guide.mjs --check. It lives in the repository only and is
  excluded from the npm package.
• A reproducible, external read-only agent evaluation fixture and 10-question
  MCP evaluation set, now in English (evaluations/read-only.xml) and French
  (evaluations/read-only.fr.xml), plus a separate scripted conformance runner
  of 43 scenarios executed in both languages against the real MCP SDK client and
  in-memory transport (npm run eval:scripted). The runner is repository
  tooling, is not an LLM benchmark, and is excluded from the npm package. See
  scripted MCP conformance.
• Internal, inert libraries src/state/ and src/workflow/. They ship inside
  the package because it publishes src, but they expose no MCP tool, read no
  configuration, create no state directory and are not imported by the running
  server. They deliver no deployment workflow, rollback or recovery in this
  release; both state storage and the
  workflow model state this explicitly.
• Contributor-facing npm scripts: test:transports, test:contract,
  test:bounds, test:state, test:workflow, test:eval-runner and
  eval:scripted. CI additionally runs scripts/check-docs.mjs for bilingual
  documentation and test/release-gates.js.
• server.json MCP registry metadata, declaring the FTP_MCP_CONFIG and
  FTP_MCP_LANG environment variables and a stdio transport.
• A repository Dockerfile and .dockerignore building a node:24-alpine
  image whose entrypoint is the stdio server; mount a configuration file and
  point FTP_MCP_CONFIG at it. No image is published, and neither file is
  included in the npm package.

Changed

• BREAKING — Node.js 18, 19, 20 and 21 are no longer supported.
  engines.node moves from >=18 to >=22. CI qualifies Node 22 and 24 on
  Linux, Windows and macOS.
• BREAKING — an explicit configuration selector now fails closed. When
  --config <path> or FTP_MCP_CONFIG is present, that single path is
  authoritative: it must exist, be a regular file and load successfully, and no
  other candidate is attempted. --config takes priority over
  FTP_MCP_CONFIG, and an empty explicit value is rejected. Only when neither
  is set does discovery still try ./ftp-servers.json then
  ~/.ftp-mcp/servers.json. In 0.1.0 both selectors were merely the first
  entries of a fallback list, so a missing or unreadable explicit path silently
  fell through to another file. The server still starts; every tool that needs
  the configuration now fails with CONFIG_INVALID instead of operating on an
  unintended configuration, and ftp_list_servers returns status: "invalid"
  with the loader diagnostic.
• One rejected server entry no longer disables the whole configuration. Entries
  are validated individually: valid servers stay usable, and each invalid one is
  reported by name with its reason through ftp_list_servers (status,
  valid_count, invalid_count and a bounded errors list). Naming a rejected
  entry returns that entry's CONFIG_INVALID, an unknown name
  returns SERVER_UNKNOWN, and omitting server with several valid candidates
  and no defaultServer returns SERVER_REQUIRED. In 0.1.0 the first invalid
  entry made the entire file unusable and every tool call failed. Envelope
  problems — no servers object, an empty one, an unknown `defaultSer...

v0.1.0 - The deploy button for AI coding agents

First public release.

ftp-deploy-mcp connects AI coding agents (Claude Code, Claude Desktop, Cursor, Windsurf, Trae, Antigravity) to your own FTP / FTPS / SFTP servers through the Model Context Protocol.

Highlights

• 10 MCP tools - list, read, upload, download, mkdir, rename, delete, test, list_servers, and a recursive ftp_deploy with dry-run
• Multi-server config (ftp-servers.json) with ${ENV:...} secret substitution and SSH key auth
• Security model: per-server path jail (no ../ escape, root undeletable), per-server read-only mode, credentials never enter the model context, gitignore-like excludes at any depth (.env, node_modules, .git, *.log)
• FileZilla import - convert sitemanager.xml in one command (incl. implicit FTPS and RemoteDir decoding)
• One-command setup - install.cmd / install.sh runs a wizard that imports your sites, tests connections, and auto-writes the MCP config of every detected client (with timestamped backups)
• doctor read-only diagnostic
• 189 e2e assertions against real local FTP + SFTP servers, green on Linux / Windows / macOS x Node 18 / 20 / 22

Install

git clone https://github.com/alebgl77/ftp-deploy-mcp.git
cd ftp-deploy-mcp
# Windows: double-click install.cmd - macOS/Linux:
./install.sh

Docs: English | Francais