DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

ftrans-cn /

ftrans-cn/ft-ftp-mcp-stdio

Topic repository only

This plugin has no description yet.

★ 2 Stars1 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@e0bd764c

FT FTP MCP

FT FTP MCP 是一个通过 stdio 运行的本地 MCP Server,让支持 MCP 的 AI Agent 在受控范围内访问 FTP/SFTP 服务器。工程名、Python 包入口和 MCP 注册名统一使用 ft-ftp-mcp-stdio。

  • 当前版本:0.3.1
  • 支持的正式分发环境:Windows 10/11 x64 + Python 3.12.x
  • 协议:FTP、SFTP
  • 许可:MIT License

它提供服务器发现、目录浏览、文件搜索、上传下载、文本预览、目录批量传输及远程文件维护等 14 个 MCP 工具。服务不监听本地网络端口;每次远端工具调用独立建立并关闭 FTP/SFTP 连接。

核心特性

  • 本地 stdio 服务:由 MCP 客户端按需启动,不开放 HTTP/TCP 服务端口。
  • FTP 与 SFTP:支持密码认证、SFTP 私钥认证和主机密钥校验。
  • 凭据不进入模型上下文:密码或私钥口令存入操作系统凭据管理器,也可由环境变量注入。
  • 虚拟路径边界:Agent 只使用以 / 开头的虚拟路径;/ 映射到必填的服务器 root,真实 root 不进入工具结果。
  • 写操作保护:支持只读模式;覆盖、移动和删除均有明确门控。
  • 大文件友好:下载内容落入本机暂存目录,工具仅返回路径、元数据和 SHA-256。
  • 上传完整性护栏:上传逐文件执行大小限制,并通过同目录临时对象提交;下载校验已知远端大小并清理失败的部分文件。
  • 中文环境兼容:FTP 文件名支持 UTF-8、GBK 和自动回退;文本预览支持 BOM、UTF-8 与 GBK。
  • 可诊断、可审计:提供只读 doctor 检查和不含凭据、文件内容的本地 JSONL 使用日志。

工具一览

工具 用途 关键保护
list_servers 列出已配置的逻辑服务器 只读本地配置,不连接远端、不读取凭据或触发 TOFU
test_connection 测试连接、认证与账号访问范围 不执行文件操作
list_dir 列出指定目录的下一层内容 最多返回 500 项
search_files 按名称通配符递归搜索 深度最多 5 层,最多返回 50 项
get_file_info 获取文件或目录元信息 仅查询
download_file 下载单个文件到本机暂存目录 校验大小并返回 SHA-256
upload_file 上传单个本机文件 默认拒绝覆盖,覆盖需 overwrite=true
make_dir 递归创建目录 幂等;只读服务器拒绝
read_text_preview 预览文本或 CSV 的开头部分 默认 100 KB,最大 1 MB,按完整行截断
download_dir 递归下载目录 跳过链接并逐项报告失败,不设置客户端数量或大小上限
upload_dir 递归上传目录 默认不覆盖,跳过软链接
rename 在同一目录中重命名 目标存在时拒绝
move 移动文件或目录 源与目标均进行路径边界检查
delete 删除文件或空目录 必须显式传入 confirm=true

除无业务输入的 list_servers 外,所有远端操作工具都接受可选的 server 参数;省略时使用 default_server。当前行为、返回结构和已知契约缺口以 当前 Spec 基线 为准;机器可读接口以 正式 MCP 工具 Schema 为准。

工作方式

flowchart LR
    U[用户] --> A[支持 MCP 的 AI Agent]
    A <-->|JSON-RPC / stdio| M[ft-ftp-mcp-stdio]
    M -->|FTP 或 SFTP| S[文件服务器]
    M --> C[本地配置与系统凭据管理器]
    M --> L[暂存目录与使用日志]

MCP 客户端配置只负责启动本地 Server;FTP/SFTP 主机、账号和边界策略保存在 ~/.ft-ftp-mcp/config.json;密码或私钥口令不写入该配置文件。

快速开始

DeepSeek Harness 用户参阅 FT FTP MCP 安装说明。Codex / WorkBuddy 用户按下文完成独立 MCP 安装与手动配置;详细验证结果见 验证记录。

1. 安装发布包

正式分发包为:

ft-ftp-mcp-stdio-offline-0.3.1-py312-win64.zip

请从项目正式分发渠道获取安装包,并在安装前使用包内 SHA256SUMS.txt 校验文件完整性;版本产物信息见 发布说明。

使用前请安装 64 位 Python 3.12.x。解压离线包后运行:

install.bat

安装脚本无需管理员权限,并会:

  1. 校验 Python 版本;
  2. 在 %LOCALAPPDATA%\ft-ftp-mcp\venv 创建独立虚拟环境;
  3. 从包内 wheels\ 离线安装本项目和全部依赖;
  4. 在 %LOCALAPPDATA%\ft-ftp-mcp\templates 生成包含本机真实路径的 Codex 与 WorkBuddy 配置模板。

安装过程使用 --no-index,不会访问 PyPI。

2. 配置服务器

运行交互式配置向导:

& "$env:LOCALAPPDATA\ft-ftp-mcp\venv\Scripts\python.exe" -m ft_ftp_mcp_stdio setup

向导支持添加、修改和删除服务器,切换默认服务器,设置日志开关并列出当前配置。新增或修改服务器时会先执行真实连接测试,成功后再原子写入配置和凭据。

3. 注册 MCP Server

安装器生成的最终模板位于:

%LOCALAPPDATA%\ft-ftp-mcp\templates\codex-config.toml
%LOCALAPPDATA%\ft-ftp-mcp\templates\workbuddy-mcp.json

将对应片段合并到客户端配置中,保留客户端原有的其他 MCP Server。

Codex 配置示例(~/.codex/config.toml):

[mcp_servers.ft-ftp-mcp-stdio]
command = "C:/Users/<用户名>/AppData/Local/ft-ftp-mcp/venv/Scripts/python.exe"
args = ["-m", "ft_ftp_mcp_stdio"]

[mcp_servers.ft-ftp-mcp-stdio.env]
FASTMCP_SHOW_SERVER_BANNER = "false"
PYTHONUTF8 = "1"

WorkBuddy 配置示例(~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "ft-ftp-mcp-stdio": {
      "command": "C:/Users/<用户名>/AppData/Local/ft-ftp-mcp/venv/Scripts/python.exe",
      "args": ["-m", "ft_ftp_mcp_stdio"],
      "env": {
        "FASTMCP_SHOW_SERVER_BANNER": "false",
        "PYTHONUTF8": "1"
      }
    }
  }
}

WorkBuddy 需要在连接器管理中信任该 Server;此后若 command、args 或 env 发生变化,原信任会失效,需要重新信任。配置完成后完全退出并重新打开客户端。

4. 验证

先运行只读诊断:

& "$env:LOCALAPPDATA\ft-ftp-mcp\venv\Scripts\python.exe" -m ft_ftp_mcp_stdio doctor

随后在 Agent 对话中指定服务器别名,例如:

测试一下 ftp1 的连接。

预期 Agent 调用 test_connection,只返回服务器 alias、协议和只读状态,不暴露地址、账号、真实 root 或凭据来源。

配置文件

默认位置:~/.ft-ftp-mcp/config.json。可通过环境变量 FT_FTP_MCP_CONFIG 指定其他路径。

最小完整示例:

{
  "version": 2,
  "default_server": "ftp1",
  "staging_dir": "~/.ft-ftp-mcp/staging",
  "log_usage": true,
  "servers": [
    {
      "alias": "ftp1",
      "protocol": "ftp",
      "host": "ftp.example.com",
      "port": 21,
      "username": "your_user",
      "root": "/",
      "description": "示例只读 FTP 服务器",
      "readOnly": true,
      "max_file_size_bytes": 2147483648,
      "encoding": "auto",
      "credential_env": null,
      "key_path": null,
      "host_key_fingerprint": null
    }
  ]
}

重要配置项:

字段 说明
default_server 工具未传 server 时使用的服务器别名
root 必填的真实服务器根;Agent 的虚拟 / 映射到此处,为 / 时隔离依赖服务端账号权限或 chroot
description 可选的非敏感服务器说明,供 list_servers 和 Agent 选择服务器
readOnly 默认 true;只有显式设为 false 才启用写操作,并在连接前检查
encoding FTP 文件名编码:auto、utf-8 或 gbk
max_file_size_bytes 每个上传文件的大小上限,默认 2 GiB;0 表示不限制,不限制下载
credential_env 可选的凭据环境变量名,适合 CI 或企业密管注入
key_path SFTP 私钥路径;为空时使用密码认证
host_key_fingerprint 可选的 SFTP 主机 SHA-256 指纹强校验
log_usage 是否记录本地 JSONL 使用日志,默认开启

远程路径统一使用以 / 开头的虚拟绝对路径;本机 local_path 必须使用本地绝对路径。完整规则见 配置文件规范。

凭据管理

密码和 SFTP 私钥口令默认存入操作系统凭据管理器,服务名为 ft-ftp-mcp-stdio,条目键为服务器别名。

python -m ft_ftp_mcp_stdio cred add <alias>
python -m ft_ftp_mcp_stdio cred list
python -m ft_ftp_mcp_stdio cred remove <alias>

发布包用户应将上述 python 替换为 %LOCALAPPDATA%\ft-ftp-mcp\venv\Scripts\python.exe 的完整路径。

凭据解析时优先读取系统凭据管理器;未找到且配置了 credential_env 时,再读取对应环境变量。SFTP 设置 key_path 后使用私钥认证,钥匙串或环境变量中的值作为可选的私钥口令。

运维命令

# 交互式维护服务器配置
python -m ft_ftp_mcp_stdio setup

# 检查运行环境、配置、凭据、网络和协议登录
python -m ft_ftp_mcp_stdio doctor

# 只诊断指定服务器
python -m ft_ftp_mcp_stdio doctor --server <alias>

doctor 是只读检查,不修改配置、凭据或 known_hosts。任一检查项为 FAIL 时退出码为 1,全部通过时为 0。更多行为与退出码见 命令行工具手册。

本地文件位置

路径 内容
~/.ft-ftp-mcp/config.json FTP/SFTP 服务器配置
~/.ft-ftp-mcp/config.json.bak.* 配置向导生成的历史备份
~/.ft-ftp-mcp/known_hosts SFTP TOFU 主机指纹记录
~/.ft-ftp-mcp/staging/ 下载文件和目录的本机暂存区
~/.ft-ftp-mcp/logs/usage-YYYYMMDD.jsonl 按日本地使用日志

使用日志只记录时间、工具名、服务器别名、路径参数、状态和耗时,不记录凭据或文件内容。暂存目录当前不会自动清理,请自行管理磁盘空间。

从源码开发

要求:Python >=3.12,<3.13、uv。

git clone <repository-url>
cd ft-ftp-mcp-stdio
uv sync

常用命令:

# 启动交互式配置向导
uv run ft-ftp-mcp-stdio setup

# 启动只读诊断
uv run ft-ftp-mcp-stdio doctor

# 启动 MCP stdio Server(通常由 MCP 客户端调用)
uv run ft-ftp-mcp-stdio

# 测试、代码检查和类型检查
uv run pytest
uv run ruff check .
uv run mypy src tests scripts

源码环境接入 MCP 客户端时,将 command 指向项目 .venv 中 Python 的绝对路径,args 使用 ['-m', 'ft_ftp_mcp_stdio']。stdio 模式的 stdout 专用于 JSON-RPC,不应向其中输出调试信息。

测试默认不访问真实 FTP/SFTP 服务。--live 测试仅供明确授权的隔离环境使用:它依赖 v2 配置中的 ftp1、sftp1、sftp-key-nopass-v2、sftp-key-pass-v2,并只在记录过初始状态的 /mcp_* 目录中写入和清理数据。确认环境满足 live 测试代码中的前提后,才可显式运行:

uv run pytest --live

不要在未授权的生产环境中运行 live 测试。

项目结构

ft-ftp-mcp-stdio/
├── src/ft_ftp_mcp_stdio/   # MCP 入口、服务层、配置、凭据与协议驱动
├── tests/                  # 单元、Schema、CLI、服务层和可选 live 测试
├── docs/                   # 产品、配置、Schema、用户与开发文档
├── templates/              # Codex / WorkBuddy 客户端配置源模板
├── scripts/                # 测试夹具及维护脚本
├── wheels/                 # Windows 离线安装依赖
├── install.bat             # Windows 离线安装器
├── config.example.json     # 配置文件示例
└── pyproject.toml          # 包元数据与开发依赖

安全边界

  • Agent 的远端权限不会超过所配置 FTP/SFTP 账号本身的权限。
  • 远端输入输出使用虚拟路径并受 root 边界约束;SFTP 逐段拒绝符号链接,FTP 只能拒绝服务器明确报告的链接。
  • 本地上传拒绝符号链接、junction 和 reparse point,但不设置允许根目录白名单;可访问范围取决于宿主沙箱和进程权限。
  • max_file_size_bytes 只限制上传;下载和批量调用不设置客户端文件数量或总字节上限。
  • upload_file 和 upload_dir 默认不覆盖;overwrite=true 只有在 driver 能确认安全原子替换时才允许。
  • rename 和 move 永不覆盖已存在的目标。
  • delete 仅删除文件或空目录,并要求调用参数 confirm=true。该参数是工具调用门控,不是插件自行弹出的人工确认窗口。
  • SFTP 默认使用 TOFU 记录首次主机指纹;敏感环境建议配置管理员提供的 host_key_fingerprint。
  • FTP 本身不加密网络传输;敏感数据应优先使用 SFTP。

已知限制

  • 不支持 FTPS、断点续传、异步传输和显式传输超时。
  • 不提供 GUI、多用户模式或远程 MCP 服务模式。
  • 正式离线安装包当前仅提供 Windows x64 版本。
  • 另提供 Windows 交叉构建的 macOS 通用离线包,同时支持 arm64(Apple Silicon)和 x86_64(Intel),自动选择对应依赖。Intel 使用 cryptography 48.0.1 兼容锁;使用方法和验证范围见 macOS 安装手册。
  • 暂存目录不会自动清理。
  • 目录批量传输是 best-effort、非事务操作;必须检查 status、failed 和上传结果的 indeterminate,不确定时不得整体重试。
  • 上传和下载没有客户端批次总量限制,超大目录、磁盘或远端配额耗尽仍是已知资源风险。
  • read_text_preview 只适用于纯文本,不适用于 Word、Excel、PowerPoint、PDF、图片或压缩包。

文档

README 用于项目概览、快速接入和开发入口;完整契约与操作细节以下列专项文档为准:

  • 当前 Spec 基线:已经实现、可验证的运行时行为与已知契约缺口
  • Windows 快速安装手册:安装、客户端接入、配置和操作示例
  • macOS 通用安装手册:Apple Silicon 和 Intel 安装、客户端接入、Keychain 和连接验证
  • 产品能力清单:当前功能、兼容性和边界
  • 配置文件规范:字段、校验、凭据与路径规则
  • 正式 MCP 工具 Schema:从运行时 tools/list 生成的 14 个工具机器契约
  • MCP 工具 Schema 草案:历史开发草案,仅供追溯,不作为当前契约
  • 配置 JSON Schema:config.json 的机器可读基础约束
  • 命令行工具手册:setup、doctor 和 cred
  • 发布说明:版本变更与验证记录

许可

本项目基于 MIT License 开源。版权所有 (c) 2026 Ftrans,完整许可条款见 LICENSE。

—/ 5

No ratings yet

Manifest verification required

Commit e0bd764c0868

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout