ftp-deploy-mcp 0.0.0-stage → 0.3.1

package/SECURITY.md

@@ -0,0 +1,94 @@
+# Security Policy
+
+**English** | [Français](./SECURITY.fr.md)
+
+## Supported versions
+
+The project has not yet completed its first npm or MCP registry publication.
+Security fixes target the current source branch and the latest tagged 0.x
+release. Older 0.x tags may be asked to upgrade rather than receive a backport.
+
+| Version | Support |
+|---|---|
+| Current source / latest 0.x tag | Supported |
+| Older 0.x tags | Best effort |
+
+## Report a vulnerability privately
+
+**Do not open a public GitHub issue, discussion, or pull request for a suspected
+vulnerability.**
+
+Use GitHub's private vulnerability reporting: open the
+[repository Security page](https://github.com/alebgl77/ftp-deploy-mcp/security),
+choose **Report a vulnerability**, and include:
+
+- affected commit or version and protocol;
+- minimal reproduction steps and required server configuration;
+- expected versus observed access or disclosure;
+- impact, including which local or remote files/credentials are exposed;
+- any suggested remediation or disclosure deadline.
+
+Avoid including live credentials or private keys. Use disposable test accounts
+and redact logs. If private reporting is unavailable, open a public issue that
+contains no vulnerability details and asks the maintainer to establish a
+private channel.
+
+The target is to acknowledge a complete report within 72 hours, then confirm
+scope, coordinate a fix and tests, and agree on a disclosure date. This is a
+response target, not a bug-bounty or resolution-time promise.
+
+## In scope
+
+- Access outside `localRoot` through traversal, symlink, junction, or download
+  destination handling.
+- SFTP access outside `root`, host-key verification bypass, or unsafe handling
+  of a verified host-key rotation.
+- FTP/FTPS connection to a non-root client jail without the explicit
+  `allowUnsafeRemoteRoot` acknowledgment.
+- Plain FTP or unverified FTPS without the explicit `allowInsecure`
+  acknowledgment.
+- Credential or key material exposed in tool results, diagnostics, logs, or
+  errors.
+- `readOnly` bypass, destructive-operation guard bypass, or incorrect success
+  reporting after a partial deployment.
+- Corruption or unsafe replacement of server or MCP client configuration.
+- A release archive accepted with changed shipped source, a changed dependency
+  manifest or source lockfile, or an unapproved dependency modifier or install hook.
+
+Issues that depend on a malicious FTP server using symlinks outside a
+client-configured sub-root are important but are **not claimed to be prevented**:
+FTP/FTPS require a server-side account/chroot boundary. Likewise, SFTP
+realpath/lstat checks reduce symlink escapes but cannot remove every race on a
+malicious server. These limits are documented in the
+[security model](./docs/SECURITY-MODEL.md).
+
+## Dependency and release integrity
+
+The six direct production dependencies use exact versions.
+`package-lock.json` is the sole source graph authority, shipped in the 90-file
+source installation archive. Use `npm ci --omit=dev --ignore-scripts` after
+extraction and retain this file. Changes require review of the complete graph,
+its URLs and integrity values, then the checks in the
+[release guide](./docs/RELEASE.md).
+
+The 89-file npm package contains no lockfile and remains unqualified. A real
+installation changed ten production dependencies. Workflows reject installed
+graph drift before npm or MCP publication; a source proof cannot authorize npm.
+A future matching npm graph is evidence only for the tested environment and date,
+with no guarantee about future installations.
+
+A passing dependency audit is evidence for that graph on that date, not a
+guarantee against future advisories or a certification of production use.
+Report archive-validation bypasses privately using the same process above.
+GitHub releases do not establish npm or Official MCP Registry availability.
+
+## Research guidelines
+
+- Test only systems and accounts you own or are authorized to assess.
+- Do not access other users' data, degrade service, persist access, or use
+  social engineering.
+- Stop once the issue is demonstrated and share details privately.
+- Give the project a reasonable opportunity to remediate before disclosure.
+
+Good-faith research following these guidelines is welcome, but this document
+does not grant authorization against third-party FTP/SFTP services.

package/docs/AGENT-PERFORMANCE.fr.md

@@ -0,0 +1,144 @@
+# Performances et intégration des agents
+
+[English](./AGENT-PERFORMANCE.md)
+
+Les optimisations réduisent les calculs locaux répétés dans le serveur MCP.
+Elles s'appliquent à tout client utilisant ses outils stdio, quel que soit le
+fournisseur du modèle. L'architecture, les noms des outils, les arguments, les
+schémas de réponse, la vérification des transferts, l'annulation et les limites
+d'admission sont conservés.
+
+- L'adaptateur FTP/SFTP sélectionné est chargé au premier usage. Le coût de
+  l'import est reporté à la première connexion ; les suivants utilisent le
+  cache de modules de Node.
+- Chaque redactor garde en cache les secrets littéraux triés et les motifs
+  compilés des secrets courts, puis les reconstruit à l'ajout d'un nouveau
+  secret distinct. La mémoire supplémentaire croît avec le nombre de secrets ;
+  l'ordre des remplacements et le comportement normal/strict sont préservés.
+- Un comptage incrémental exact des octets JSON évite de sérialiser à répétition
+  les échantillons qui grandissent. La troncature du texte évite aussi une
+  sérialisation complète en double. Le contenu et les plafonds des réponses
+  sont préservés.
+
+## Connecter un agent
+
+Installez les sources comme indiqué dans le [README](../README.fr.md). Utilisez
+Node.js 22 ou plus récent et des chemins absolus explicites. Cette définition
+générique utilise le checkout comme répertoire de travail du processus et
+sélectionne directement la configuration des serveurs :
+
+```json
+{
+  "command": "node",
+  "args": [
+    "/chemin/absolu/vers/ftp-deploy-mcp/src/index.js",
+    "--config",
+    "/chemin/absolu/vers/ftp-servers.json"
+  ],
+  "cwd": "/chemin/absolu/vers/ftp-deploy-mcp"
+}
+```
+
+Adaptez la configuration englobante au client. S'il n'accepte pas `cwd`, fixez
+explicitement le répertoire de travail du lanceur ; conservez les deux chemins
+absolus dans les arguments. `localRoot`, dans la configuration des serveurs,
+détermine l'arborescence locale autorisée. `FTP_MCP_CONFIG` est une alternative
+à `--config`, qui reste prioritaire. Voir la
+[configuration](../README.fr.md#configuration-des-serveurs).
+
+| Client agent | Mode d'intégration |
+| --- | --- |
+| Claude Code / Claude Desktop | Ajoutez la commande et les arguments sous `mcpServers` ; voir la [configuration du client](../README.fr.md#configuration-du-client). |
+| OpenAI Agents SDK pour JavaScript | Créez `MCPServerStdio` avec les options de lancement, connectez-le et ajoutez-le aux `mcpServers` de l'agent. Fermez-le à la fin. Voir le [guide MCP du SDK](https://openai.github.io/openai-agents-js/guides/mcp/). |
+| Gemini CLI | Ajoutez les options de lancement sous `mcpServers` dans `settings.json` ; voir le [guide MCP de Gemini CLI](https://geminicli.com/docs/tools/mcp-server/). |
+| Qwen-Agent | Fournissez une configuration d'outil contenant `mcpServers` avec la commande et les arguments ; voir l'[exemple MCP de Qwen-Agent](https://github.com/QwenLM/Qwen-Agent#how-to-use-mcp). |
+
+Ces modes décrivent la compatibilité stdio ; ils ne constituent pas des
+résultats de tests de bout en bout propres à chaque fournisseur. Une
+intégration MCP distante hébergée nécessite un serveur MCP HTTP accessible ou
+un pont distinct. Ce dépôt expose stdio et n'ajoute ni serveur HTTP ni pont.
+
+Pour un catalogue stable, OpenAI Agents SDK accepte l'option
+`cacheToolsList: true` dans `MCPServerStdio`. Elle évite de répéter la découverte
+des outils côté client. Invalidez ce cache avec `invalidateToolsCache()` si le
+catalogue change ; voir les [conseils de cache du SDK](https://openai.github.io/openai-agents-js/guides/mcp/#other-things-to-know).
+
+## Cibler les appels
+
+- Appelez `ftp_list` avec un `limit` adapté (50 par défaut, 200 au maximum).
+  Suivez le `next_offset` renvoyé seulement si d'autres entrées sont utiles.
+  La pagination borne la réponse MCP ; l'adaptateur récupère toujours la liste
+  du dossier distant.
+- Appelez `ftp_read` avec un `max_bytes` explicite, par exemple 8192 pour un
+  petit fichier de configuration. Le défaut est de 256 Kio et le plafond de 1 Mio.
+- Attendez chaque mutation dont dépend la suivante. Terminez par exemple un
+  envoi avant de renommer sa destination. Les lectures indépendantes peuvent
+  se chevaucher ; les verrous FIFO et les [limites d'admission](./RESOURCE-BOUNDS.fr.md)
+  restent actifs.
+- Examinez un appel `ftp_deploy` avec `dry_run: true` avant le déploiement réel.
+  Cette simulation n'effectue aucune entrée-sortie réseau et ne vérifie pas
+  la cible distante.
+
+Des réponses bornées et pertinentes, ainsi que la mesure du nombre d'appels,
+du temps d'exécution et des erreurs suivent les
+[conseils de conception d'outils d'Anthropic](https://www.anthropic.com/engineering/writing-tools-for-agents).
+
+## Reproduire les contrôles
+
+Depuis un checkout complet avec les dépendances de développement :
+
+```bash
+npm ci --ignore-scripts
+npm run test:performance
+npm test
+npm run test:eval-runner
+npm run eval:scripted
+```
+
+`test:performance` exécute `test/redaction-performance.test.mjs` et
+`test/agent-performance.test.mjs` ; ces régressions font aussi partie de
+`npm test`.
+
+Le benchmark d'exécution exige un checkout intact comme premier argument.
+Créez et installez cette référence une fois, ou utilisez un checkout existant
+du même commit :
+
+```bash
+git worktree add --detach ../ftp-deploy-mcp-baseline a068aa5c3b1e53caaffc2c7907966ff5a2e9cb0f
+npm --prefix ../ftp-deploy-mcp-baseline ci --ignore-scripts
+npm run benchmark:agents -- ../ftp-deploy-mcp-baseline 200
+```
+
+Le dernier argument optionnel est le nombre positif d'itérations (200 par
+défaut). `benchmark:agents` exécute `scripts/benchmark-agent-performance.mjs`
+avec des fixtures locales, vérifie l'équivalence des sorties et rapporte le
+travail de sérialisation et la durée. Sa mesure de découverte couvre l'import
+des modules, l'enregistrement et la liste des outils, sans le handshake stdio
+complet. Consignez le commit, la version de Node.js, le système d'exploitation
+et la charge avec les mesures ; répétez les comparaisons sur la même machine.
+Sur les premières versions de Node.js 22 sans instrumentation des imports,
+les contrôles utilisant ces hooks sont ignorés et les nombres de modules sont
+indisponibles ; les mesures de durée du benchmark restent exécutées.
+
+Le microbenchmark de masquage est optionnel et compare des sorties de fixtures
+identiques à celles de l'implémentation précédente. Il affiche des médianes
+indicatives sans assertion sur la durée. Dans un shell POSIX :
+
+```bash
+REDACTION_BENCHMARK=1 node --test test/redaction-performance.test.mjs
+```
+
+Dans PowerShell :
+
+```powershell
+$env:REDACTION_BENCHMARK = '1'
+node --test test/redaction-performance.test.mjs
+Remove-Item Env:REDACTION_BENCHMARK
+```
+
+Les tests et benchmarks mesurent le comportement de l'implémentation et son
+exécution locale. Les [évaluations scriptées](./SCRIPTED-EVALUATIONS.fr.md)
+exercent les handlers MCP sans modèle. Ils ne démontrent ni qualité du modèle,
+ni économie de tokens, ni latence d'un fournisseur, ni débit FTP/SFTP en
+production. Les [instructions d'évaluation d'agents](../evaluations/README.fr.md)
+couvrent séparément les essais avec un modèle.

package/docs/AGENT-PERFORMANCE.md

@@ -0,0 +1,133 @@
+# Agent performance and client integration
+
+[Français](./AGENT-PERFORMANCE.fr.md)
+
+The performance work reduces repeated local computation in the MCP server.
+It applies to any client using its stdio tools, independently of the model
+provider. The server architecture, tool names, arguments, response schemas,
+transfer verification, cancellation and admission limits remain in place.
+
+- The selected FTP/SFTP adapter loads on first use. Its import cost moves to
+  the first connection; subsequent imports use Node's module cache.
+- Each redactor caches sorted secret literals and compiled short-secret
+  patterns, rebuilding them when a new distinct secret is collected. Extra
+  storage grows with the number of secrets; replacement order and normal/strict
+  behavior are preserved.
+- Exact incremental JSON byte accounting avoids repeatedly serializing growing
+  samples. Text truncation also avoids a duplicate full-result serialization.
+  Response content and size limits are preserved.
+
+## Connect an agent
+
+Install from source as described in the [README](../README.md). Use Node.js 22
+or newer and explicit absolute paths. This generic launch specification uses
+the checkout as the process working directory and selects the server
+configuration directly:
+
+```json
+{
+  "command": "node",
+  "args": [
+    "/absolute/path/to/ftp-deploy-mcp/src/index.js",
+    "--config",
+    "/absolute/path/to/ftp-servers.json"
+  ],
+  "cwd": "/absolute/path/to/ftp-deploy-mcp"
+}
+```
+
+Adapt the surrounding configuration to the client. If it has no `cwd` setting,
+set the launcher's working directory explicitly; keep both argument paths
+absolute. `localRoot` in the server configuration determines the allowed local
+file tree. `FTP_MCP_CONFIG` is an alternative to `--config`; the command-line
+selector takes precedence. See [configuration](../README.md#server-configuration).
+
+| Agent client | Integration route |
+| --- | --- |
+| Claude Code / Claude Desktop | Add the command and arguments under `mcpServers`; see [client setup](../README.md#client-setup). |
+| OpenAI Agents SDK for JavaScript | Create `MCPServerStdio` with the launch options, connect it and attach it to the agent's `mcpServers`. Close it when finished. See the [SDK MCP guide](https://openai.github.io/openai-agents-js/guides/mcp/). |
+| Gemini CLI | Add the launch options under `mcpServers` in `settings.json`; see the [Gemini CLI MCP guide](https://geminicli.com/docs/tools/mcp-server/). |
+| Qwen-Agent | Supply a tool configuration containing `mcpServers` with the command and arguments; see the [Qwen-Agent MCP example](https://github.com/QwenLM/Qwen-Agent#how-to-use-mcp). |
+
+These routes describe stdio compatibility; they are not provider-specific
+end-to-end test results. Remote hosted MCP integrations require an accessible
+HTTP MCP server or a separate bridge. This repository exposes stdio and adds
+no HTTP server or bridge.
+
+For a stable tool catalog, the OpenAI Agents SDK optionally accepts
+`cacheToolsList: true` in `MCPServerStdio`. This avoids repeated client-side
+tool discovery. Invalidate the cache with `invalidateToolsCache()` when the
+catalog changes; see the [SDK caching guidance](https://openai.github.io/openai-agents-js/guides/mcp/#other-things-to-know).
+
+## Keep calls focused
+
+- Use `ftp_list` with an appropriate `limit` (default 50, maximum 200). Follow
+  the returned `next_offset` only when more entries are needed. Pagination
+  bounds the MCP response; the adapter still obtains the remote directory list.
+- Use `ftp_read` with an explicit `max_bytes`, for example 8192 for a small
+  configuration file. The default is 256 KiB and the hard maximum is 1 MiB.
+- Await dependent mutations in sequence. For example, finish an upload before
+  renaming its destination. Independent reads may overlap; the server's FIFO
+  locks and [admission limits](./RESOURCE-BOUNDS.md) still apply.
+- Review an `ftp_deploy` call with `dry_run: true` before executing the deploy.
+  The dry run performs no network I/O and does not verify the remote endpoint.
+
+Bounded, relevant responses and measurement of tool-call counts, runtime and
+errors follow [Anthropic's tool design guidance](https://www.anthropic.com/engineering/writing-tools-for-agents).
+
+## Reproduce the checks
+
+Run from a full repository checkout with development dependencies installed:
+
+```bash
+npm ci --ignore-scripts
+npm run test:performance
+npm test
+npm run test:eval-runner
+npm run eval:scripted
+```
+
+`test:performance` runs `test/redaction-performance.test.mjs` and
+`test/agent-performance.test.mjs`; these regressions also run in `npm test`.
+
+The runtime benchmark requires a pristine checkout as its first argument.
+Create and install this baseline once, or use an existing checkout of the same
+commit:
+
+```bash
+git worktree add --detach ../ftp-deploy-mcp-baseline a068aa5c3b1e53caaffc2c7907966ff5a2e9cb0f
+npm --prefix ../ftp-deploy-mcp-baseline ci --ignore-scripts
+npm run benchmark:agents -- ../ftp-deploy-mcp-baseline 200
+```
+
+The optional final argument is the positive iteration count (default 200).
+`benchmark:agents` runs `scripts/benchmark-agent-performance.mjs` with local
+fixtures, checks output equivalence, and reports serialization work and elapsed
+time. Its discovery measurement covers module import, registration and tool
+listing, not the complete stdio handshake. Record the commit, Node.js version,
+operating system and workload alongside timings; repeat comparisons on the
+same machine. On early Node.js 22 releases without module-load instrumentation,
+hook-based checks are skipped and module counts are unavailable; benchmark
+timings still run.
+
+The redaction microbenchmark is opt-in and compares identical fixture outputs
+with the previous implementation. It reports diagnostic medians without timing
+assertions. On POSIX shells:
+
+```bash
+REDACTION_BENCHMARK=1 node --test test/redaction-performance.test.mjs
+```
+
+On PowerShell:
+
+```powershell
+$env:REDACTION_BENCHMARK = '1'
+node --test test/redaction-performance.test.mjs
+Remove-Item Env:REDACTION_BENCHMARK
+```
+
+The tests and benchmarks measure implementation behavior and local execution.
+The [scripted evaluations](./SCRIPTED-EVALUATIONS.md) exercise MCP handlers
+without a model. They do not establish model quality, token savings, provider
+latency or production FTP/SFTP throughput. Use the separate
+[agent evaluation instructions](../evaluations/README.md) for model-based work.

package/docs/ERROR-CONTRACT.fr.md

@@ -0,0 +1,141 @@
+# Contrat d’erreur MCP
+
+[English](./ERROR-CONTRACT.md)
+
+Les dix outils legacy et leurs champs de succès restent stables. Lorsque
+`stateDir` est activé, quatre outils durables supplémentaires sont publiés. Neuf outils legacy
+publient un `oneOf` JSON Schema draft-07 avec deux possibilités strictes :
+l’objet de succès existant et `{error}`. `ftp_read` conserve un succès texte
+sans schéma de sortie ; ses erreurs utilisent néanmoins l’enveloppe validée
+en interne. Les clients doivent lire `isError` et les champs stables ci-dessous
+plutôt qu’analyser le texte traduit.
+
+```json
+{
+  "isError": true,
+  "content": [{ "type": "text", "text": "Erreur : READ_ONLY : …" }],
+  "structuredContent": {
+    "error": {
+      "schema_version": 1,
+      "code": "READ_ONLY",
+      "message": "…",
+      "retryable": false,
+      "request_id": "46d0223a-de77-4f28-bf77-f8b9706a4ecb",
+      "next_action": "fix_config",
+      "effects": "none"
+    }
+  }
+}
+```
+
+`request_id` est un nouvel UUID créé par le serveur pour un appel. Il est
+distinct de l’identifiant de corrélation JSON-RPC et n’identifie pas une
+opération durable. Les erreurs durables ajoutent `plan_id` et `operation_id`
+facultatifs, une phase et des compteurs partiels durables. Ces identifiants
+réfèrent uniquement au workflow journalisé et jamais à la corrélation JSON-RPC.
+
+## Décisions stables et effets observés
+
+Les valeurs acceptées pour `code` sont :
+
+`CONFIG_REQUIRED`, `CONFIG_INVALID`, `SERVER_REQUIRED`, `SERVER_UNKNOWN`,
+`INVALID_ARGUMENT`, `READ_ONLY`, `TRANSPORT_POLICY`, `HOST_KEY_REJECTED`,
+`REMOTE_ROOT_REJECTED`, `PATH_REJECTED`, `NOT_FOUND`, `ALREADY_EXISTS`,
+`TRANSFER_LIMIT`, `TRANSFER_VERIFY`, `TARGET_CHANGED`, `CANCELLED`, `TIMEOUT`,
+`DEPLOY_PARTIAL`, `TRANSPORT_ERROR`, `OUTPUT_LIMIT`, `INTERNAL_ERROR`,
+`SCAN_LIMIT`, `CAPACITY_LIMIT`.
+
+Les outils durables utilisent aussi `DURABLE_STATE_DISABLED`,
+`DURABLE_STATE_BUSY`, `DURABLE_STATE_LIMIT`, `DURABLE_STATE_CORRUPT`,
+`DURABLE_STATE_IO`, `DURABLE_STATE_UNSUPPORTED`, `PLAN_NOT_FOUND`,
+`PLAN_EXPIRED`, `PLAN_STALE`, `PLAN_CONSUMED`, `IDEMPOTENCY_CONFLICT`,
+`CONFIRMATION_DECLINED`, `CONFIRMATION_INVALID`,
+`CLIENT_INTERACTION_UNSUPPORTED`, `STATUS_CHANGED`,
+`RECONCILIATION_REQUIRED`, `ROLLBACK_CONFLICT` et `WORKFLOW_UNSUPPORTED`.
+L’état v1 est refusé avant décodage des plans et exige une réinitialisation hors ligne.
+
+`SCAN_LIMIT` refuse toute la sélection locale avant connexion, avec `effects:none`
+et `next_action:fix_input`. `CAPACITY_LIMIT` refuse l’admission avant préparation,
+avec `effects:none` et `next_action:retry`. Les deux conservent `retryable:false` ;
+voir les [limites de ressources](./RESOURCE-BOUNDS.fr.md).
+
+Les valeurs legacy de `next_action` sont `fix_input`, `fix_config`,
+`select_server`, `inspect_target`, `retry`, `contact_operator` et `none`.
+Les erreurs durables peuvent aussi indiquer `status`, `resume_apply`,
+`resume_rollback`, `offline_recovery` ou `upgrade_client`.
+Les erreurs des outils historiques renvoient prudemment `retryable:false`. Les
+erreurs durables ne renvoient `retryable:true` que pour
+`DURABLE_STATE_BUSY`, `DURABLE_STATE_IO`, `STATUS_CHANGED` et les échecs
+`TIMEOUT` ou `TRANSPORT_ERROR` projetés ; toutes les autres renvoient `false`.
+Ce drapeau guide le client sans jamais autoriser une reprise automatique : il
+faut suivre `next_action`, surtout après un effet `possible` ou `confirmed`.
+
+| `effects` | Signification |
+| --- | --- |
+| `none` | Aucune opération mutatrice n’a été lancée par cet appel. |
+| `possible` | Une mutation a été lancée, sans effet encore confirmé. |
+| `confirmed` | Au moins un effet a été acquitté ; d’autres effets peuvent rester incertains. |
+
+Les effets comprennent les temporaires, leur nettoyage et les écritures
+locales des téléchargements. Une politique distante de lecture seule
+n’interdit pas ces écritures locales. `confirmed` ne signifie pas que toute
+l’opération a réussi ; zéro fichier terminé ne prouve pas l’absence de
+modification. Un échec de fermeture après promotion conserve les effets confirmés.
+
+Les erreurs d’envoi, de téléchargement et de déploiement peuvent inclure les
+champs stricts `partial` : `completed_files`, `completed_bytes`, `failed_files`,
+`total_files` facultatif et `final`. Ce sont des entiers sûrs non négatifs,
+issus des promotions observées et des tentatives de fichier en échec, sans
+analyse du texte. Les octets comptent les fichiers terminés, pas tout le
+trafic réseau ni les temporaires partiellement écrits. `final: false` indique
+un instantané anticipé pendant que le traitement sous-jacent se termine.
+Cet instantané n’est pas révisé ultérieurement dans la réponse.
+
+## Protocole, annulation et limites de sortie
+
+Les arguments rejetés par le schéma d’entrée déclaré d’un outil connu donnent
+`INVALID_ARGUMENT` avant son traitement, sa connexion ou une écriture locale.
+Un refus métier ultérieur peut survenir après connexion. Un outil inconnu renvoie
+une erreur de protocole JSON-RPC `-32602` bornée sans reprendre son nom.
+Les trames mal formées conservent le traitement des erreurs de protocole du SDK.
+
+L’annulation MCP du client interrompt l’opération et le SDK supprime sa réponse :
+le client ne doit pas attendre une enveloppe `CANCELLED`. Les échéances internes
+sont distinctes et peuvent renvoyer `TIMEOUT`. L’annulation native du SDK v2
+traite chaque identifiant de requête valide, dont le nombre `0` et la chaîne vide
+`""`. Une garde du canal, possédée par le point d’entrée, réserve chaque
+identifiant de requête JSON-RPC entrant, toutes méthodes confondues, avant sa
+remise au SDK. Tout doublon actif ferme la connexion avant l’exécution d’un
+second handler, même si sa méthode diffère. L’identifiant d’un appel d’outil
+n’est libéré qu’après le règlement ou l’échec de l’envoi de sa réponse terminale
+et le règlement réel de tous les tours de handler enregistrés, de sa préparation
+et de sa libération, y compris tous les tours legacy d’entrée requise.
+Si l’annulation supprime la réponse, il reste réservé jusqu’à la fermeture de la
+connexion. Des identifiants concurrents distincts, dont `0`, `""`, `1` et `"0"`,
+restent indépendants. Une réponse dont l’envoi a déjà commencé ne peut pas être
+rappelée. L’annulation n’efface pas les effets.
+
+Les résultats d’outils connus sont masqués, bornés puis validés à une seule
+frontière. La limite de 25 000 octets porte sur le `JSON.stringify` UTF-8 du
+résultat complet, texte et données structurées compris, après expansion du
+masquage. Les avertissements de sécurité ont un rôle de rendu interne distinct.
+Des chaînes distantes telles que `Page:` ou `SECURITY WARNING` ne peuvent pas
+acquérir ce rôle. La pagination est reconstruite après réduction des exemples.
+Un repli `OUTPUT_LIMIT` conserve l’UUID, les effets et les compteurs observés.
+
+Les décisions typées précèdent la traduction. Les détails natifs restent des
+données de leur source sous un libellé traduit ; une réponse FTP ambiguë,
+dont le code 550, ne devient pas `NOT_FOUND` d’après son texte. Les secrets
+sont masqués dans le texte libre. Seules les constantes publiques propres au
+schéma et l’UUID créé pour ce résultat sont préservés à leurs chemins
+structurés exacts. Les objets Error, causes, piles, identifiants secrets et
+arguments bruts ne sont pas sérialisés. Les secrets de configuration sont
+collectés en privé avant validation, y compris ceux des entrées rejetées et
+les valeurs ENV résolues. Les diagnostics publics du chargeur utilisent le
+même masque. Un JSON mal formé reçoit un diagnostic générique sans extrait
+du parseur ; aucune extraction fiable de secrets depuis ce contenu n’est
+revendiquée. Les blocs FileZilla rejetés sont identifiés par leur index
+numérique, sans reprise des noms ou champs de protocole non fiables.
+
+Voir les [langues](./LANGUAGES.fr.md), le [modèle de sécurité](./SECURITY-MODEL.fr.md)
+et les [transferts vérifiés](./TRANSFERS.fr.md) pour les autres limites.

package/docs/ERROR-CONTRACT.md

@@ -0,0 +1,137 @@
+# MCP error contract
+
+[Français](./ERROR-CONTRACT.fr.md)
+
+The ten legacy tool names and success field shapes remain stable. When
+`stateDir` is enabled, four durable tools are additionally advertised. Nine legacy tools publish
+a JSON Schema draft-07 `oneOf` with two strict alternatives: the existing
+success object and `{error}`. `ftp_read` retains text-only success and no
+output schema; its errors still use the internally validated envelope.
+Clients should use `isError` and the stable fields below, rather than parse
+the localized human text.
+
+```json
+{
+  "isError": true,
+  "content": [{ "type": "text", "text": "Error: READ_ONLY: …" }],
+  "structuredContent": {
+    "error": {
+      "schema_version": 1,
+      "code": "READ_ONLY",
+      "message": "…",
+      "retryable": false,
+      "request_id": "46d0223a-de77-4f28-bf77-f8b9706a4ecb",
+      "next_action": "fix_config",
+      "effects": "none"
+    }
+  }
+}
+```
+
+`request_id` is a fresh server-generated UUID for one call. It is unrelated to
+the JSON-RPC correlation ID and is not a durable operation identifier. No
+`operation_id`. Durable errors additionally carry nullable `plan_id` and
+`operation_id`, a phase, and durable partial counters. Those identifiers refer
+only to the sealed journal workflow and are never JSON-RPC correlation IDs.
+
+## Stable decisions and effect observations
+
+The accepted `code` values are:
+
+`CONFIG_REQUIRED`, `CONFIG_INVALID`, `SERVER_REQUIRED`, `SERVER_UNKNOWN`,
+`INVALID_ARGUMENT`, `READ_ONLY`, `TRANSPORT_POLICY`, `HOST_KEY_REJECTED`,
+`REMOTE_ROOT_REJECTED`, `PATH_REJECTED`, `NOT_FOUND`, `ALREADY_EXISTS`,
+`TRANSFER_LIMIT`, `TRANSFER_VERIFY`, `TARGET_CHANGED`, `CANCELLED`, `TIMEOUT`,
+`DEPLOY_PARTIAL`, `TRANSPORT_ERROR`, `OUTPUT_LIMIT`, `INTERNAL_ERROR`,
+`SCAN_LIMIT`, `CAPACITY_LIMIT`.
+
+Durable tools also use `DURABLE_STATE_DISABLED`, `DURABLE_STATE_BUSY`,
+`DURABLE_STATE_LIMIT`, `DURABLE_STATE_CORRUPT`, `DURABLE_STATE_IO`,
+`DURABLE_STATE_UNSUPPORTED`, `PLAN_NOT_FOUND`, `PLAN_EXPIRED`, `PLAN_STALE`,
+`PLAN_CONSUMED`, `IDEMPOTENCY_CONFLICT`, `CONFIRMATION_DECLINED`,
+`CONFIRMATION_INVALID`, `CLIENT_INTERACTION_UNSUPPORTED`, `STATUS_CHANGED`,
+`RECONCILIATION_REQUIRED`, `ROLLBACK_CONFLICT`, and `WORKFLOW_UNSUPPORTED`.
+State v1 is rejected before plan decoding and requires offline reinitialization.
+
+`SCAN_LIMIT` refuses the complete local selection before connecting, with
+`effects:none` and `next_action:fix_input`. `CAPACITY_LIMIT` refuses admission
+before preparation, with `effects:none` and `next_action:retry`. Both keep
+`retryable:false`; see [resource limits](./RESOURCE-BOUNDS.md).
+
+The accepted legacy `next_action` values are `fix_input`, `fix_config`,
+`select_server`, `inspect_target`, `retry`, `contact_operator`, and `none`.
+Durable errors can additionally direct `status`, `resume_apply`,
+`resume_rollback`, `offline_recovery`, or `upgrade_client`.
+Legacy-tool errors conservatively return `retryable:false`. Durable errors set
+`retryable:true` only for `DURABLE_STATE_BUSY`, `DURABLE_STATE_IO`,
+`STATUS_CHANGED`, and mapped `TIMEOUT` or `TRANSPORT_ERROR` failures; all other
+durable errors return `false`. The flag is guidance for the caller and never
+authorizes an automatic retry: follow `next_action`, especially after any
+`possible` or `confirmed` effect.
+
+| `effects` | Meaning |
+| --- | --- |
+| `none` | No mutating operation was dispatched by this call. |
+| `possible` | Mutation was dispatched, without a confirmed effect yet. |
+| `confirmed` | At least one effect was acknowledged; further uncertain effects may exist. |
+
+Effects include temporary files, cleanup and local download writes. A remote
+read-only policy does not prohibit local download writes. `confirmed` does
+not mean that the entire operation succeeded, and zero completed files does
+not prove that nothing changed. A transport close failure after promotion
+retains confirmed effects.
+
+Upload, download and deployment errors can include strict `partial` fields:
+`completed_files`, `completed_bytes`, `failed_files`, optional `total_files`,
+and `final`. Counts are safe nonnegative integers from observed promotions
+and failed file attempts, not text parsing. Bytes count completed files;
+they do not represent all network traffic or partially written temporaries.
+`final: false` marks an early snapshot while the underlying worker still
+settles. An early snapshot is not later revised on the wire.
+
+## Protocol, cancellation and output boundaries
+
+Arguments rejected by a known tool's declared input schema produce
+`INVALID_ARGUMENT` before its handler, connection or filesystem write. Later
+business-policy refusals can occur after connection. An unknown tool returns a
+bounded JSON-RPC `-32602` protocol error without echoing its name. Malformed
+protocol frames retain the SDK's protocol-error handling.
+
+MCP peer cancellation aborts the operation, and the SDK suppresses its result;
+clients must not expect a delivered `CANCELLED` envelope. Internal deadlines
+are distinct and may return `TIMEOUT`. SDK v2 cancellation handles every valid
+request ID natively, including numeric `0` and the empty string `""`. An
+entry-owned wire guard reserves every inbound JSON-RPC request ID, across all
+methods, before SDK dispatch. A duplicate active ID closes the connection before
+a second handler runs, including a cross-method duplicate. A tool-call ID is
+released only after both its terminal response send settles or fails and its
+all registered handler-turn workers, preparation and disposal settle, including
+all legacy input-required rounds. If peer cancellation suppresses
+the response, the ID remains reserved until the connection closes. Concurrent
+different IDs, including `0`, `""`, `1` and `"0"`, remain independent. A
+response whose send already started cannot be recalled. Cancellation does not
+undo effects.
+
+Known tool results are redacted, bounded and validated once at the boundary.
+The 25,000-byte limit covers UTF-8 `JSON.stringify` of the complete result,
+including both text and structured data, after redaction expansion. Required
+security notices have a separate trusted rendering role. Remote strings such
+as `Page:` and `SECURITY WARNING` cannot acquire that role. Pagination is
+rebuilt after sample shrinking. An `OUTPUT_LIMIT` fallback preserves request
+UUID, effects and observed partial counters.
+
+Typed decisions precede translation. Native diagnostic details remain source
+data under a localized wrapper; ambiguous FTP responses, including code 550,
+do not become `NOT_FOUND` based on prose. Secrets are masked in free text.
+Only schema-specific public constants and the UUID minted for this result
+are preserved at their exact structured paths. Error objects, causes, stacks,
+credentials and raw arguments are not serialized. Configuration credentials
+are collected privately before validation, including values from rejected
+entries and resolved environment placeholders. Public loader diagnostics use
+the same mask. Malformed JSON receives a generic syntax diagnostic with no
+parser excerpt; no reliable secret extraction from malformed input is claimed.
+Rejected FileZilla blocks are identified by their numeric block index without
+echoing untrusted names or protocol fields.
+
+See [languages](./LANGUAGES.md), the [security model](./SECURITY-MODEL.md)
+and [verified transfers](./TRANSFERS.md) for the remaining operational limits.