filesystem

FieldCure MCP Filesystem Server

一个安全的 Model Context Protocol (MCP) 服务，可向 AI 客户端提供本地文件系统操作。使用 C# 和官方 MCP C# SDK 构建。

功能

• 17 种文件系统工具：读取、写入、追加、删除、搜索、复制、移动、转换为 Markdown 等
• 沙盒访问：所有操作仅限于明确允许的目录
• MCP roots 协议：客户端可在运行时更改允许的目录，无需重启服务
• 强化安全性：防止路径遍历、解析符号链接、阻止 NTFS ADS、拒绝 Windows 保留名称
• 原子写入：采用先写入临时文件再重命名的模式，防止数据损坏
• 二进制检测：二进制文件自动以 base64 返回，文本文件则以 UTF-8 返回
• 内置文档解析：可直接读取支持的文档格式，并在磁盘上转换为 Markdown
• Stdio 传输：通过 stdin/stdout 上的 JSON-RPC 实现标准 MCP 子进程模式

安装

dotnet tool

dotnet tool install -g FieldCure.Mcp.Filesystem

从源代码安装

git clone https://github.com/fieldcure/fieldcure-mcp-filesystem.git
cd fieldcure-mcp-filesystem
dotnet build

要求

• .NET 8.0 Runtime 或更高版本

配置

Claude Desktop

{
  "mcpServers": {
    "filesystem": {
      "command": "fieldcure-mcp-filesystem",
      "args": [
        "C:\\Users\\me\\Documents",
        "C:\\Projects"
      ]
    }
  }
}

VS Code

{
  "servers": {
    "filesystem": {
      "command": "fieldcure-mcp-filesystem",
      "args": [
        "${workspaceFolder}"
      ]
    }
  }
}

工具

文件操作

工具	说明
read_file	读取文件内容（文本以 UTF-8 编码，二进制以 base64 编码）
read_multiple_files	一次读取多个文件，并逐个处理错误
read_file_lines	读取指定范围的行
convert_to_markdown	将一个受支持的文档文件转换为磁盘上的 Markdown 文件
convert_directory_to_markdown	将目录中的多个受支持文档文件批量转换为 Markdown 文件
write_file	以原子写入方式创建或覆盖文件
append_file	在文件末尾追加内容，并自动添加换行符
modify_file	查找并替换文本（纯文本或正则表达式）
copy_file	复制文件或递归复制目录
move_file	移动或重命名文件或目录
delete_file	删除文件或目录

目录操作

工具	说明
list_directory	列出目录内容，并显示类型标记、大小和日期
create_directory	递归创建目录
directory_tree	按层级显示目录树，可配置深度

搜索与信息

工具	说明
search_files	按 glob 模式查找文件
search_within_files	搜索多个文件中的文本内容，并显示行号
get_file_info	获取文件或目录的元数据

MCP Roots 协议

该服务支持 MCP roots 协议，可在运行时更改目录。客户端更改 roots 时：

1. 服务会请求更新后的 roots 列表。
2. 允许的目录将被整体替换。
3. CLI 参数用于指定初始沙盒。
4. 空 roots 列表表示禁止所有文件访问。

安全模型

在执行任何文件系统操作之前，所有路径都会通过 IPathValidator 验证：

1. 允许的目录定义沙盒边界。
2. . 和 .. 会通过 Path.GetFullPath() 进行规范化。
3. 符号链接必须解析到允许的目录内。
4. 路径前缀匹配会考虑目录分隔符。
5. 阻止 NTFS 替代数据流。
6. 拒绝 Windows 保留名称。
7. 允许目录的更新是线程安全的。

Markdown 转换工具使用相同的沙盒规则验证源路径和输出路径。它们会将转换后的 Markdown 直接写入磁盘，而不是通过 MCP 返回完整文档文本；与先调用 read_file 再调用 write_file 相比，这通常更节省 token。

项目结构

src/FieldCure.Mcp.Filesystem/
|- Program.cs
|- Security/
|  |- IPathValidator.cs
|  \- PathValidator.cs
|- Tools/
|  |- FileOperationTools.cs
|  |- DirectoryTools.cs
|  \- SearchTools.cs
\- Utilities/
   |- EncodingDetector.cs
   \- FileSize.cs

开发

dotnet build
dotnet test
dotnet pack src/FieldCure.Mcp.Filesystem -c Release

限制

已支持	暂不支持
文本文件读写（UTF-8）	自动检测非 UTF-8 编码
二进制文件检测 + base64	超大文件（>100 MB）的流式处理
原子写入	文件监视 / 更改通知
Glob 模式搜索	全文索引
正则表达式查找和替换	多文件事务性写入
符号链接解析	跨平台创建符号链接
MCP roots 协议	HTTP 传输
提取文档文本 / 将 DocumentParsers 支持的格式转换为 Markdown	扫描文档的 OCR

另请参阅

属于 AssistStudio 生态系统的一部分。

许可证

MIT