<div align="center">

<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:** version **0.3.2** is published on
> [npm](https://www.npmjs.com/package/ftp-deploy-mcp/v/0.3.2) and the
> [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alebgl77%2Fftp-deploy-mcp/versions/0.3.2).
> Use `npx -y ftp-deploy-mcp@0.3.2` for that version. The
> [GitHub release](https://github.com/alebgl77/ftp-deploy-mcp/releases/tag/v0.3.2)
> is a separate source distribution; `main` can include later changes.
> Registry visibility establishes availability, not locked dependency resolution
> or qualification of a different commit. See the [release guide](./docs/RELEASE.md).

**Deployment modes:** the ten base tools provide controlled transfers and dry runs.
Enabling `stateDir` adds four durable tools with MCP confirmation, explicit resume
and conservative rollback of acknowledged changes. These guarantees belong to
the optional durable workflow; legacy `ftp_deploy` has no transaction or rollback.

## 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

<div align="center">

<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/architecture-overview.png" width="100%" alt="Architecture overview: MCP client routes locally confined FTP, FTPS, and SFTP transfers through ftp-deploy-mcp.">

</div>

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.

### Animated verified deployment flow

<div align="center">

<img src="https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/verified-deployment-flow.gif" width="100%" alt="Animated verified deployment flow: scan, plan, approve, transfer, verify, and promote with a rollback safety path.">

</div>

For reduced motion, view the [static completed-state image](https://raw.githubusercontent.com/alebgl77/ftp-deploy-mcp/main/assets/verified-deployment-flow.png).
See the [visual system provenance and generation notes](https://github.com/alebgl77/ftp-deploy-mcp/blob/main/assets/provenance/visual-system-2026-10-17.md).

The visual direction was explored with ChatGPT Image; the final README assets
are rendered deterministically. 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.

Once published, the v0.3.2 source installation asset is named
`ftp-deploy-mcp-0.3.2-source.tar.gz`: 90 files, including that lockfile. Verify
its publication and checksums before extracting it in a fresh directory:

```bash
tar --ignore-zeros -xzf ftp-deploy-mcp-0.3.2-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 follows npm dependency
resolution. 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.
- Four additional durable-workflow tools when `stateDir` is configured;
  confirmation and rollback follow the [documented bounds](#durable-workflow-guarantees).
- 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.

The published npm package can instead be launched with
`npx -y ftp-deploy-mcp@0.3.2`. Verify the exact version before updating;
pinning it does not also freeze npm's transitive dependency resolution.

## 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

The [availability links above](#ftp-deploy-mcp) identify published version 0.3.2.
The migration steps below describe the security changes introduced after v0.1;
they do not require republishing or moving an existing release tag.

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
through the real SDK client and handlers, with an in-memory remote adapter:
86 scripted server-conformance results. See the
[scripted conformance guide](./docs/SCRIPTED-EVALUATIONS.md) for reports and limits;
this command does not evaluate a model or replace the separate real-transport tests.

## License

MIT — see [LICENSE](./LICENSE).

## Author

Built and maintained by **[Alexandre Beguel](https://github.com/alebgl77)**, Agentic AI Architect and external CAIO based in Paris. He works on production GenAI, LLMOps, LLM FinOps and evidence-first AI governance. [beguel.com](https://beguel.com/) · [LinkedIn](https://www.linkedin.com/in/beguel/) · [Profile in English, French and Spanish](https://alebgl77.github.io/)