ftp-deploy-mcp 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) ftp-deploy-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.fr.md

@@ -0,0 +1,26 @@
+# Licence MIT — traduction informative
+
+[English — canonical license](./LICENSE) | **Français — traduction informative**
+
+Cette traduction facilite la lecture. Le texte anglais du fichier
+[LICENSE](./LICENSE) constitue la licence de référence.
+
+Copyright (c) contributeurs de ftp-deploy-mcp
+
+Il est accordé gratuitement à toute personne obtenant une copie de ce logiciel
+et des fichiers de documentation associés (le « Logiciel ») l'autorisation
+d'utiliser le Logiciel sans restriction, notamment les droits d'utiliser,
+copier, modifier, fusionner, publier, distribuer, concéder en sous-licence
+et/ou vendre des copies du Logiciel, et de permettre aux personnes auxquelles
+le Logiciel est fourni d'en faire autant, sous réserve des conditions suivantes :
+
+La mention de copyright ci-dessus et la présente autorisation doivent être
+incluses dans toutes les copies ou parties substantielles du Logiciel.
+
+LE LOGICIEL EST FOURNI « EN L'ÉTAT », SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU
+IMPLICITE, NOTAMMENT SANS GARANTIE DE QUALITÉ MARCHANDE, D'ADÉQUATION À UN USAGE
+PARTICULIER ET D'ABSENCE DE CONTREFAÇON. EN AUCUN CAS LES AUTEURS OU TITULAIRES
+DU COPYRIGHT NE PEUVENT ÊTRE TENUS RESPONSABLES D'UNE RÉCLAMATION, DE DOMMAGES
+OU DE TOUTE AUTRE RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UNE ACTION
+CONTRACTUELLE, DÉLICTUELLE OU AUTRE, DÉCOULANT DU LOGICIEL, DE SON UTILISATION
+OU DE TOUTE AUTRE OPÉRATION LIÉE AU LOGICIEL.

package/README.fr.md

@@ -0,0 +1,518 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/logo.svg" width="96" alt="logo ftp-deploy-mcp">
+
+# ftp-deploy-mcp
+
+**Le bouton déployer pour les agents de codage IA.**
+
+Donnez à Claude Code, Claude Desktop, Cursor, Windsurf, Trae, Antigravity ou
+tout client MCP un moyen ciblé de lister, lire, téléverser, télécharger et
+déployer des fichiers sur vos propres serveurs FTP, FTPS et SFTP.
+
+Le serveur stdio implémente la révision MCP `2026-07-28` avec le SDK TypeScript
+modulaire v2 stable et conserve la négociation historique du SDK pour les
+anciens clients MCP.
+
+*English version → [README.md](./README.md)*
+
+Langue de la CLI et des outils MCP : anglais par défaut ; utilisez `--lang fr` ou `FTP_MCP_LANG=fr`.
+[Périmètre et priorité des langues](./docs/LANGUAGES.fr.md).
+
+[![CI](https://github.com/alebgl77/ftp-deploy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/alebgl77/ftp-deploy-mcp/actions/workflows/ci.yml)
+[![Licence : MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](./package.json)
+[![Compatible MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
+
+<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/banner-fr.png" width="100%" alt="ftp-deploy-mcp — Déploiement contrôlé pour vos agents IA ; FTP, FTPS, SFTP via MCP stdio">
+
+</div>
+
+Des contrôles conçus pour le déploiement gardent les identifiants hors des
+réponses d'outils, proposent lecture seule et dry-run, et limitent l'accès aux
+fichiers locaux avec `localRoot`. Le dépôt est couvert par une suite e2e
+étendue utilisant des serveurs FTP et SFTP locaux. Aucune télémétrie.
+
+> **Disponibilité :** l'installation depuis les sources fonctionne aujourd'hui.
+> Le paquet npm n'est **pas encore publié** : `npx -y ftp-deploy-mcp` reste
+> indisponible. Le projet indique toujours que la publication dans le registre
+> MCP officiel est en attente ; l'installation depuis un registre n'est pas
+> proposée ici. Les releases de sources GitHub sont distinctes des publications
+> sur npm et le registre MCP officiel. Les pages Glama et MCP Index existantes
+> sont des fiches de découverte, pas la preuve d'un paquet installable.
+> Cette copie porte la version 0.3.1. Les versions sources publiées figurent sur
+> [GitHub Releases](https://github.com/alebgl77/ftp-deploy-mcp/releases/latest) ;
+> la release GitHub v0.3.0 publiée reste inchangée.
+
+## Documentation
+
+| Document | English | Français |
+|---|---|---|
+| Présentation et installation | [README](./README.md) | [README](./README.fr.md) |
+| Modifications | [Changelog](./CHANGELOG.md) | [Journal](./CHANGELOG.fr.md) |
+| Contribution | [Guide](./CONTRIBUTING.md) | [Guide](./CONTRIBUTING.fr.md) |
+| Politique de sécurité | [Policy](./SECURITY.md) | [Politique](./SECURITY.fr.md) |
+| Modèle de sécurité | [Model](./docs/SECURITY-MODEL.md) | [Modèle](./docs/SECURITY-MODEL.fr.md) |
+| Publication | [Guide](./docs/RELEASE.md) | [Guide](./docs/RELEASE.fr.md) |
+| Évaluation d'agents | [Instructions](./evaluations/README.md) | [Instructions](./evaluations/README.fr.md) |
+| Performances et intégration des agents | [Guide](./docs/AGENT-PERFORMANCE.md) | [Guide](./docs/AGENT-PERFORMANCE.fr.md) |
+| Conformité MCP scriptée | [Guide](./docs/SCRIPTED-EVALUATIONS.md) | [Guide](./docs/SCRIPTED-EVALUATIONS.fr.md) |
+| Langues de la CLI et des outils MCP | [Guide](./docs/LANGUAGES.md) | [Guide](./docs/LANGUAGES.fr.md) |
+| Contrat d'erreur MCP | [Contract](./docs/ERROR-CONTRACT.md) | [Contrat](./docs/ERROR-CONTRACT.fr.md) |
+| Transferts vérifiés par promotion | [Guide](./docs/TRANSFERS.md) | [Guide](./docs/TRANSFERS.fr.md) |
+| Limites de parcours et d'admission | [Limits](./docs/RESOURCE-BOUNDS.md) | [Limites](./docs/RESOURCE-BOUNDS.fr.md) |
+| Stockage d'état durable | [Library](./docs/STATE-STORAGE.md) | [Bibliothèque](./docs/STATE-STORAGE.fr.md) |
+| Modèle du workflow durable | [Model](./docs/WORKFLOW-MODEL.md) | [Modèle](./docs/WORKFLOW-MODEL.fr.md) |
+| Licence MIT | [Texte canonique](./LICENSE) | [Traduction informative](./LICENSE.fr.md) |
+
+## Architecture et scénarios
+
+Explorez les schémas d'architecture actuelle et cible et les scénarios illustratifs
+dans le [guide HTML interactif bilingue](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/index.html).
+Le guide et ses instructions
+de reconstruction en [anglais](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/README.md) et en
+[français](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/README.fr.md) se trouvent dans le dépôt, hors du paquet
+npm. Après clonage, ouvrez `site/index.html` localement et utilisez son
+sélecteur de langue.
+
+Les bannières du README ont été générées avec ChatGPT Image. Leur
+[provenance et leurs prompts exacts](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/assets/provenance/README.fr.md)
+documentent leur rôle illustratif ; elles ne constituent pas une certification.
+
+## Première installation depuis les sources
+
+1. Installez une version de Node.js prise en charge : 22, 24 ou 26 (minimum : 22).
+2. Lancez `git clone https://github.com/alebgl77/ftp-deploy-mcp.git`, puis
+   `cd ftp-deploy-mcp`.
+3. Lancez `npm ci --omit=dev --ignore-scripts`.
+4. Lancez `npm run setup`, puis modifiez la configuration générée : renseignez
+   un `localRoot` absolu, remplacez les identifiants et configurez le pin de clé
+   d'hôte SFTP ou les acceptations de risque FTP/FTPS décrites plus bas.
+5. Redémarrez le client MCP et essayez un dry-run :
+
+```text
+Appelez ftp_deploy avec :
+{"server":"prod","local_dir":"dist","remote_dir":"/","dry_run":true}
+```
+
+Sous Windows, `install.cmd`, et sous macOS/Linux, `./install.sh`, peuvent
+remplacer les étapes 3–4. Relisez chaque serveur généré avant la première
+connexion.
+
+Pour une version étiquetée, sélectionnez son tag exact avant l'installation.
+`npm ci` utilise le seul fichier de référence `package-lock.json`, avec six
+dépendances directes épinglées exactement et le graphe revu. Conservez-le avec
+les sources. `--ignore-scripts` désactive les scripts automatiques de cycle de
+vie des dépendances ; le setup est une action explicite distincte.
+
+Le fichier d'installation source v0.3.1 porte le nom
+`ftp-deploy-mcp-0.3.1-source.tar.gz` : 90 fichiers, dont ce verrouillage. Après
+vérification de sa publication et de ses empreintes, extrayez-le dans un dossier
+neuf :
+
+```bash
+tar --ignore-zeros -xzf ftp-deploy-mcp-0.3.1-source.tar.gz
+cd package
+npm ci --omit=dev --ignore-scripts
+node src/index.js setup
+```
+
+Cette archive d'installation exclut les tests et scripts de maintenance du dépôt ;
+le ZIP/tar automatique de GitHub contient le dépôt complet. Le `.tgz` npm distinct
+contient 89 fichiers sans verrouillage et reste non qualifié : un vrai consommateur
+npm a changé dix dépendances de production. Il ne garantit pas une installation
+verrouillée. Le [guide de publication](./docs/RELEASE.fr.md) décrit les contrôles
+et leurs limites.
+
+## Matrice protocoles et sécurité
+
+| Protocole | Identité du transport | Comportement de la racine distante | Usage recommandé |
+|---|---|---|---|
+| **SFTP** | Chiffré. `hostKeySha256` est obligatoire sauf si `allowUnknownHostKey: true` accepte explicitement le risque d'usurpation. | Les contrôles `realpath`/`lstat` refusent les composants symboliques et maintiennent les opérations sous `root`. Un serveur malveillant ou changeant peut encore créer une course entre contrôle et usage. | À privilégier, avec empreinte vérifiée hors bande. |
+| **FTPS** | Chiffré si le certificat est vérifié. `insecureTLS: true` exige aussi `allowInsecure: true` et supprime la protection MITM. | Une sous-racine côté client n'est pas un jail anti-symlink fiable. Un `root` autre que `/` est refusé sauf `allowUnsafeRemoteRoot: true`. | Utiliser un compte dédié, chrooté côté serveur, dont la racine visible est `/`. |
+| **FTP** | En clair. Refusé sauf si `allowInsecure: true` accepte interception et exposition des identifiants. | Même limite que FTPS : la vraie frontière est le compte/chroot serveur, pas le contrôle lexical du client. | Héritage uniquement, réseau de confiance et compte dédié chrooté. |
+
+Les trois protocoles appliquent aussi `localRoot` à `ftp_upload`,
+`ftp_deploy` et `ftp_download` afin de limiter les fichiers locaux accessibles
+au serveur MCP.
+
+## Ce que vous obtenez
+
+- Dix outils MCP ciblés : découverte et test des serveurs, liste, lecture,
+  téléversement, déploiement récursif, téléchargement, création de dossier,
+  renommage et suppression.
+- Plusieurs serveurs nommés dans une configuration locale.
+- Exclusions façon gitignore, dry-run et mode `readOnly` par serveur.
+- Import FileZilla, assistant de configuration et commande `doctor` en lecture
+  seule.
+- Identifiants chargés localement depuis la configuration, l'environnement ou
+  des clés SSH, et jamais renvoyés intentionnellement au modèle.
+
+## Configuration des serveurs
+
+Un chemin de configuration explicite fait autorité :
+
+1. `--config <chemin>`
+2. `FTP_MCP_CONFIG`, en l'absence de `--config`
+
+Une configuration explicite vide, absente, illisible ou invalide produit une
+erreur sans repli vers un autre fichier. Les outils MCP restent disponibles
+pour signaler le problème. `--config` exige un argument de chemin.
+
+Sans ces deux sélecteurs, la première configuration trouvée est utilisée :
+
+1. `./ftp-servers.json`
+2. `~/.ftp-mcp/servers.json`
+
+L'exemple pédagogique ci-dessous contient des commentaires. Un vrai fichier de
+configuration doit être du JSON strict ; partez de
+[ftp-servers.example.json](./ftp-servers.example.json).
+
+```jsonc
+{
+  "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
+    }
+  }
+}
+```
+
+Remplacez l'empreinte composée de `A`, volontairement inutilisable pour un vrai
+hôte. Pendant une rotation contrôlée, `hostKeySha256` accepte un tableau :
+
+```json
+"hostKeySha256": [
+  "SHA256:old_verified_43_character_base64_value_here",
+  "SHA256:new_verified_43_character_base64_value_here"
+]
+```
+
+Ces libellés montrent seulement la forme et ne sont pas des pins valides.
+Chaque valeur réelle contient exactement `SHA256:` suivi de 43 caractères
+base64 sans remplissage.
+
+### Référence des champs
+
+| Champ | Protocoles | Signification |
+|---|---|---|
+| `stateDir` | niveau supérieur | Répertoire absolu et normalisé facultatif pour l'état durable, canoniquement disjoint de chaque `localRoot`. Son activation publie les quatre outils durables. |
+| `requirePlan` | niveau supérieur | Avec `stateDir`, vaut `true` par défaut. Bloque les mutations distantes legacy sauf le dry-run de `ftp_deploy` ; `false` les conserve sous le même verrou persistant d'alias. |
+| `stateLimits` | niveau supérieur | Quotas stricts facultatifs pour l'état, les sauvegardes, plans, opérations, fichiers/octets de plan, octets/événements de journal et fichiers de sauvegarde. |
+| `protocol` | tous | Requis : `ftp`, `ftps` ou `sftp`. |
+| `host` / `port` / `user` | tous | Hôte, port et compte. Ports par défaut : 21, 990 pour FTPS implicite et 22 pour SFTP. |
+| `password` | tous | Mot de passe ou placeholder `${ENV:NOM}`. |
+| `privateKeyPath` / `passphrase` | SFTP | Chemin de clé SSH et passphrase optionnelle. `~` est étendu. Ces champs authentifient l'utilisateur, pas le serveur. |
+| `localRoot` | tous | Requis pour upload, deploy et download. Doit se résoudre en dossier local absolu existant ; `~` est accepté. Les chemins relatifs et les sorties par lien/jonction sont refusés. Un chemin d'outil absolu doit lui aussi rester à l'intérieur. |
+| `root` | tous | Racine distante, `/` par défaut. SFTP utilise realpath/lstat. FTP/FTPS exigent un chroot serveur pour une frontière fiable. |
+| `hostKeySha256` | SFTP | Empreinte obligatoire, chaîne ou tableau non vide. Format : `SHA256:<43 caractères base64 sans remplissage>`. Incompatible avec `allowUnknownHostKey`. |
+| `allowUnknownHostKey` | SFTP | Dérogation de compatibilité urgente. `true` accepte une identité serveur non vérifiée et affiche un avertissement. |
+| `readOnly` | tous | Bloque upload, deploy, mkdir, rename et delete. Le dry-run de deploy reste possible. |
+| `operationTimeoutMs` | tous | Délai d'un appel, attente et connexion comprises : 120000 ms par défaut. Entier de 100 à 3600000. Les délais natifs du transport restent actifs. |
+| `maxTransferBytes` | tous | Maximum d'octets réels par fichier : 268435456 (256 Mio) par défaut, maximum 1099511627776 (1 Tio). Entier positif représentable exactement. |
+| `maxDeployFiles` | tous | Maximum de fichiers sélectionnés par déploiement : 10000 par défaut, maximum 100000. Entier positif ; ne borne pas le parcours complet des dossiers. |
+| `maxScanEntries` | tous | Entrées locales visitées par déploiement, racine, exclusions et liens compris. Défaut 100000, maximum 1000000 ; entier positif sans perte. |
+| `maxScanDepth` | tous | Profondeur inclusive des dossiers sous la racine (niveau 0). Défaut 64, maximum 256 ; entier positif sans perte. |
+| `maxDeployBytes` | tous | Maximum cumulé d'octets sources par déploiement : 1073741824 (1 Gio) par défaut, maximum 1099511627776 (1 Tio). Les tentatives échouées conservent leur réservation. |
+| `implicitTLS` | FTPS | Active TLS implicite, normalement sur le port 990. |
+| `insecureTLS` | FTPS | Désactive la vérification du certificat. Exige `allowInsecure: true`. |
+| `allowInsecure` | FTP/FTPS | Accepte explicitement FTP en clair ou FTPS non vérifié. Ne sécurise pas la connexion. |
+| `allowUnsafeRemoteRoot` | FTP/FTPS | Autorise un `root` autre que `/` malgré le risque de sortie par symlink. À utiliser seulement si la frontière du compte serveur est comprise. |
+
+Toute chaîne peut contenir `${ENV:NOM_DE_VARIABLE}`. Une variable absente
+produit une erreur de configuration qui la nomme.
+
+### Vérifier une empreinte SFTP hors bande
+
+Ne faites pas confiance à une empreinte obtenue uniquement via la connexion que
+vous cherchez justement à vérifier.
+
+1. Obtenez l'empreinte SHA-256 depuis le panneau authentifié ou le support de
+   l'hébergeur, ou auprès d'un administrateur via un canal séparé et
+   authentifié.
+2. Si vous administrez l'hôte, utilisez sa console de confiance pour lancer par
+   exemple
+   `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256`.
+3. Comparez toute la valeur `SHA256:...` avant de la placer dans
+   `hostKeySha256`. `ssh-keyscan` peut collecter une clé candidate, mais ne
+   l'authentifie pas à lui seul.
+
+Pour une rotation, vérifiez la nouvelle empreinte hors bande, configurez
+temporairement les deux pins, changez la clé serveur, confirmez la connexion,
+puis retirez l'ancien pin. N'utilisez pas `allowUnknownHostKey` comme raccourci.
+
+## Référence des outils
+
+Tous les chemins distants sont relatifs au `root` distant. `server` est
+optionnel lorsqu'un `defaultServer` est défini ou qu'un seul serveur existe.
+
+| Outil | Paramètres principaux | Rôle |
+|---|---|---|
+| `ftp_list_servers` | aucun | Affiche les métadonnées et avertissements, jamais les mots de passe. |
+| `ftp_test` | `server?` | Se connecte et liste la racine visible. |
+| `ftp_list` | `server?`, `path?`, `limit?`, `offset?` | Liste un dossier distant. `limit` vaut 50 par défaut (1–200) ; `offset` vaut 0 par défaut. |
+| `ftp_read` | `server?`, `path`, `max_bytes?` | Lit un fichier texte borné ; refuse les binaires. |
+| `ftp_upload` | `server?`, `local_path`, `remote_path?` | Envoie un fichier depuis `localRoot`. |
+| `ftp_deploy` | `server?`, `local_dir`, `remote_dir?`, `include?`, `exclude?`, `dry_run?` | Déploie récursivement un dossier de `localRoot`. |
+| `ftp_download` | `server?`, `remote_path`, `local_path`, `overwrite?` | Télécharge dans `localRoot`. |
+| `ftp_mkdir` | `server?`, `path` | Crée un dossier distant récursivement. |
+| `ftp_rename` | `server?`, `from_path`, `to_path` | Renomme ou déplace. |
+| `ftp_delete` | `server?`, `path`, `recursive?` | Supprime un fichier ou, avec récursion explicite, un dossier. |
+| `ftp_plan_deploy` | `server?`, `local_dir`, `remote_dir?`, `include?`, `exclude?`, `ttl_seconds?` | Publie un plan durable immuable et expirant. Disponible seulement avec `stateDir`. |
+| `ftp_apply_deploy` | `plan_id`, `idempotency_key`, `resume?` | Confirme, associe puis reprend explicitement une application durable. |
+| `ftp_deploy_status` | exactement un de `plan_id` / `operation_id`, `offset?`, `limit?`, `if_journal_seq?` | Lit un instantané durable paginé, sans réseau ni écriture d'état. |
+| `ftp_rollback_deploy` | `operation_id`, `resume?` | Confirme et reprend explicitement le retour arrière prudent des fichiers durablement acquittés. |
+
+### Garanties du workflow durable
+
+Les outils durables exigent le flux officiel MCP `input_required`, sans repli
+booléen. L'état signé lie session, méthode, digest du plan, opération, hash de
+la clé d'idempotence, choix de reprise, séquence du journal et expiration. Un
+refus, une preuve invalide ou expirée, ou un client incompatible n'a aucun effet
+distant. L'association seule renvoie un statut ; toute mutation distante non
+terminale exige `resume:true`.
+
+Le niveau est `observable_state_reconciled` : le remplacement par fichier dépend
+du serveur, l'atomicité multi-fichiers et l'exécution exactement une fois sont
+fausses, et le retour arrière couvre seulement les fichiers durablement acquittés.
+SFTP remplace et crée seulement sous un parent canonique existant ; FTP/FTPS
+remplace seulement un fichier régulier existant. Aucun parent durable n'est créé,
+aucun extra distant purgé, aucun retour automatique lancé et aucun
+`SATISFIED_UNOWNED` restauré.
+
+Les processus coopérants partageant le même `stateDir` canonique sérialisent
+l'alias exact avant construction de l'adaptateur. Ce n'est pas un verrou distant
+distribué et cela ne coordonne ni aliases ni répertoires d'état différents.
+Aliases d'écriture qui se chevauchent, renommage d'alias, binaires mélangés et
+processus tué avec verrou persistant exigent une intervention : mettez les
+écrivains en pause pour les mises à niveau et récupérez les verrous hors ligne.
+Les écrivains externes et courses ABA restent hors de la garantie observable.
+
+### Promotion vérifiée depuis un fichier temporaire
+
+Les envois et déploiements écrivent dans un temporaire voisin imprévisible,
+vérifient son nombre réel d'octets et son SHA256 contre la source locale, puis
+le promeuvent par un unique renommage. Un échec de vérification ou de renommage
+ne déclenche jamais la suppression de la cible finale ni un repli vers un
+écrasement direct. Les téléchargements vérifient un temporaire local exclusif,
+le synchronisent et le ferment avant de promouvoir le fichier complet. Par
+défaut, `overwrite:false` utilise un lien physique pour préserver tout fichier
+apparu entre-temps ; les systèmes sans liens physiques échouent sans écraser.
+
+Les remplacements locaux et SFTP conservent les bits de droits (0777) d'une
+cible régulière existante ; FTP/FTPS ne le garantit pas de façon portable.
+Les droits de création du compte, l'umask et les ACL doivent donc convenir à
+la destination. Le renommage dépend du serveur et du système de fichiers.
+Le chemin legacy ne garantit ni remplacement atomique universel, ni transaction
+du site, ni retour arrière. La relecture augmente le trafic réseau. Voir les
+[garanties, limites et règles de nettoyage des transferts](./docs/TRANSFERS.fr.md).
+
+### Exécution, annulation et contention
+
+Dans un même processus Node, upload, deploy, mkdir, rename et delete suivent
+une file FIFO pour un protocole, nom d'hôte, port et utilisateur normalisés
+identiques. Les alias de serveur et les racines partagent ce verrou. Les
+téléchargements sont sérialisés par destination locale canonique, y compris
+entre serveurs. Les lectures distantes peuvent se chevaucher.
+
+Une annulation MCP ou l'expiration du délai ferme les transports actifs et
+arrête les fichiers suivants du déploiement. Les erreurs portent `CANCELLED`
+ou `TIMEOUT` ; `TARGET_BUSY` indique l'attente d'une autre opération. Une
+réponse peut précéder le règlement réel d'une opération bloquée, mais son
+verrou reste détenu jusqu'au règlement et au nettoyage. Aucune mutation
+incertaine n'est réessayée automatiquement. Inspectez l'état distant et local
+partiel avant de réessayer ; les mutations legacy ne sont pas transactionnelles
+et ne fournissent aucun retour arrière.
+
+La préparation interne est à usage unique et limitée à 10 secondes sans
+prolonger l'échéance globale. L'admission reste détenue jusqu'à la fin réelle
+du travail et du nettoyage. Un contexte préparé est libéré une fois, même s'il
+arrive après annulation ; le handler n'est pas appelé après une préparation
+annulée ou expirée. Les callbacks de préparation peuvent eux-mêmes agir. Les
+outils durables appliquent la même discipline de terminaison. Voir les
+[limites de ressources](./docs/RESOURCE-BOUNDS.fr.md).
+
+La progression n'est envoyée qu'avec un token fourni par l'appelant, sous
+forme de compteurs croissants, sans chemins ni texte d'identifiants. Les
+verrous ne coordonnent pas les autres processus Node, alias DNS, comptes ou
+clients externes présents sur le même hôte.
+
+### Compatibilité des réponses, pagination et annotations
+
+`ftp_list` renvoie une page plutôt qu'une liste de dossier non bornée. Une
+réponse réussie contient les champs de pagination `total`, `count`, `offset`,
+`limit`, `has_more` et `next_offset`. Par exemple, la requête
+`{"server":"prod","path":"/assets","limit":2,"offset":2}` peut produire
+l'extrait volontairement non exhaustif ci-dessous. Il omet les champs requis
+`server`, `path` et `security_warning` au premier niveau, ainsi que les champs
+requis `size_bytes` et `modified_at` de chaque entrée :
+
+```json
+{
+  "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
+  }
+}
+```
+
+Le texte historique, lisible par un humain dans `content`, est conservé pour
+compatibilité. En cas de succès, tous les outils sauf `ftp_read` annoncent
+aussi un `outputSchema` MCP et renvoient un `structuredContent` correspondant ;
+`ftp_read` conserve un succès texte borné. Chacun des neuf schémas structurés
+accepte soit sa forme stricte de succès, soit une enveloppe stricte `{error}`.
+Les erreurs d’exécution renvoient `isError: true`, un texte traduit, un code,
+un UUID de requête, les effets observés et une indication de reprise sûre.
+Un outil inconnu reste une erreur de protocole. Voir le
+[contrat d’erreur](./docs/ERROR-CONTRACT.fr.md).
+
+Le processus admet au plus 64 appels d’outil, y compris ceux encore en nettoyage
+après annulation. Les appels supplémentaires renvoient `CAPACITY_LIMIT`. Le parcours
+local d’un déploiement est asynchrone et borné séparément ; les [limites de ressources](./docs/RESOURCE-BOUNDS.fr.md)
+décrivent le comptage exact, `SCAN_LIMIT` et les exclusions personnalisées corrigées.
+
+Tous les outils publient des annotations MCP sur leur caractère lecture seule,
+destructif, idempotent et ouvert sur l'extérieur. Ces annotations guident les
+clients mais ne constituent pas une frontière de sécurité : imposez les accès
+avec les identifiants serveur, `readOnly`, `localRoot` et les contrôles de
+protocole décrits plus haut. Le résultat structuré de `ftp_deploy` contient un
+résumé et des échantillons bornés, pas des listes exhaustives de fichiers.
+
+`ftp_deploy` n'est pas une transaction. Si un ou plusieurs transferts échouent,
+l'outil renvoie une erreur MCP avec un résumé du déploiement partiel ; les
+fichiers déjà promus ne sont pas annulés.
+
+Les exclusions par défaut couvrent notamment `node_modules`, `.git`, les
+fichiers d'environnement, journaux, métadonnées système, `ftp-servers.json` et
+`.ftp-mcp` à toute profondeur.
+Le nom réservé `.ftp-mcp-*.tmp` est toujours exclu, même si un motif `include`
+explicite le sélectionne, pour ne pas déployer un temporaire de téléchargement partiel.
+
+## Configuration du client
+
+`npm run setup` détecte les clients pris en charge, crée des sauvegardes
+horodatées avant de modifier une configuration existante et affiche un bloc
+pour les clients configurés par interface. Pour un branchement manuel,
+remplacez le chemin par celui, absolu, de ce checkout :
+
+```json
+{
+  "mcpServers": {
+    "ftp": {
+      "command": "node",
+      "args": ["/chemin/absolu/vers/ftp-deploy-mcp/src/index.js"]
+    }
+  }
+}
+```
+
+Les emplacements courants sont `.mcp.json` pour Claude Code,
+`~/.cursor/mcp.json` pour Cursor et
+`~/.codeium/windsurf/mcp_config.json` pour Windsurf. Claude Desktop et les
+autres clients acceptent la même commande et les mêmes arguments dans leurs
+réglages MCP.
+
+Après vérification de la première publication npm, cette commande source pourra
+être remplacée par `npx -y ftp-deploy-mcp`. Ce n'est volontairement pas présenté
+comme une installation fonctionnelle aujourd'hui.
+
+## Import FileZilla et diagnostic
+
+```bash
+node src/index.js import-filezilla --file /chemin/sitemanager.xml --out ./ftp-servers.json
+npm run doctor
+```
+
+L'import peut décoder des mots de passe en clair. Gardez la sortie hors du
+contrôle de version, restreignez ses droits, ajoutez `localRoot` et examinez
+chaque avertissement de transport ou de racine FTP/FTPS avant la connexion.
+`doctor` reste en lecture seule et ne montre pas les mots de passe.
+
+## Migration de v0.1 vers v0.2
+
+La release GitHub v0.3.0 est publiée. Cette copie source porte la version
+0.3.1. Le paquet npm reste non publié et le projet indique toujours que la
+publication dans le registre MCP officiel est en attente. Les étapes ci-dessous
+concernent l'installation depuis les sources et n'annoncent pas une release npm.
+
+1. Ajoutez un `localRoot` absolu à tout serveur utilisé pour upload, deploy ou
+   download.
+2. Pour chaque serveur SFTP, ajoutez un `hostKeySha256` vérifié hors bande.
+   `allowUnknownHostKey: true` doit rester une acceptation de risque temporaire
+   et explicite ; ne configurez pas les deux champs.
+3. Pour FTP/FTPS, préférez un chroot serveur dédié dont la racine visible est
+   `/` et posez `root` à `/`. Une sous-racine exige désormais
+   `allowUnsafeRemoteRoot: true` et reste vulnérable aux symlinks serveur.
+4. Traitez l'échec de `ftp_deploy` comme un déploiement partiel : examinez le
+   résumé et réconciliez l'arbre distant avant de relancer.
+5. Relancez `npm run setup` ou mettez à jour la commande MCP vers ce checkout,
+   puis lancez `npm run doctor` et un dry-run.
+
+Le remplacement atomique des nouvelles configurations sensibles est une
+condition vérifiée par les tests de publication ; un numéro de version seul
+n'établit pas cette garantie. Consultez
+[docs/RELEASE.fr.md](./docs/RELEASE.fr.md) pour la qualification et la publication.
+
+## Sécurité et limites
+
+- La frontière FTP/FTPS la plus forte est l'isolation ou le chroot du compte
+  côté serveur. La normalisation client refuse les traversées évidentes, mais
+  FTP n'a pas de primitives `REALPATH`/`LSTAT` portables permettant de prouver
+  qu'un symlink serveur reste dans une sous-racine.
+- SFTP vérifie le pin d'hôte et refuse les composants symboliques via
+  `realpath`/`lstat`. Un serveur contrôlé par un attaquant peut encore changer
+  son état entre vérification et opération.
+- `readOnly` limite les écritures accidentelles via ce serveur MCP ; des droits
+  distants réellement en lecture seule restent plus forts.
+- FTP, `insecureTLS`, `allowUnknownHostKey` et `allowUnsafeRemoteRoot` sont des
+  acceptations explicites de risque, pas des fonctions de sécurité.
+
+Lisez le [modèle de sécurité complet](./docs/SECURITY-MODEL.fr.md) et la
+[politique de signalement privé](./SECURITY.fr.md).
+
+## Développement
+
+```bash
+npm test
+npm run eval:scripted
+node src/index.js --version
+node src/index.js --help
+```
+
+La suite de tests utilise des serveurs FTP et SFTP locaux, sans réseau externe.
+Les contributions sont bienvenues ; voir
+[CONTRIBUTING.fr.md](./CONTRIBUTING.fr.md). Les mainteneurs doivent suivre le
+[guide de release](./docs/RELEASE.fr.md). Une évaluation agent reproductible, en
+lecture seule et hébergée à l'extérieur, est décrite dans
+[evaluations/README.fr.md](./evaluations/README.fr.md).
+
+Depuis un checkout source, `npm run eval:scripted` exécute 43 cas dans les deux
+langues avec un adaptateur mémoire et les vrais handlers MCP. Le
+[guide de conformité scriptée](./docs/SCRIPTED-EVALUATIONS.fr.md) décrit rapports
+et limites ; cette commande n’évalue pas un modèle.
+
+## Licence
+
+MIT — voir le [texte anglais de référence](./LICENSE) et sa
+[traduction française informative](./LICENSE.fr.md).