ftp-deploy-mcp 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,415 @@
+# Changelog
+
+**English** | [Français](./CHANGELOG.fr.md)
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.1] - 2026-10-17
+
+This patch release is limited to release qualification and a supply-chain lock
+refresh. It preserves the immutable v0.3.0 tag and GitHub source release. npm
+and Official MCP Registry publication remain pending.
+
+### Fixed
+
+- Release qualification now locks the optional transitive `nan` dependency to
+  2.29.0, including its reviewed registry URL and integrity, matching the
+  version resolved by a fresh installation. No runtime behavior or public API
+  changes.
+
+### Changed
+
+- Package, lockfile, MCP server and bilingual release metadata now consistently
+  target v0.3.1. The complete v0.3.0 history remains below.
+
+## [0.3.0] - 2026-10-17
+
+This minor release uses the separate GitHub source release channel; the published v0.2.0 tag and
+release remain unchanged. npm and Official MCP Registry publication remain
+pending. Install from source; no npm, `npx` or registry availability is claimed.
+
+### Added
+
+- Optional durable deployment with `stateDir`: `ftp_plan_deploy`,
+  `ftp_apply_deploy`, `ftp_deploy_status`, and `ftp_rollback_deploy`. The
+  workflow uses official MCP `input_required` confirmation, sealed journals,
+  bounded verified backups, explicit resume, and conservative reconciliation.
+  Its guarantee is `observable_state_reconciled`, not multi-file atomicity or
+  exactly-once execution.
+- Privacy-safe state format v2 stores a domain-salted local-root hash and strict
+  relative source paths, never the absolute local root. Apply revalidates local
+  identity before connection; rollback remains usable after local-root drift.
+  State v1 requires offline reinitialization.
+
+### Fixed
+
+- Internal preparation is single-use, capped at 10 seconds without extending
+  the overall deadline, and retains admission until actual work and cleanup
+  settle. Prepared contexts are released once, including late completion after
+  cancellation. A cancelled or expired preparation never invokes the handler;
+  the preparation callback itself may act. No public MCP tool is added.
+- Release qualification compares the complete expected package manifest,
+  authoritative source lock and all shipped source bytes. Unapproved dependency
+  modifiers and installation hooks are refused before consumer installation.
+- Archive inspection reads and hashes compressed bytes once, performs strict
+  gzip decoding with a 32 MiB aggregate output cap, rejects nonzero data after
+  the consumed gzip boundary, and supplies the same decoded TAR to every tar
+  invocation. Terminal NUL padding is allowed; gzip/TAR member boundaries
+  cannot hide extra files from validation.
+- npm and MCP workflows separate qualification without OIDC or secrets from
+  publication in a fresh checkout pinned to `github.sha`. npm transfers the
+  exact uploaded artifact ID and original inventory/integrity values; the
+  publication job validates those bindings before creating its local proof.
+  Dependency installation, tests, smoke checks and `--runtime` execute only
+  outside privileged publication jobs.
+- Release metadata parsing accepts the supported npm pack JSON array/object
+  forms consistently in CI. Changelog dates must be valid calendar dates.
+
+### Changed
+
+- The MCP runtime now uses the stable modular TypeScript SDK v2.3.1:
+  `@modelcontextprotocol/server` is the exact production pin, while the exact
+  client and raw-wire core packages remain development-only. The stdio entry
+  uses the SDK's `serveStdio` factory, negotiates revision `2026-07-28`, and
+  retains the legacy client path, including revision `2024-11-05`.
+- The five direct production dependencies are pinned exactly; the sole
+  `package-lock.json` retains 35 reviewed non-root records (22 production and
+  13 development). No shrinkwrap is shipped.
+- The builder produces a 90-file source installation archive with its lockfile,
+  distinct from the 89-file npm package without a lockfile. Proofs explicitly
+  bind the distribution, sources and integrity.
+- Source installation uses `npm ci --omit=dev --ignore-scripts`; contributor
+  setup uses `npm ci --ignore-scripts`. Archive bytes may vary across systems.
+  The actual installed graph, including transitive dependencies and peers, is
+  compared with the original authority before publication.
+- npm remains unqualified after ten observed changes in a real installation.
+  MCP qualification checks the actual registry download, then the privileged
+  job requires its original integrity before authentication.
+
+- English/French installation and release documentation distinguishes GitHub
+  source releases from npm and Official MCP Registry availability.
+
+Scripted tests are not an LLM benchmark, and this minor release makes no
+enterprise-certification claim.
+
+## [0.2.0] - 2026-09-09
+
+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](./docs/LANGUAGES.md).
+- 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](./docs/ERROR-CONTRACT.md).
+- 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](./docs/TRANSFERS.md) and
+  [resource limits](./docs/RESOURCE-BOUNDS.md).
+- 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](./docs/SECURITY-MODEL.md),
+  [release process](./docs/RELEASE.md),
+  [error contract](./docs/ERROR-CONTRACT.md),
+  [languages](./docs/LANGUAGES.md),
+  [verified transfers](./docs/TRANSFERS.md),
+  [resource limits](./docs/RESOURCE-BOUNDS.md),
+  [state storage](./docs/STATE-STORAGE.md),
+  [workflow model](./docs/WORKFLOW-MODEL.md) and
+  [scripted MCP conformance](./docs/SCRIPTED-EVALUATIONS.md). `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](./docs/SCRIPTED-EVALUATIONS.md).
+- 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](./docs/STATE-STORAGE.md) and the
+  [workflow model](./docs/WORKFLOW-MODEL.md) 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 `defaultServer`, an
+  unset `${ENV:VAR}` — still reject the whole file, as does a file in which
+  every entry is invalid.
+- **BREAKING — `localRoot` is now required** by `ftp_upload`, `ftp_deploy` and
+  `ftp_download`, **and relative tool paths now resolve against it instead of
+  the server process's working directory.** A server entry without an absolute
+  `localRoot` refuses those three tools with `CONFIG_INVALID`. In 0.1.0
+  `local_path` and `local_dir` resolved against `process.cwd()`, so an unchanged
+  call such as `ftp_deploy {"local_dir":"dist"}` now reads `<localRoot>/dist`
+  instead of `<cwd>/dist` — it can silently select a different directory, or
+  fail with `NOT_FOUND` or `PATH_REJECTED` when the old target sits outside the
+  root. Absolute paths keep their meaning and must still resolve inside
+  `localRoot`. `ftp_list_servers` reports each server's `localRoot` status.
+- Tool errors are no longer text-only. Every error result now carries the
+  structured `{error}` envelope described above, and the nine tools with an
+  output schema publish a JSON Schema draft-07 `oneOf` of their success object
+  and that envelope. `ftp_read` keeps text-only success and no output schema;
+  its errors still use the same internally validated envelope. Existing text
+  responses remain available alongside structured successful responses, and
+  `ftp_deploy` still reports bounded samples rather than exhaustive file lists.
+- `ftp_upload`, `ftp_deploy` and `ftp_download` now verify every file before
+  promoting it. Uploads hash the local source with SHA256, write to an
+  unpredictable sibling named `.ftp-mcp-<random>.tmp`, read that temporary back,
+  compare byte count and digest, then promote with one rename. On failure the
+  server never deletes the final destination to make promotion succeed and never
+  falls back to a direct overwrite; it deletes only its own temporary, and a
+  cleanup failure adds a bounded warning that a temporary may remain. Downloads
+  read a bounded remote SHA256 expectation first, then promote by same-directory
+  hard link with `overwrite:false` (the default) or by rename with
+  `overwrite:true`. The basename pattern `.ftp-mcp-*.tmp` is reserved and always
+  excluded from `ftp_deploy`, even when an explicit `include` matches it. This
+  adds network traffic and latency, does not make a multi-file deployment
+  atomic, and does not promise universal atomic replacement: FTP and SFTP rename
+  behaviour depends on the server and filesystem. SFTP records the temporary's
+  server-assigned mode, restricts it to 0600 while writing, and before promotion
+  restores the existing destination's permission bits (0777 mask), or that
+  recorded creation mode for a new file; a required stat or chmod failure
+  prevents promotion. FTP/FTPS has no portable permission-preservation mechanism
+  here, so replacing an existing remote file can reset its permissions to the
+  server's creation defaults. Locally, `ftp_download` copies an existing
+  destination's 0777 bits onto its temporary, but a **new** local file is now
+  created with mode 0600 rather than 0.1.0's process-umask default, and
+  promotion with the default `overwrite:false` needs hard-link support in the
+  destination directory and fails closed without it. See
+  [verified transfers](./docs/TRANSFERS.md).
+- Deployment selection is now bounded and asynchronous. `maxScanEntries` and
+  `maxScanDepth` cap visited entries and directory depth; exceeding either
+  refuses the complete selection with `SCAN_LIMIT` (`effects:none`,
+  `retryable:false`, `next_action:fix_input`) before any remote connection, for
+  dry runs as well as real deploys. See
+  [resource limits](./docs/RESOURCE-BOUNDS.md).
+- **Deployment selection can now include files it previously skipped.** Only the
+  built-in `node_modules`, `.git` and `.ftp-mcp` directory names prune
+  traversal. Custom `exclude` patterns and `include` patterns no longer prune
+  directories; they keep their existing per-file matching rules. This removes a
+  former directory-probe false positive in which, for example,
+  `exclude: ["**/__ftp_deploy_probe__"]` also hid `docs/wanted.txt`. Review a
+  dry run after upgrading if you rely on exclusion patterns.
+- **BREAKING — plain FTP, and FTPS with `insecureTLS: true`, are now refused.**
+  0.1.0 had no insecure-transport gate and connected to both without objection.
+  0.2.0 raises `TRANSPORT_POLICY` before any network I/O unless the server entry
+  sets `allowInsecure: true`, so every 0.1.0 `"protocol": "ftp"` entry — the
+  default, namesake protocol of this package — stops connecting until that flag
+  is added.
+- **BREAKING — SFTP connections without `hostKeySha256` are refused** before
+  authentication, with `HOST_KEY_REJECTED`, unless `allowUnknownHostKey: true`
+  is explicitly configured. 0.1.0 performed no host-key verification and had no
+  such field, so every existing SFTP server entry stops connecting until one of
+  the two keys is added.
+- **BREAKING — FTP/FTPS connections whose `root` is not `/` are refused**
+  unless `allowUnsafeRemoteRoot: true` is explicitly configured;
+  `REMOTE_ROOT_REJECTED` is raised before any network I/O. 0.1.0 accepted any
+  `root` and its own README recommended exactly this pattern
+  (`"root": "/var/www/site"`), so those entries stop connecting until the flag
+  is added. The recommended boundary is now a dedicated server-side chrooted
+  account with `root: "/"`.
+- `ftp_deploy` returns an MCP error when any transfer fails and includes a
+  partial-deployment summary, now also as structured `partial` counters. Earlier
+  successful transfers are not rolled back.
+- `ftp_list` no longer returns every directory entry by default. It returns the
+  first 50 entries and pagination metadata; callers can select an offset and a
+  page size from 1 through 200.
+- Tool results are bounded to 25000 bytes of UTF-8 `JSON.stringify` covering
+  both text and structured data after redaction. Oversized results shrink their
+  bounded samples and rebuild pagination first, then truncate the largest text
+  body with a `… [output truncated]` marker, and fall back to `OUTPUT_LIMIT`
+  only when nothing can be shrunk — while preserving the request UUID, effects
+  and observed partial counters. This cap sits below `ftp_read`'s unchanged
+  `max_bytes` window (default 262144, hard max 1048576): a read that returned
+  256 KB of content on 0.1.0 now returns roughly 25 KB, marked as truncated, in
+  a successful result.
+- Boolean safety flags and SFTP fingerprint formats are validated per server.
+- `setup` surfaces active insecure-transport acknowledgments; `doctor` surfaces
+  active insecure-transport, unknown-host-key and unsafe-remote-root
+  acknowledgments.
+- Documentation now distinguishes the working source install from future
+  `npx` and MCP registry installation.
+- The published package now also ships `docs/`, `evaluations/`, `server.json`,
+  `CONTRIBUTING.md`, `CONTRIBUTING.fr.md`, `SECURITY.md`, `SECURITY.fr.md`,
+  `CHANGELOG.fr.md` and `LICENSE.fr.md`. The package and `server.json`
+  descriptions are now bilingual and describe local confinement and verified
+  staging.
+- New runtime dependency `zod-to-json-schema`, used to publish the tool input
+  and output JSON Schemas.
+- The local FTP test server now uses the `@electerm/ftp-srv` development
+  dependency.
+
+### Removed
+
+- `assets/banner.svg`, `assets/banner.png`, `assets/demo.svg` and
+  `assets/diagram.svg`. The README banners are now `assets/banner-en.png` and
+  `assets/banner-fr.png`, with their generation prompts and provenance recorded
+  under `assets/provenance/`.
+- The `ftp-srv` development dependency, replaced as noted above.
+
+### Fixed
+
+- Interactive manual server entry in `setup` no longer writes the wizard result
+  through a missing property.
+- Case variants of protocol names can no longer bypass insecure-transport
+  checks on setup and diagnostic paths.
+- Tool errors retain applicable security warnings, including failures after an
+  insecure connection may already have exposed credentials.
+
+### Security
+
+- Insecure transports are refused by default; see the **BREAKING** entry under
+  *Changed* for the new `allowInsecure` gate and its upgrade impact. Warnings
+  are attached to discovery, diagnostics, successes, and failures involving
+  accepted insecure transports.
+- SFTP resolves the configured remote root and uses realpath/lstat checks to
+  refuse symbolic-link components and resolved paths outside that root. A
+  malicious server can still race state between validation and operation. An
+  SFTP connection also pins its initial canonical root; a known root change
+  returns `TARGET_CHANGED` and refuses to rebase an owned temporary.
+- FTP/FTPS no longer describe lexical path normalization as a trustworthy
+  anti-symlink jail; server-side account isolation is the real boundary.
+- Local sources and download destinations are constrained under `localRoot`.
+- Non-interactive setup fails closed: it reports insecure transports but never
+  grants an `allowInsecure` exception automatically.
+- Error confidentiality is enforced at the result boundary. Error objects,
+  causes, stacks, credentials and raw arguments are never serialized; secrets
+  are masked in free text; configuration credentials are collected before
+  validation, including values from rejected entries and resolved `${ENV:VAR}`
+  placeholders, so loader diagnostics use the same mask. Malformed configuration
+  JSON yields a generic syntax diagnostic with no parser excerpt, and rejected
+  FileZilla blocks are identified by numeric index without echoing untrusted
+  names or protocol fields. Remote strings such as `Page:` and `SECURITY
+  WARNING` cannot impersonate the trusted notice rendering.
+- The committed lockfile resolves the MCP SDK's transitive `hono` dependency to
+  the patched 4.13.5.
+
+## [0.1.0] - 2026-07-20
+
+### Added
+
+- Ten MCP tools: `ftp_list_servers`, `ftp_test`, `ftp_list`, `ftp_read`,
+  `ftp_upload`, `ftp_deploy`, `ftp_download`, `ftp_mkdir`, `ftp_rename`, and
+  `ftp_delete`.
+- Multi-server configuration across FTP, FTPS, and SFTP.
+- Recursive directory deploy with gitignore-like excludes and dry-run.
+- Per-server remote `root` path normalization and `readOnly` mode.
+- `${ENV:VAR}` placeholders for configuration secrets.
+- FileZilla import, including implicit FTPS sites.
+- Setup wizard with MCP client configuration backups.
+- Read-only `doctor` diagnostic and source installers.
+- English and French documentation.
+- End-to-end tests against local FTP and SFTP servers.

package/CONTRIBUTING.fr.md

@@ -0,0 +1,120 @@
+# Contribuer à ftp-deploy-mcp
+
+[English](./CONTRIBUTING.md) | **Français**
+
+Merci d'envisager une contribution. Ce projet reste volontairement compact et
+limite ses dépendances ; lisez les principes ci-dessous avant d'ouvrir une PR.
+
+Le runtime MCP prend en charge Node.js >=22. L'outillage de publication exige **Node.js 24.20.0 exactement** : création et inspection des archives, inventaires source, contrôles du graphe installé, vérification du registre et `npm run test:release` refusent les autres versions avant ces opérations. Utilisez la distribution Node qualifiée, avec son npm fourni, et consignez les versions Node/libuv/npm/tar avec `node scripts/release-toolchain.mjs`. La qualification du consommateur peut toujours exécuter le serveur MCP avec Node 22 et appeler séparément les outils externes de publication avec Node 24.20.0.
+
+La CI conserve les neuf jobs runtime (Node 22/24/26 sur Linux, macOS et Windows). La suite complète de publication s'exécute séparément sur les trois systèmes avec Node 24.20.0. macOS comporte trois passes complètes prédéfinies ; tout échec fait échouer le job. Ces passes de qualification sont fixes, sans relance après échec, cas ignoré ni augmentation des limites d'archive. Les workflows supply-chain et de publication npm/MCP utilisent la même version Node exacte.
+
+## Environnement de développement
+
+```bash
+git clone https://github.com/alebgl77/ftp-deploy-mcp.git
+cd ftp-deploy-mcp
+npm ci --ignore-scripts
+npm test
+```
+
+`npm test` est le principal contrôle du code. Il démarre de vrais serveurs FTP
+et SFTP locaux sur des ports de boucle locale et exécute la suite de bout en
+bout contre eux : aucun accès réseau externe n'est requis ni utilisé. Pour
+les modifications de documentation seules, vérifiez aussi que les exemples
+JSON modifiés s'analysent, que les liens Markdown relatifs existent, puis
+exécutez `git diff --check`.
+
+## Mettre à jour le graphe de dépendances
+
+`package-lock.json` est l'unique fichier de verrouillage de référence ;
+n'ajoutez pas de `npm-shrinkwrap.json` parallèle. Les six dépendances directes de
+production sont épinglées à une version exacte. L'installation courante utilise
+`npm ci --ignore-scripts` et ne doit pas réécrire le graphe.
+
+Pour une mise à jour voulue, modifiez uniquement les versions exactes approuvées,
+régénérez le verrouillage source avec les scripts de cycle de vie désactivés et la version
+npm qualifiée, puis consignez cette version npm. Examinez toute entrée du graphe
+ajoutée, supprimée ou modifiée, notamment `resolved`, `integrity`, les contraintes
+facultatives/de plateforme et les hooks d'installation. N'acceptez pas de
+modifications sans rapport issues d'une mise à jour ou d'une correction d'audit
+automatique. Exécutez une installation propre, les tests concernés, l'audit des
+dépendances et les contrôles de l'archive exacte et du consommateur isolé du
+[guide de publication](./docs/RELEASE.fr.md). Présentez ensemble les modifications
+des sources, du manifeste et du verrouillage source pour la revue.
+
+La distribution d'installation source contient 90 fichiers, dont ce verrouillage. Le paquet npm distinct contient 89 fichiers sans verrouillage et reste non qualifié après dix dérives observées dans une installation réelle. Les contrôles du graphe installé comparent aussi les dépendances transitives et les peers à l'inventaire source original ; tout écart bloque la publication npm/MCP.
+
+## Principes
+
+- **JavaScript ESM simple.** Pas de TypeScript, d'outil de regroupement ni
+  d'étape de compilation. Le contenu de `src/` est exécuté tel quel.
+- **Aucune nouvelle dépendance d'exécution sans discussion.** Ouvrez d'abord
+  une issue si vous en jugez une nécessaire : les `dependencies` de
+  `package.json` sont volontairement limitées.
+- **Chaque fonctionnalité s'accompagne d'assertions de test.** Les nouveaux
+  outils, options ou comportements ne sont terminés qu'une fois couverts
+  dans `test/smoke.test.js`.
+- **Les garanties de sécurité reflètent les limites des protocoles.** Les
+  sous-racines FTP/FTPS côté client ne sont pas présentées comme un confinement
+  sûr contre les liens symboliques ; le compte/chroot dédié côté serveur est
+  la frontière. Les protections SFTP doivent documenter la course résiduelle
+  côté serveur.
+- **Disponibilité des sources et disponibilité d'une publication sont
+  distinctes.** N'annoncez pas l'installation par `npx` ou le registre MCP
+  avant que l'artefact correspondant soit public et vérifié indépendamment.
+- **En mode serveur, `stdout` est réservé à JSON-RPC.** N'utilisez jamais
+  `console.log` dans le chemin d'exécution du serveur MCP : toute sortie
+  standard est un message du protocole. Les diagnostics et les messages
+  destinés aux humains vont sur `stderr` ou dans les commandes `doctor`/`setup`
+  (hors mode serveur).
+
+## Exécuter une partie de la suite
+
+Exécutez la suite principale :
+
+```bash
+node test/smoke.test.js
+```
+
+Exécutez séparément la qualification des transports et les contrôles de publication :
+
+```bash
+node --test test/transport-qualification.js
+npm run test:release
+```
+
+`npm test` exécute la suite principale et la qualification des transports.
+Avant d'ouvrir une PR, lancez les deux ainsi que les contrôles de publication
+concernés par le changement ; gardez les assertions existantes activées.
+
+## Liste de contrôle d'une PR
+
+- [ ] `npm test` passe (utilisez le total actuel ; ne le figez pas dans la documentation).
+- [ ] Aucune nouvelle dépendance d'exécution, ou elle a d'abord été discutée dans une issue.
+- [ ] Les comportements ajoutés ou modifiés ont des assertions de test correspondantes.
+- [ ] `README.md` (anglais) et `README.fr.md` (français) sont mis à jour si le
+      comportement visible par l'utilisateur a changé.
+- [ ] Les nouveaux exemples de configuration sont en JSON strict et les liens
+      Markdown relatifs pointent vers des cibles existantes.
+- [ ] Les modifications sensibles pour la sécurité figurent dans
+      [docs/SECURITY-MODEL.fr.md](./docs/SECURITY-MODEL.fr.md).
+
+## Publication (mainteneurs)
+
+N'improvisez pas la première publication à partir de cette courte section.
+Suivez le [guide de publication](./docs/RELEASE.fr.md), qui couvre :
+
+- la concordance des versions du paquet, du verrouillage source, du serveur et du tag,
+  puis la vérification distincte des versions npm et du registre MCP officiel
+  après publication ;
+- la validation d'une archive propre et les tests de bout en bout ;
+- npm Trusted Publishing, la provenance et le recours à un `NPM_TOKEN` de
+  courte durée uniquement si l'amorçage de la première publication l'exige ;
+- les opérations manuelles de propriété et de publication sur le registre MCP ;
+- les vérifications après publication et le rétablissement par une nouvelle
+  version corrective.
+
+Le paquet npm et l'entrée du registre MCP ne sont disponibles qu'une fois
+tous les prérequis manuels applicables et toutes les vérifications de ce
+guide satisfaits.

package/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to ftp-deploy-mcp
+
+**English** | [Français](./CONTRIBUTING.fr.md)
+
+Thanks for considering a contribution. This project intentionally stays small and
+dependency-light — please read the principles below before opening a PR.
+
+The MCP runtime supports Node.js >=22. Release tooling requires **Node.js 24.20.0 exactly**: archive creation and inspection, source inventories, installed-graph checks, registry verification and `npm run test:release` reject other versions before performing those operations. Use the qualified Node distribution, including its bundled npm, and record Node/libuv/npm/tar versions with `node scripts/release-toolchain.mjs`. Consumer runtime qualification may still execute the MCP server with Node 22 while invoking the external release tools separately with Node 24.20.0.
+
+CI retains all nine runtime jobs (Node 22/24/26 on Linux, macOS and Windows). The complete release suite runs separately on all three operating systems with Node 24.20.0. macOS has three predefined full passes; any failed pass fails the job. These are fixed qualification passes, with no failure retries, skipped cases or increased archive limits. Supply-chain and npm/MCP publication workflows use the same exact release Node version.
+
+## Dev setup
+
+```bash
+git clone https://github.com/alebgl77/ftp-deploy-mcp.git
+cd ftp-deploy-mcp
+npm ci --ignore-scripts
+npm test
+```
+
+`npm test` is the main code gate. It spins up real local FTP and SFTP servers
+on loopback ports and runs the full e2e suite against them — no external
+network access is required or used. Documentation-only changes should also
+parse changed JSON examples, check relative Markdown links, and run
+`git diff --check`.
+
+## Updating the dependency graph
+
+`package-lock.json` is the only authoritative lockfile; do not add a parallel
+`npm-shrinkwrap.json`. The six direct production dependencies are exact pins.
+Routine setup uses `npm ci --ignore-scripts` and must not rewrite the graph.
+
+For an intentional update, change only the approved exact versions, regenerate
+the source lockfile with lifecycle scripts disabled and the qualified npm version,
+and record that npm version. Review every added, removed or changed graph entry,
+including `resolved`, `integrity`, optional/platform constraints and install
+hooks. Do not accept unrelated graph changes from an automatic update or audit
+fix. Run a clean install, the affected tests, the dependency audit and exact
+tarball/isolated-consumer checks in the [release guide](./docs/RELEASE.md).
+Keep the source, manifest and lockfile changes together for review.
+
+The source installation distribution contains 90 files, including this lockfile. The separate npm package contains 89 files without a lockfile and remains unqualified after ten observed changes in a real installation. Installed-graph checks compare transitive dependencies and peers against the original source inventory; any difference blocks npm/MCP publication.
+
+## Principles
+
+- **Plain ESM JavaScript.** No TypeScript, no bundler, no build step. What's in
+  `src/` is what runs.
+- **No new runtime dependencies without discussion.** Open an issue first if you
+  think one is needed — `dependencies` in `package.json` are kept deliberately
+  minimal.
+- **Every feature lands with smoke-test assertions.** New tools, options, or
+  behaviors are not considered done until they're covered in
+  `test/smoke.test.js`.
+- **Security claims match protocol reality.** FTP/FTPS client-side sub-roots
+  are not described as a symlink-safe jail; a dedicated server-side
+  account/chroot is the boundary. SFTP protections must document the residual
+  server-side race.
+- **Source and published availability are distinct.** Do not advertise `npx`
+  or MCP registry installation until the corresponding artifact is public and
+  independently verified.
+- **`stdout` in server mode is JSON-RPC only.** Never `console.log` from the MCP
+  server path — anything written to stdout is a wire-protocol message.
+  Diagnostics and human-facing output belong on `stderr` or in `doctor`/`setup`
+  (non-server) commands.
+
+## Running part of the suite
+
+Run the main smoke suite:
+
+```bash
+node test/smoke.test.js
+```
+
+Run the transport qualification and release gates separately:
+
+```bash
+node --test test/transport-qualification.js
+npm run test:release
+```
+
+`npm test` runs the main smoke suite and transport qualification. Before
+opening a PR, run both and any release gates affected by the change; keep
+existing assertions enabled.
+
+## PR checklist
+
+- [ ] `npm test` passes (use the current total; do not hard-code it in docs).
+- [ ] No new runtime dependency, or it was discussed in an issue first.
+- [ ] New/changed behavior has matching smoke-test assertions.
+- [ ] Docs updated in both `README.md` (English) and `README.fr.md` (French) if
+      user-facing behavior changed.
+- [ ] New configuration examples are strict JSON and relative Markdown links
+      resolve.
+- [ ] Security-sensitive changes are reflected in
+      [docs/SECURITY-MODEL.md](./docs/SECURITY-MODEL.md).
+
+## Releasing (maintainers)
+
+Do not improvise the first publication from this short section. Follow the
+[release guide](./docs/RELEASE.md), which covers:
+
+- matching package, lockfile, server and tag versions, then separately
+  verifying npm and Official MCP Registry versions after publication;
+- clean-tarball validation and end-to-end tests;
+- npm Trusted Publishing/provenance and the short-lived `NPM_TOKEN` fallback
+  needed only when first-publication bootstrapping requires it;
+- manual MCP registry ownership and publication;
+- post-publish verification and fix-forward rollback.
+
+The npm package and MCP registry entry are not available until every applicable
+manual prerequisite and verification step in that guide has passed.