ftp-deploy-mcp 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,502 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/logo.svg" width="96" alt="ftp-deploy-mcp logo">
+
+# ftp-deploy-mcp
+
+**The deploy button for AI coding agents.**
+
+Give Claude Code, Claude Desktop, Cursor, Windsurf, Trae, Antigravity, or any
+MCP client a focused way to list, read, upload, download, and deploy files on
+your own FTP, FTPS, and SFTP servers.
+
+The stdio server implements MCP revision `2026-07-28` through the stable
+modular TypeScript SDK v2 and retains the SDK's legacy negotiation path for
+older MCP clients.
+
+*Version française → [README.fr.md](./README.fr.md)*
+
+CLI and MCP language: English by default; use `--lang fr` or `FTP_MCP_LANG=fr`.
+[Language scope and precedence](./docs/LANGUAGES.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)
+[![License: 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)
+[![MCP compatible](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-en.png" width="100%" alt="ftp-deploy-mcp — Controlled deployment for your AI agents; FTP, FTPS, SFTP over MCP stdio">
+
+</div>
+
+Purpose-built deployment controls keep credentials out of tool responses,
+support read-only servers and dry runs, and limit local file access with
+`localRoot`. The repository is covered by an extensive end-to-end suite that
+runs against local FTP and SFTP servers. There is no telemetry.
+
+> **Availability:** install from source today. The npm package has **not been
+> published yet**, so `npx -y ftp-deploy-mcp` is unavailable. The project still
+> lists publication in the Official MCP Registry as pending; registry-based
+> installation is not offered here. GitHub source releases are
+> separate from npm and Official MCP Registry publication. Existing Glama and
+> MCP Index pages are discovery listings, not proof of an installable package.
+> This checkout has version 0.3.1. Find published source versions on
+> [GitHub Releases](https://github.com/alebgl77/ftp-deploy-mcp/releases/latest);
+> the published GitHub release v0.3.0 remains unchanged.
+
+## Documentation
+
+| Document | English | Français |
+|---|---|---|
+| Overview and installation | [README](./README.md) | [README](./README.fr.md) |
+| Changes | [Changelog](./CHANGELOG.md) | [Modifications](./CHANGELOG.fr.md) |
+| Contributing | [Guide](./CONTRIBUTING.md) | [Guide](./CONTRIBUTING.fr.md) |
+| Security policy | [Policy](./SECURITY.md) | [Politique](./SECURITY.fr.md) |
+| Security model | [Model](./docs/SECURITY-MODEL.md) | [Modèle](./docs/SECURITY-MODEL.fr.md) |
+| Release process | [Guide](./docs/RELEASE.md) | [Guide](./docs/RELEASE.fr.md) |
+| Agent evaluation | [Instructions](./evaluations/README.md) | [Instructions](./evaluations/README.fr.md) |
+| Agent performance and client integration | [Guide](./docs/AGENT-PERFORMANCE.md) | [Guide](./docs/AGENT-PERFORMANCE.fr.md) |
+| Scripted MCP conformance | [Guide](./docs/SCRIPTED-EVALUATIONS.md) | [Guide](./docs/SCRIPTED-EVALUATIONS.fr.md) |
+| CLI and MCP languages | [Guide](./docs/LANGUAGES.md) | [Guide](./docs/LANGUAGES.fr.md) |
+| MCP error contract | [Contract](./docs/ERROR-CONTRACT.md) | [Contrat](./docs/ERROR-CONTRACT.fr.md) |
+| Verified staged transfers | [Guide](./docs/TRANSFERS.md) | [Guide](./docs/TRANSFERS.fr.md) |
+| Scan and admission limits | [Limits](./docs/RESOURCE-BOUNDS.md) | [Limites](./docs/RESOURCE-BOUNDS.fr.md) |
+| Durable state storage | [Library](./docs/STATE-STORAGE.md) | [Bibliothèque](./docs/STATE-STORAGE.fr.md) |
+| Durable workflow model | [Model](./docs/WORKFLOW-MODEL.md) | [Modèle](./docs/WORKFLOW-MODEL.fr.md) |
+| MIT license | [Canonical text](./LICENSE) | [Informative translation](./LICENSE.fr.md) |
+
+## Architecture and scenarios
+
+Explore the current and target architecture diagrams and illustrative scenarios
+in the bilingual [interactive HTML guide](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/index.html).
+The guide and its
+[English](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/README.md) / [French](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/site/README.fr.md)
+build instructions are in the repository, outside the npm package. After
+cloning, open `site/index.html` locally and use its language selector.
+
+The README banners were generated with ChatGPT Image. Their
+[provenance and exact prompts](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/assets/provenance/README.md)
+document their illustrative role; they are not a certification.
+
+## First source install
+
+1. Install a supported Node.js version: 22, 24 or 26 (minimum: 22).
+2. Run `git clone https://github.com/alebgl77/ftp-deploy-mcp.git`, then
+   `cd ftp-deploy-mcp`.
+3. Run `npm ci --omit=dev --ignore-scripts`.
+4. Run `npm run setup`, then edit the generated server config: set an absolute
+   `localRoot`, replace credentials, and configure the SFTP host-key pin or the
+   FTP/FTPS safety acknowledgments described below.
+5. Restart the MCP client and try a dry run:
+
+```text
+Call ftp_deploy with:
+{"server":"prod","local_dir":"dist","remote_dir":"/","dry_run":true}
+```
+
+Windows users can run `install.cmd` and macOS/Linux users can run
+`./install.sh` instead of steps 3–4. Review every generated server entry before
+the first connection.
+
+For a tagged version, check out that exact tag before installing. `npm ci` uses
+the sole authoritative `package-lock.json`, with six exact direct pins and the
+reviewed graph. Keep it with the sources. `--ignore-scripts` disables automatic
+dependency lifecycle scripts; setup is a separate, explicit action.
+
+The v0.3.1 source installation asset is named
+`ftp-deploy-mcp-0.3.1-source.tar.gz`: 90 files, including that lockfile. Once its
+publication and checksums are verified, extract it in a fresh directory:
+
+```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
+```
+
+This installation archive excludes repository tests and maintainer scripts;
+GitHub's automatic source ZIP/tar contains the complete repository. The separate
+npm `.tgz` contains 89 files without a lockfile and remains unqualified: an actual
+npm consumer changed ten production dependencies. It provides no locked-install
+guarantee. See the [release guide](./docs/RELEASE.md) for verification and limits.
+
+## Protocol and security matrix
+
+| Protocol | Transport identity | Remote-root behavior | Recommended use |
+|---|---|---|---|
+| **SFTP** | Encrypted. `hostKeySha256` is required unless `allowUnknownHostKey: true` explicitly accepts impersonation risk. | `realpath`/`lstat` checks refuse symlink components and keep operations below `root`. A malicious or changing server can still create a race between validation and use. | Preferred. Pin a fingerprint verified out of band. |
+| **FTPS** | Encrypted when certificate verification succeeds. `insecureTLS: true` also requires `allowInsecure: true` and disables MITM protection. | A client-side sub-root cannot be a reliable anti-symlink jail. `root` other than `/` is refused unless `allowUnsafeRemoteRoot: true`. | Use a dedicated, server-side chrooted account whose visible root is `/`. |
+| **FTP** | Plaintext. Refused unless `allowInsecure: true` accepts interception and credential exposure. | Same limitation as FTPS: the real boundary is the server account/chroot, not lexical client path checks. | Legacy-only, on a trusted network, with a dedicated chrooted account. |
+
+All three protocols also enforce `localRoot` for `ftp_upload`, `ftp_deploy`,
+and `ftp_download`. This limits which local files the MCP server can access.
+
+## What you get
+
+- Ten focused MCP tools for server discovery, testing, listing, reading,
+  uploading, recursive deploys, downloading, creating directories, renaming,
+  and deleting.
+- Multiple named servers in one local configuration.
+- Gitignore-like deploy exclusions, dry-run, and per-server `readOnly` mode.
+- FileZilla import, an interactive setup wizard, and a read-only `doctor`
+  command.
+- Credentials loaded locally from the config, environment variables, or SSH
+  keys and never intentionally returned to the model.
+
+## Server configuration
+
+An explicit configuration path is authoritative:
+
+1. `--config <path>`
+2. `FTP_MCP_CONFIG`, when `--config` is absent
+
+An empty, missing, unreadable, or invalid explicit configuration reports an
+error without falling back to another file. The MCP tools remain available
+to report the configuration problem. `--config` requires a path argument.
+
+Without either selector, the first configuration found wins:
+
+1. `./ftp-servers.json`
+2. `~/.ftp-mcp/servers.json`
+
+The teaching example below is JSON with comments. Real configuration files
+must be strict JSON; start from
+[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
+    }
+  }
+}
+```
+
+Replace the all-`A` fingerprint; it is deliberately non-functional for a real
+host. Use `hostKeySha256` as an array during a controlled key rotation:
+
+```json
+"hostKeySha256": [
+  "SHA256:old_verified_43_character_base64_value_here",
+  "SHA256:new_verified_43_character_base64_value_here"
+]
+```
+
+The illustrative labels above show the shape but are not valid pins. Each real
+entry is exactly `SHA256:` plus 43 characters of unpadded base64.
+
+### Field reference
+
+| Field | Applies to | Meaning |
+|---|---|---|
+| `stateDir` | top level | Optional absolute, normalized durable-state directory, canonically disjoint from every `localRoot`. Enabling it advertises the four durable workflow tools. |
+| `requirePlan` | top level | With `stateDir`, defaults to `true`. Blocks legacy remote mutators except `ftp_deploy` dry runs; `false` retains them under the same persistent alias lock. |
+| `stateLimits` | top level | Optional strict durable quotas for state, backups, plans, operations, plan files/bytes, journal bytes/events, and backup files. |
+| `protocol` | all | Required: `ftp`, `ftps`, or `sftp`. |
+| `host` / `port` / `user` | all | Connection endpoint and account. Default ports are 21, 990 for implicit FTPS, and 22 for SFTP. |
+| `password` | all | Password or `${ENV:NAME}` placeholder. |
+| `privateKeyPath` / `passphrase` | SFTP | SSH private key path and optional passphrase. A leading `~` is expanded. These authenticate the user; they do not verify the server. |
+| `localRoot` | all | Required for upload, deploy, and download. Must resolve to an existing absolute local directory; a leading `~` is supported. Relative and symlink/junction escapes are refused. Relative tool paths resolve inside it, and absolute tool paths must still remain inside it. |
+| `root` | all | Remote root, default `/`. Tool paths are resolved below it. SFTP performs server-side realpath/lstat checks. FTP/FTPS need a server-side chroot for a trustworthy boundary. |
+| `hostKeySha256` | SFTP | Required fingerprint string or non-empty array of pins. Format: `SHA256:<43-character unpadded base64>`. Cannot be combined with `allowUnknownHostKey`. |
+| `allowUnknownHostKey` | SFTP | Emergency compatibility override. `true` accepts an unverified server identity and visibly warns on results. |
+| `readOnly` | all | Blocks upload, deploy, mkdir, rename, and delete. A deploy dry run remains available. |
+| `operationTimeoutMs` | all | Tool deadline including queue and connection time, default 120000 ms. Integer from 100 to 3600000. Native transport timeouts also apply. |
+| `maxTransferBytes` | all | Maximum actual bytes per file, default 268435456 (256 MiB), maximum 1099511627776 (1 TiB). Positive safe integer. |
+| `maxDeployFiles` | all | Maximum selected files per deploy, default 10000, maximum 100000. Positive safe integer; does not bound the full directory scan. |
+| `maxScanEntries` | all | Visited local entries per deploy, including the root, excluded entries and links. Default 100000, maximum 1000000; positive safe integer. |
+| `maxScanDepth` | all | Inclusive directory depth below the root (depth 0). Default 64, maximum 256; positive safe integer. |
+| `maxDeployBytes` | all | Maximum cumulative source bytes per deploy, default 1073741824 (1 GiB), maximum 1099511627776 (1 TiB). Failed attempts retain their reservation. |
+| `implicitTLS` | FTPS | Uses implicit TLS, normally on port 990. |
+| `insecureTLS` | FTPS | Disables certificate verification. Requires `allowInsecure: true`. |
+| `allowInsecure` | FTP/FTPS | Explicitly accepts plaintext FTP or unverified FTPS. It does not make the connection secure. |
+| `allowUnsafeRemoteRoot` | FTP/FTPS | Allows a `root` other than `/` despite the unresolved symlink-escape risk. Use only when the server-side account boundary is understood. |
+
+Any string can contain `${ENV:VARIABLE_NAME}`. Missing variables produce a
+named configuration error.
+
+### Verify an SFTP fingerprint out of band
+
+Do not trust a fingerprint obtained only through the connection you are about
+to verify.
+
+1. Obtain the SHA-256 host-key fingerprint from the hosting provider's
+   authenticated control panel or support channel, or from an administrator
+   through a separately authenticated channel.
+2. If you administer the host, use its trusted console to run a command such as
+   `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256`.
+3. Compare the complete `SHA256:...` value before putting it in
+   `hostKeySha256`. `ssh-keyscan` may collect a candidate key, but by itself it
+   does not authenticate that key.
+
+For rotation, verify the new fingerprint out of band, temporarily configure
+both old and new pins, rotate the server key, confirm connections use the
+expected key, then remove the old pin. Do not use `allowUnknownHostKey` as a
+rotation shortcut.
+
+## Tool reference
+
+All remote path arguments are relative to the configured remote `root`. The
+`server` parameter is optional when `defaultServer` is set or only one server
+exists.
+
+| Tool | Main parameters | Purpose |
+|---|---|---|
+| `ftp_list_servers` | none | Show server metadata and active safety warnings, never passwords. |
+| `ftp_test` | `server?` | Connect and list the visible root. |
+| `ftp_list` | `server?`, `path?`, `limit?`, `offset?` | List a remote directory. `limit` defaults to 50 (1–200); `offset` defaults to 0. |
+| `ftp_read` | `server?`, `path`, `max_bytes?` | Read a bounded text file; binary data is refused. |
+| `ftp_upload` | `server?`, `local_path`, `remote_path?` | Upload one file from `localRoot`. |
+| `ftp_deploy` | `server?`, `local_dir`, `remote_dir?`, `include?`, `exclude?`, `dry_run?` | Recursively deploy a directory from `localRoot`. |
+| `ftp_download` | `server?`, `remote_path`, `local_path`, `overwrite?` | Download into `localRoot`. |
+| `ftp_mkdir` | `server?`, `path` | Create a remote directory recursively. |
+| `ftp_rename` | `server?`, `from_path`, `to_path` | Rename or move. |
+| `ftp_delete` | `server?`, `path`, `recursive?` | Delete a file or, with explicit recursion, a directory. |
+| `ftp_plan_deploy` | `server?`, `local_dir`, `remote_dir?`, `include?`, `exclude?`, `ttl_seconds?` | Publish an immutable, expiring durable plan. Available only with `stateDir`. |
+| `ftp_apply_deploy` | `plan_id`, `idempotency_key`, `resume?` | Confirm, associate, and explicitly resume a durable apply. |
+| `ftp_deploy_status` | exactly one of `plan_id` / `operation_id`, `offset?`, `limit?`, `if_journal_seq?` | Read a lock-free, paginated durable snapshot without network access or state writes. |
+| `ftp_rollback_deploy` | `operation_id`, `resume?` | Confirm and explicitly resume conservative rollback of durably acknowledged files. |
+
+### Durable workflow guarantees
+
+The durable tools require the official MCP `input_required` confirmation flow;
+there is no boolean fallback. Signed request state binds the session, method,
+plan digest, operation, idempotency-key hash, resume choice, journal sequence,
+and expiry. Declined, invalid, expired, or unsupported interaction has no remote
+effect. Association alone is status-only; any nonterminal remote mutation
+requires `resume:true`.
+
+The guarantee level is `observable_state_reconciled`: per-file replacement is
+server-dependent, multi-file atomicity and exactly-once execution are false,
+and rollback covers only durably acknowledged files. SFTP supports replacement
+plus new files under existing canonical parents; FTP/FTPS supports replacement
+of existing regular files only. Durable execution never creates parents, purges
+remote extras, automatically rolls back, or rolls back `SATISFIED_UNOWNED`.
+
+Cooperating processes sharing one canonical `stateDir` serialize the exact
+server alias before adapter construction. This is not a distributed remote lock
+and does not coordinate different aliases or state directories. Overlapping
+writable aliases, alias renames, mixed-binary upgrades, and a process killed
+while holding a persistent lock require operator care: quiesce upgrades and
+recover stale locks offline. External writers and ABA changes remain outside
+the observable identity guarantee.
+
+### Verified staged promotion
+
+Uploads and deploys write to an unpredictable sibling temporary, verify its
+actual byte count and SHA256 against the local source, then promote it with one
+rename. A verification or rename failure never triggers deletion of the final
+target or a direct-overwrite fallback. Downloads verify an exclusive local
+temporary, synchronize and close it, then promote the complete file. The
+default `overwrite:false` uses a hard link to avoid clobbering a file that
+appeared meanwhile; filesystems without hard-link support fail closed.
+
+Local and SFTP replacements preserve an existing regular target's permission
+bits (0777); FTP/FTPS cannot portably preserve permissions, so account creation
+defaults, umask and ACL policy need to suit the destination. Rename behavior
+depends on the server and filesystem. Legacy upload/deploy does not promise
+universal atomic replacement, a site transaction, or rollback. Readback adds network traffic.
+See [transfer guarantees, limits and cleanup](./docs/TRANSFERS.md).
+
+### Execution, cancellation, and contention
+
+Within one Node process, upload, deploy, mkdir, rename, and delete run in FIFO
+order for the same normalized protocol, hostname, port, and username. Server
+aliases and roots share that lock. Downloads serialize by canonical local
+destination, including across servers. Read-only remote operations can overlap.
+
+MCP cancellation and deadlines close active transports and stop subsequent
+deploy files. Errors identify `CANCELLED` or `TIMEOUT`; `TARGET_BUSY` indicates
+waiting for another operation. A timed-out call can return before an underlying
+operation settles, but its lock remains owned until settlement and cleanup.
+No uncertain mutation is retried automatically. Inspect partial remote/local
+state before retrying; legacy mutation calls are not transactional deployment
+and provide no rollback.
+
+Internal preparation is single-use and limited to 10 seconds without extending
+the overall operation deadline. Admission remains held until the actual work
+and cleanup settle. A prepared context is released once, including when it
+arrives after cancellation; the handler is not called after preparation is
+cancelled or expires. Preparation callbacks themselves may act. Durable tools
+use the same settlement discipline. See the
+[resource limits](./docs/RESOURCE-BOUNDS.md).
+
+Progress notifications are sent only when the caller supplies a progress
+token, with increasing counters and no paths or credential text. Locks do not
+coordinate other Node processes, DNS aliases, other accounts, or external
+clients on the same host.
+
+### Response compatibility, pagination, and annotations
+
+`ftp_list` returns one page instead of an unbounded directory listing. Its
+successful response includes `total`, `count`, `offset`, `limit`, `has_more`,
+and `next_offset` pagination fields. For example, a request with
+`{"server":"prod","path":"/assets","limit":2,"offset":2}` may include the
+following intentionally non-exhaustive excerpt. It omits the required
+top-level `server`, `path`, and `security_warning` fields and the required
+per-entry `size_bytes` and `modified_at` fields:
+
+```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
+  }
+}
+```
+
+The existing human-readable `content` text is retained for compatibility.
+On success, every tool except `ftp_read` also advertises an MCP
+`outputSchema` and returns matching `structuredContent`; `ftp_read` remains a
+bounded text-only tool on success. Each of the nine structured schemas accepts
+either its strict success shape or a strict `{error}` envelope. Tool execution
+errors return `isError: true` with localized text and structured code, request UUID,
+effect observations and safe-retry guidance. Unknown tools remain protocol errors.
+See the [error contract](./docs/ERROR-CONTRACT.md).
+
+The process admits at most 64 tool calls, including workers still cleaning up
+after cancellation. Excess calls return `CAPACITY_LIMIT`. Local deployment scans
+are asynchronous and separately bounded; see [resource limits](./docs/RESOURCE-BOUNDS.md)
+for exact counting, `SCAN_LIMIT` and corrected custom exclusion behavior.
+
+All tools publish MCP annotations describing read-only, destructive,
+idempotent, and open-world behavior. These annotations are client hints, not a
+security boundary; enforce access with server credentials, `readOnly`,
+`localRoot`, and the protocol controls described above. `ftp_deploy` structured
+results contain a summary and bounded samples, not exhaustive file lists.
+
+`ftp_deploy` is not a transaction. If one or more transfers fail, the tool
+returns an MCP error with a partial-deployment summary; files already promoted
+before the failure are not rolled back.
+
+Default deploy exclusions include `node_modules`, `.git`, environment files,
+logs, OS metadata, `ftp-servers.json`, and `.ftp-mcp` content at any depth.
+The reserved `.ftp-mcp-*.tmp` basename is always excluded, even if an explicit
+`include` pattern matches it, so deploy cannot select a partial download temporary.
+
+## Client setup
+
+`npm run setup` detects supported clients, creates timestamped backups before
+changing existing client configuration, and prints a block for UI-only clients.
+To wire a client manually, replace the path below with the absolute path to
+this checkout:
+
+```json
+{
+  "mcpServers": {
+    "ftp": {
+      "command": "node",
+      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
+    }
+  }
+}
+```
+
+Common locations include `.mcp.json` for Claude Code,
+`~/.cursor/mcp.json` for Cursor, and
+`~/.codeium/windsurf/mcp_config.json` for Windsurf. Claude Desktop and other
+clients accept the same command/arguments structure through their MCP settings.
+
+After the first npm release is verified, this source command can be replaced
+with `npx -y ftp-deploy-mcp`. It is intentionally not presented as a working
+installation method today.
+
+## FileZilla import and diagnostics
+
+```bash
+node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json
+npm run doctor
+```
+
+Imported passwords may be decoded into plaintext. Keep the output outside
+version control, restrict its permissions, add `localRoot`, and review every
+insecure-transport or FTP/FTPS remote-root warning before connecting.
+`doctor` is read-only and reports configuration and client wiring without
+printing passwords.
+
+## Migrating from v0.1 to v0.2
+
+GitHub v0.3.0 is published. This source checkout has version 0.3.1. The npm
+package remains unpublished, and the project still lists Official MCP Registry
+publication as pending. The steps below apply to the source installation and
+do not announce an npm release.
+
+1. Add an absolute `localRoot` to every server used by upload, deploy, or
+   download.
+2. For every SFTP server, add an out-of-band-verified `hostKeySha256`. Use
+   `allowUnknownHostKey: true` only as a temporary, explicit risk acceptance;
+   do not configure both fields.
+3. For FTP/FTPS, prefer a dedicated server-side chroot whose visible root is
+   `/` and set `root` to `/`. A non-root client path now requires
+   `allowUnsafeRemoteRoot: true` and remains unsafe against server-side
+   symlinks.
+4. Treat a failed `ftp_deploy` as a partial deployment: inspect its summary and
+   reconcile the remote tree before retrying.
+5. Re-run `npm run setup` or update the MCP client command to this checkout,
+   then run `npm run doctor` and a dry run.
+
+Atomic replacement for newly written sensitive configuration is checked by the
+release tests; a version number alone does not establish that guarantee. See
+[docs/RELEASE.md](./docs/RELEASE.md) for the qualification and publication steps.
+
+## Security and limitations
+
+- The strongest FTP/FTPS boundary is the server's own account isolation or
+  chroot. Client-side normalization rejects obvious traversal, but FTP lacks
+  portable `REALPATH`/`LSTAT` primitives and cannot prove that a server-side
+  symlink stays inside a configured sub-root.
+- SFTP verifies the host pin and rejects symlink components using
+  `realpath`/`lstat`. A server controlled by an attacker can still change
+  filesystem state between checks and operations.
+- `readOnly` reduces accidental writes through this MCP server; it is not a
+  substitute for read-only credentials enforced by the remote server.
+- FTP, `insecureTLS`, `allowUnknownHostKey`, and
+  `allowUnsafeRemoteRoot` are explicit risk acceptances, not security features.
+
+Read the full [security model](./docs/SECURITY-MODEL.md) and
+[private disclosure policy](./SECURITY.md).
+
+## Development
+
+```bash
+npm test
+npm run eval:scripted
+node src/index.js --version
+node src/index.js --help
+```
+
+The test suite uses local FTP and SFTP servers and does not require an external
+network. Contributions are welcome; see
+[CONTRIBUTING.md](./CONTRIBUTING.md). Maintainers should use the
+[release guide](./docs/RELEASE.md). A reproducible, externally hosted read-only
+agent evaluation is documented in [evaluations/README.md](./evaluations/README.md).
+
+From a source checkout, `npm run eval:scripted` runs 43 cases in both languages
+with a memory adapter and real MCP handlers. See the
+[scripted conformance guide](./docs/SCRIPTED-EVALUATIONS.md) for reports and limits;
+this command does not evaluate a model.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SECURITY.fr.md

@@ -0,0 +1,99 @@
+# Politique de sécurité
+
+[English](./SECURITY.md) | **Français**
+
+## Versions prises en charge
+
+Le projet n'a pas encore achevé sa première publication sur npm ou le registre
+MCP. Les correctifs de sécurité visent la branche source actuelle et la dernière
+version 0.x étiquetée. Pour les anciens tags 0.x, une mise à niveau peut être
+demandée plutôt qu'un rétroportage.
+
+| Version | Prise en charge |
+|---|---|
+| Sources actuelles / dernier tag 0.x | Prise en charge |
+| Anciens tags 0.x | Selon les possibilités |
+
+## Signaler une vulnérabilité en privé
+
+**N'ouvrez pas d'issue, de discussion ou de pull request GitHub publique pour
+une vulnérabilité présumée.**
+
+Utilisez le signalement privé de vulnérabilités de GitHub : ouvrez la
+[page Security du dépôt](https://github.com/alebgl77/ftp-deploy-mcp/security),
+choisissez **Report a vulnerability**, puis indiquez :
+
+- le commit ou la version et le protocole concernés ;
+- les étapes minimales de reproduction et la configuration serveur requise ;
+- les accès ou divulgations attendus et observés ;
+- l'impact, notamment les fichiers locaux ou distants et les identifiants exposés ;
+- toute correction suggérée ou échéance de divulgation.
+
+N'incluez pas d'identifiants actifs ni de clés privées. Utilisez des comptes de
+test jetables et masquez les informations sensibles dans les journaux. Si le
+signalement privé est indisponible, ouvrez une issue publique sans aucun détail
+sur la vulnérabilité et demandez au mainteneur d'établir un canal privé.
+
+L'objectif est d'accuser réception d'un rapport complet sous 72 heures, puis
+de confirmer son périmètre, coordonner un correctif et ses tests, et convenir
+d'une date de divulgation. Il s'agit d'un objectif de réponse, sans promesse
+de prime ni de délai de résolution.
+
+## Périmètre
+
+- Accès hors de `localRoot` par traversée, lien symbolique, jonction ou
+  traitement de la destination d'un téléchargement.
+- Accès SFTP hors de `root`, contournement de la vérification de clé d'hôte ou
+  traitement non sûr d'une rotation de clé d'hôte vérifiée.
+- Connexion FTP/FTPS à un confinement côté client dont la racine n'est pas `/`
+  sans acceptation explicite via `allowUnsafeRemoteRoot`.
+- FTP en clair ou FTPS non vérifié sans acceptation explicite via `allowInsecure`.
+- Identifiants ou clés exposés dans les résultats d'outils, diagnostics,
+  journaux ou erreurs.
+- Contournement de `readOnly` ou des protections d'opérations destructives,
+  ou succès annoncé à tort après un déploiement partiel.
+- Corruption ou remplacement non sûr d'une configuration serveur ou client MCP.
+- Archive de publication acceptée malgré une modification des sources livrées,
+  du manifeste de dépendances ou du verrouillage source, ou malgré un modificateur de
+  dépendances ou un hook d'installation non autorisé.
+
+Les problèmes qui reposent sur un serveur FTP malveillant utilisant des liens
+symboliques hors d'une sous-racine configurée côté client sont importants,
+mais **leur prévention n'est pas garantie** : FTP/FTPS exigent une frontière
+de compte/chroot côté serveur. De même, les contrôles SFTP `realpath`/`lstat`
+réduisent les sorties par lien symbolique sans pouvoir supprimer toutes les
+courses sur un serveur malveillant. Ces limites sont décrites dans le
+[modèle de sécurité](./docs/SECURITY-MODEL.fr.md).
+
+## Intégrité des dépendances et de la publication
+
+Les six dépendances directes de production utilisent des versions exactes.
+`package-lock.json` est l'unique référence du graphe source, livrée dans
+l'archive d'installation source de 90 fichiers. Utilisez
+`npm ci --omit=dev --ignore-scripts` après extraction et conservez ce fichier.
+Toute modification exige une revue du graphe complet, de ses URL et intégrités,
+puis les contrôles du [guide de publication](./docs/RELEASE.fr.md).
+
+Le paquet npm de 89 fichiers ne contient aucun verrouillage et reste non qualifié.
+Une installation réelle a changé dix dépendances de production. Les workflows
+refusent toute dérive du graphe installé avant publication npm ou MCP ; une preuve
+de type source ne peut pas autoriser npm. Un éventuel graphe npm conforme ne vaut
+que pour l'environnement et la date testés, sans garantir les installations futures.
+
+Un audit de dépendances réussi vaut pour ce graphe à cette date ; il ne garantit
+pas l'absence d'avis futurs et ne certifie pas un usage en production. Signalez
+en privé les contournements du validateur d'archive selon la procédure ci-dessus.
+Une release GitHub ne prouve pas la disponibilité sur npm ou le registre MCP
+officiel.
+
+## Consignes de recherche
+
+- Testez uniquement les systèmes et comptes qui vous appartiennent ou que
+  vous êtes autorisé à évaluer.
+- N'accédez pas aux données d'autres utilisateurs, ne dégradez pas le service,
+  ne maintenez pas d'accès persistant et n'utilisez pas d'ingénierie sociale.
+- Arrêtez-vous une fois le problème démontré et transmettez les détails en privé.
+- Laissez au projet un délai raisonnable pour corriger le problème avant sa divulgation.
+
+Les recherches de bonne foi respectant ces consignes sont bienvenues, mais ce
+document n'autorise pas les tests contre des services FTP/SFTP tiers.