AI导哈

FTP代理服务

FtpMcpServer是一个轻量级无状态代理服务，允许MCP客户端通过HTTP与FTP/FTPS服务器交互，支持文件读写、目录管理等操作。

  • by StateSimplify-LLC
  • C#
  • 本地部署
  • 更新于
在 GitHub 查看 StateSimplify-LLC/FtpMcpServer

使用说明

FtpMcpServer —— 一个C#（.NET 8）实现的MCP ↔ FTP代理

FtpMcpServer 允许任何模型上下文协议（MCP）客户端通过一个用 C# 编写的轻量级、无状态代理，与普通的 FTP/FTPS 服务器进行通信。它提供了安全且描述清晰的 MCP 工具，以及一种资源类型，这些工具和资源类型通过 FluentFTP 直接映射到 FTP 操作。

亮点

  • 纯.NET 8，使用官方MCP C# SDK（基于HTTP传输） /mcp）。
  • 无状态、每次请求建立连接：客户端传递一个API密钥（一个base64编码的JSON有效载荷），其中包含FTP主机、凭据和选项。无需服务器端存储凭据。
  • 读写支持：列出、下载、上传、写入文本、删除、创建/删除目录、重命名、查看文件大小、查看修改时间。
  • 将流式文件作为MCP资源回传时，指定正确的资源类型（MIME类型）。
  • 通过HTTP端点，与OpenAI兼容的MCP客户端（包括OpenAI Playground）协同工作。

它是如何工作的

  • 客户端通过HTTP连接到MCP终端节点（/mcp)。
  • 每个请求都包含一个 Authorization: Bearer <token> 或者 X-Api-Key: <token>，其中 <token> 是一个Base64编码的JSON对象，用于描述目标FTP服务器和连接选项。
  • 服务器根据每个请求生成（或推导出） FtpDefaults 从该令牌中的声明（主机、端口、用户名/密码、目录、SSL、被动模式、超时设置等）获取。
  • 工具使用FluentFTP执行并返回结构化结果或嵌入式资源。
ASCII overview
client (MCP) ──HTTP──> /mcp (auth via Bearer/X-Api-Key)
   │                                 │
   │                          build FtpDefaults (from token claims)
   │                                 │
   └────────── tools/resources <─────┘
                                FluentFTP → FTP/FTPS server

快速入门

先决条件

  • .NET SDK 8.0及以上版本
  • 一个可以从运行FtpMcpServer的机器上访问的FTP/FTPS服务器

构建并运行

  • 克隆与恢复：
    • git clone <your-repo-url>
    • dotnet restore
  • 在本地运行于一个可预测的端口（例如8787）：
    • dotnet run --urls "http://localhost:8787"
  • 通过访问以下地址验证服务器是否已启动（健康检查端点无需认证）：
    • http://localhost:8787/health
    • http://localhost:8787/info

MCP端点处于 /mcp 并且需要授权。

认证和令牌格式

通过base64编码的JSON令牌提供凭据和连接设置 Authorization 或者 X-Api-Key 头球 有效载荷支持：

必需的

  • server 或者 hostFTP 主机名/IP
  • port数字（如果省略，默认为21）
  • username：字符串
  • password字符串
  • dir起始目录，例如。， "/"

可选

  • ssl布尔值（使用FTPS）
  • passive布尔型（默认 true)
  • ignoreCertErrors布尔值（FTPS验证）
  • timeoutSeconds数字
  • retryAttempts数字（默认 3（被）夹在……之间 1 并且 10）

示例令牌 JSON

{
  "server": "ftp.example.com",
  "port": 21,
  "username": "demo",
  "password": "s3cr3t",
  "dir": "/pub",
  "ssl": false,
  "passive": true,
  "ignoreCertErrors": false,
  "timeoutSeconds": 30,
  "retryAttempts": 3
}

将此JSON编码为UTF-8，然后进行Base64编码，并将其作为承载令牌传递。（如何编码取决于您的客户端环境。）

使用内置端点生成一个令牌

如果你的构建包含 TokenController （GET /token), 您可以直接从正在运行的服务器生成一个即用型令牌（无需本地脚本）：

1) 启动服务器
确保FtpMcpServer正在运行，例如在 http://localhost:8787。

2) 打开令牌URL
在浏览器或HTTP客户端中访问此地址，并用您的FTP详细信息替换相应值：

http://localhost:8787/token
  ?server=ftp.example.com
  &username=demo
  &password=s3cr3t
  &dir=/pub
  &port=21
  &ssl=false
  &passive=true
  &ignoreCertErrors=false
  &timeoutSeconds=30

笔记

  • 你可以使用其中任意一个 server 或者 host如果两者都提供， host 在连接方面具有优先权，并且 server 在有效载荷中有所体现。
  • 默认值： port=21， dir=/可选布尔值， timeoutSeconds，和 retryAttempts 可以省略。
  • 验证：缺失 server/host， username或者 password 返回400。 port 必须大于 0； timeoutSeconds （当提供时）必须大于0； retryAttempts （如提供）必须在1到10之间。

3) 复制结果
端点返回的JSON格式如下：

{
  "token": "<BASE64_STRING>",
  "authorizationHeader": "Authorization: Bearer <BASE64_STRING>",
  "payload": {
    "server": "ftp.example.com",
    "host": "ftp.example.com",
    "port": 21,
    "username": "demo",
    "dir": "/pub",
    "useSsl": false,
    "passive": true,
    "ignoreCertErrors": false,
    "timeoutSeconds": 30,
    "retryAttempts": 3
  }
}

使用原始数据或 "token" 或者复制 "authorizationHeader" 将此行原样添加到客户端的头部。

4) 使用MCP（多通道协议）令牌
当连接到 /mcp，包括：

Authorization: Bearer <BASE64_STRING>

（或者 X-Api-Key: <BASE64_STRING>)

提示：如果您的密码包含在URL中有特殊含义的字符（&， +， #等)，在查询字符串中对其进行URL编码，或者使用能够通过查询参数自动处理此操作的HTTP客户端。

连接来自OpenAI API和Playground

  • 终端点： http://<host>:<port>/mcp
  • 标题： 包括 Authorization: Bearer <YOUR_BASE64_TOKEN> （或者 X-Api-Key）。
  • 游乐场： 配置您的MCP连接，使其指向上述终端，并在头部提供您的令牌。

可用的工具和资源

工具（类别： FtpTools)

  • ftp_listDirectory(path?)列出包含以下内容的条目： name， isDirectory， size， modified， permissions。
  • ftp_downloadFile(path)将文件作为嵌入式资源（base64）返回，并进行MIME类型检测。
  • ftp_uploadFile(path, dataBase64)将base64内容上传到指定路径（按需创建目录）。
  • ftp_writeFile(path, content, encoding?)使用指定的编码（默认为UTF-8）写入纯文本。
  • ftp_deleteFile(path)删除一个文件。
  • ftp_makeDirectory(path)创建一个目录。
  • ftp_removeDirectory(path)删除一个空目录。
  • ftp_rename(path, newName)在其父目录内重命名文件或目录。
  • ftp_getFileSize(path)返回以字节为单位的大小。
  • ftp_getModifiedTime(path)返回最后修改时间。

重试处理

  • 对于瞬时的网络或服务器错误，最多会重试 retryAttempts 尝试次数（默认为3次，最多不超过10次），每次尝试之间有短暂延迟。
  • 诸如认证失败等致命错误会立即显现，不会进行重试。
  • FluentFTP 配置了相同的重试次数，因此套接字级别的操作也遵守这一限制。

资源类型（类别： FluentFtpResourceType)

  • ftp_file读取远程文件并返回一个带有从路径推断出的MIME类型的Blob资源。

相关 MCP