FileSystem MCP Server

FileSystem MCP Server

版本：0.1.4 — 上次更新：2026-10-13

适用于 Visual Studio 2022+ 的本地 MCP 服务，通过向 AI Agent 提供对项目文件夹和文件的选择性访问，实现代码工作区功能

目录

• 🎯 目标环境
• 功能
• 安装
• 快速开始
• 配置选项
  • 选项 1：Config.json 文件（最简单，推荐新手使用）
  • 选项 2：命令行参数（高级，适用于 MCP 客户端）
  • 选项 3：混合方式（兼顾两者优点）
• 用法
  • 命令行示例
  • 可用工具
• 为什么这种混合方式非常理想
• Visual Studio 2022+ 调试
• Visual Studio 2022+ 使用示例
• 通过 GitHub Copilot Chat 编辑 mcp.json 文件
• 安全性
• 错误处理
• 故障排除
  • MCP 配置问题
  • Visual Studio 2022+ 调试
  • 常见问题
• 命令行参考
• 跨平台路径支持
• 高级和实际场景中的 MCP 配置示例

---

🎯 目标环境

此 MCP 服务针对以下场景进行了优化：

• Visual Studio 2022+ 开发工作流
• 无需复杂工作区设置的本地开发环境
• 直接访问文件夹，以执行文件系统操作
• 不使用 .code-workspace 文件的开发环境
• 单个项目目录，而非多根工作区

功能

• 目录遍历：列出允许访问的目录内容
• 文件读取：读取具有允许扩展名的文件内容
• 文件写入：向文件写入文本或二进制内容 — 需通过 --allow-write 显式启用（默认禁用）
• 目录验证：检查已配置目录是否可访问
• 混合配置：命令行参数（MCP）+ config.json 回退配置（调试）
• Visual Studio 2022+ 调试：支持无参数启动
• 跨平台路径支持：自动处理 Windows（\）和 Unix（/）路径分隔符
• 安全性：仅允许访问明确指定的目录和文件类型
• 专注本地开发：非常适用于 Visual Studio 2022+ 等环境

安装

从 PyPI 安装（推荐用户使用）

pip install vs-filesystem-mcp-server

从源代码安装（用于开发）

1. 确保已安装 Python 3.10+

2. 克隆代码仓库

3. 转到项目目录

4. 使用 uv 安装依赖项：

   uv sync
   

快速开始

1. 用于 MCP：将修正后的配置添加到 .mcp.json
2. 用于调试：在 Visual Studio 2022+ 中按 F5 即可——会自动使用 config.json
3. 测试配置：先调用 init() 工具
4. 如果 init() 返回错误：请检查目录路径和权限

配置选项

选项 1：Config.json 文件（最简单，推荐新手使用）

最简单的入门方式！ 创建一个 config.json 文件：

用于 MCP 服务：

• 将 config.json 放在 .mcp.json 文件所在的文件夹中（通常为 C:\Users\YourUsername\）

从源代码进行调试（Visual Studio 2022+）：

• 将 config.json 放在与 app.py 相同的目录中（D:/Projects/filesystem_server/）

{
  "allowed_dirs": [
    "C:/Users/YourUsername/Documents/projects",
    "D:/projects",
    "D:/Webs"
  ],
  "allowed_extensions": [
    ".py", ".js", ".ts", ".json", ".md", ".txt",
    ".yml", ".yaml", ".toml", ".cfg", ".ini", ".cs",
    ".css", ".scss", ".htm", ".html", ".xml", ".xaml"
  ],
  "allow_write": false
}

注意： 设置 "allow_write": true 可启用 write_file 和 write_file_binary 工具。

MCP 配置（通过 pip 安装）

将以下内容添加到 .mcp.json 文件中（通常位于 VS 2022+ 中的 C:\Users\YourUsername\）：

{
  "servers": {
    "filesystem-server": {
      "command": "vs-filesystem-mcp-server"
    }
  }
}

注意： 通过 pip 安装时，只需使用命令 vs-filesystem-mcp-server，无需指定 app.py 的路径！

MCP 配置（从源代码运行）

如果你正在开发并从源代码运行：

{
  "servers": {
    "filesystem-server": {
      "command": "python",
      "args": [
        "/absolute/path/to/your/project/filesystem_server/app.py"
      ],
      "cwd": "/absolute/path/to/your/project/filesystem_server"
    }
  }
}

优势：

• ✅ 无需命令行参数
• ✅ 非常适合在 Visual Studio 2022 中调试（只需按 F5）
• ✅ 放置在正确位置后，即可与 MCP 客户端配合使用
• ✅ 易于编辑和修改
• ✅ 非常适合测试和开发

用法：

# For debugging in Visual Studio 2022:
python app.py  # Uses config.json from same directory as app.py

# For MCP server usage:
# The MCP client automatically finds config.json in the .mcp.json directory

重要的位置说明：

• 🔧 调试： config.json 与 app.py 放在同一目录
• 🌐 MCP 服务： config.json 与 .mcp.json 放在同一目录
• 📁 不同的用途对应不同的位置！

选项 2：命令行参数（高级——适用于 MCP 客户端）

适用于生产环境中的 MCP 客户端配置，尤其是在你希望将所有内容放在同一处时：

通过 pip 安装时

{
  "servers": {
    "filesystem-server": {
      "command": "vs-filesystem-mcp-server",
      "args": [
        "--allowed-dirs", "D:/projects", "D:/Webs",
        "--allowed-extensions", ".py", ".js", ".ts", ".json", ".md", ".txt"
      ]
    }
  }
}

从源代码运行时

python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md"

# With write access enabled:
python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md" --allow-write true

MCP 客户端配置（.mcp.json）：

{
  "servers": {
    "filesystem-server": {
      "command": "python",
      "args": [
        "/absolute/path/to/your/project/filesystem_server/app.py",
        "--allowed-dirs", "D:/projects", "D:/Webs",
        "--allowed-extensions", ".py", ".js", ".ts", ".json", ".md", ".txt"
      ],
      "cwd": "/absolute/path/to/your/project/filesystem_server"
    }
  }
}

优势：

• ✅ 配置自包含
• ✅ 无需外部配置文件
• ✅ 便于进行版本控制
• ✅ 在 MCP 设置中明确可见

选项 3：混合方式（兼得两者优势）

服务会优先使用命令行参数；如果未提供参数，则自动回退到 config.json。

工作方式：

• MCP 客户端： 使用命令行参数（选项 2）
• Visual Studio 调试： 自动使用 config.json（选项 1）
• 优先级： 如果提供了命令行参数，则会覆盖 config.json 中的配置

优势：

• ✅ 既适用于 MCP 客户端，也适用于调试
• ✅ 不同使用场景之间不会发生冲突
• ✅ 灵活且方便开发者使用
• ✅ 可根据具体情况选择最佳选项

用法

命令行示例

# With command line arguments (MCP clients):
python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md"

# Using config.json fallback (Visual Studio 2022+ debugging):
python app.py

# Show MCP configuration help:
python app.py --help-mcp

可用工具

1. init(directory, file_path) - 验证配置目录是否可访问，并可选择列出目录和/或读取文件

   • directory（可选）：要列出内容的目录路径（可以为 None）
   • file_path（可选）：要读取内容的文件路径（可以为 None）
   • 如果所有目录均可访问，则返回 { "message": "OK", "isError": false, ... }
   • 如果有目录无法访问，则返回错误详情
   • 显示配置来源（命令行参数或配置文件）
   • 使用此工具可在使用其他工具前验证配置

2. list_directory(directory, report_progress=True, batch_size=100) - 列出指定目录中的文件和子目录，可选择报告进度

   • directory：目录的绝对路径或相对路径（同时支持 / 和 \ 分隔符）
   • report_progress（可选）：如果为 True，则返回进度信息和批次详情（默认值：True）
   • batch_size（可选）：报告进度前要处理的项目数（默认值：100）
   • 如果 report_progress 为 False，则返回文件和目录名称列表
   • 如果 report_progress 为 True，则返回包含 contents、progress_info、total_items 和 processing_time 的字典
   • 如果发生错误，则返回包含 "error" 和 "error_message" 键的字典
   • 不会引发异常，所有错误都会作为结果的一部分返回

3. read_file(file_path) - 以文本形式读取指定文件的内容

   • 将文件内容作为字符串返回（仅适用于文本文件）
   • 不适用于二进制文件（图像、音频等）

4. read_file_binary(file_path) - 以 Base64 编码的二进制形式读取指定文件的内容

   • 成功时返回 { "content_base64": <base64 string>, "encoding": "base64", "error": False }
   • 如果不允许读取该文件或找不到文件，则返回错误字典
   • 适用于图像、音频和其他二进制文件

5. list_resources(directory=None, report_progress=True, batch_size=100) - 以 MCP 资源格式列出目录（或所有允许的目录）中的所有资源（文件和目录）

   • directory（可选）：起始目录（默认为所有 allowed_dirs）
   • report_progress（可选）：如果为 True，则返回进度信息和批次（默认值：True）
   • batch_size（可选）：每个进度批次包含的资源数量（默认值：100）
   • 如果 report_progress 为 False，则返回资源对象列表
   • 如果 report_progress 为 True，则返回包含 contents、progress_info、total_items 和 processing_time 的字典
   • 资源对象示例：

     {
       "id": "D:/projects/example.txt",
       "type": "file",
       "name": "example.txt",
       "path": "D:/projects/example.txt",
       "metadata": {
         "size": 1234,
         "modified": "2025-08-18T12:34:56Z"
       },
       "actions": ["read", "read_binary", "write", "write_binary"]
     }
     

6. get_resource(path) - 获取特定文件或目录的元数据和操作

   • path：资源的绝对路径或相对路径
   • 返回资源对象（id、type、name、path、metadata、actions）或错误字典
   • 对于文件，包含大小和修改时间；对于目录，包含类型和操作
   • 不返回文件内容

7. write_file(file_path, content) - 将文本内容写入指定文件（需要 --allow-write）

   • file_path：要写入的路径（必须位于允许的目录中）
   • content：要写入的文本字符串
   • 如果写入权限已禁用、路径不允许、扩展名不允许或发生 IO 错误，则引发 ValueError
   • 覆盖现有文件
   • 默认禁用 — 使用 --allow-write 标志或在 config.json 中设置 "allow_write": true 启用

8. write_file_binary(file_path, content_base64) - 将 base64 编码的二进制内容写入文件（需要 --allow-write）

   • file_path：要写入的路径（必须位于允许的目录中）
   • content_base64：经过 Base64 编码的二进制数据
   • 返回 {"success": true, "bytes_written": int, "error": false} 或错误字典
   • 覆盖现有文件，适用于图像和二进制文件
   • 默认禁用 — 使用 --allow-write 标志或在 config.json 中设置 "allow_write": true 启用

为什么这种混合方式非常理想

• ✅ MCP 客户端：使用高效的命令行参数
• ✅ Visual Studio 2022：通过 config.json 后备配置，实现零障碍调试
• ✅ 无冲突：优先级系统可妥善处理这两种情况
• ✅ 开发者友好：可按你希望的方式运行
• ✅ 两全其美：MCP 的高效性 + 调试的便利性

Visual Studio 2022+ 调试

出色的调试体验：

• ✅ 无需命令行参数
• ✅ 只需按 F5 即可开始调试
• ✅ 自动使用 config.json
• ✅ 可设置断点并正常调试
• ✅ 全面的 IntelliSense 和调试支持

调试设置：

1. 在 Visual Studio 2022 中打开项目
2. 确保 config.json 存在（已为你创建）
3. 按 F5 或选择 Debug > Start Debugging
4. 服务将使用你配置的目录启动

Visual Studio 2022+ 使用示例

下面通过逐步示例说明如何在 Visual Studio 2022 中调用 FileSystem MCP Server。这些截图展示了使用别名 "fss" 调用服务的过程；它只是 "filesystem-server" 的简短名称。你可以在 .mcp.json 文件中自定义此别名——实际名称由你决定。

**注意：**所有图片均位于 images/ 子文件夹中。

步骤 1：调用服务工具

在此示例中，MCP 客户端配置为使用 "fss" 作为服务名称。这只是为了方便使用的别名。

第 2 步：查看服务器响应

服务器会返回请求结果，例如 read_file() 工具的输出。

---

注意：

• 这里使用 "fss" 作为简写。你可以在 .mcp.json 配置中使用任何喜欢的名称。
• 如需更改服务器名称，只需将 .mcp.json 文件中的键 "filesystem-server" 更新为其他名称即可。

有关 MCP 客户端配置的更多详情，请参阅上方的配置选项部分。

通过 GitHub Copilot Chat 编辑 mcp.json 文件

你可以直接在 Visual Studio 中通过 GitHub Copilot Chat 界面轻松编辑 mcp.json 配置文件。请按以下步骤操作：

1. 在 Agent 模式下，点击 Visual Studio 右侧的“工具”图标。
2. 点击列表中任意 MCP 服务旁边的箭头。
3. 选择“编辑”——mcp.json 文件将打开以供编辑。

这样，你无需离开 IDE 即可快速更新 MCP 服务配置。

安全性

• 只能访问 --allowed-dirs 或 config.json 中指定的目录
• 只能读取或写入扩展名列在 --allowed-extensions 或 config.json 中的文件
• 默认禁用写入权限：write_file 和 write_file_binary 需要 --allow-write 标志，或在 config.json 中设置 "allow_write": true
• 访问前会验证所有路径
• 服务以用户帐户的权限运行
• 非常适合本地开发：可安全访问项目目录

错误处理

服务会提供详细的错误消息，涉及以下情况：

• 未授权的目录访问
• 无效的文件路径
• 不支持的文件扩展名
• 缺少配置（针对 MCP 和调试场景提供实用指导）
• 目录无法访问的问题（通过 init() 工具）

list_directory() 的新增错误处理：

• list_directory() 函数现在会将错误作为结果列表的一部分返回，而不是引发异常
• 错误格式：["error", "detailed_error_message"]
• 这样 MCP 客户端无需处理异常，即可更轻松地妥善处理错误
• 调用成功时会返回正常的目录内容列表

故障排除

MCP 配置问题

你的原始配置在 "D:/Webs" 后缺少逗号。上方的修正版本已解决此问题。

Visual Studio 2022+ 调试

1. 确保 config.json 存在（已为你的目录创建）
2. 从 init() 工具开始，以验证配置
3. 设置断点并按常规方式调试
4. 检查输出窗口，确认配置来源

常见问题

1. 缺少配置：服务会针对 MCP 和调试场景显示实用提示
2. 路径访问错误：确认目录存在且可访问
3. 权限问题：检查已配置路径的目录权限
4. MCP 客户端问题：使用上方修正后的配置

命令行参考

python app.py --help                         # Show help
python app.py --help-mcp                     # Show MCP configuration examples  
python app.py --allowed-dirs DIR1 DIR2       # Set allowed directories
python app.py --allowed-extensions EXT1 EXT2 # Set allowed extensions
python app.py --allow-write true             # Enable write tools (disabled by default)
python app.py --allow-write false            # Explicitly disable write tools
python app.py --config custom.json           # Use custom config file
python app.py                                # Use config.json fallback (debugging)

跨平台路径支持

文件系统服务会自动规范化路径，以适配不同操作系统的路径约定：

✅ Windows 用户——两种格式均可使用

{
  "allowed_dirs": [
    "D:\\projects",           // Windows-style backslashes
    "F:/sd/wipes",           // Unix-style forward slashes  
    "C:\\Users\\Me\\Docs"    // Mixed formats work too
  ]
}

✅ 自动路径规范化

• 输入："F:\sd\wipes"（Windows 常用格式）
• 规范化后："F:/sd/wipes"（适用于 Python 的格式）
• 结果：✅ 可无缝使用，不会出错！

✅ MCP 工具示例

# All of these work identically:
list_directory("F:\\sd\\wipes")    # Windows format
list_directory("F:/sd/wipes")      # Unix format  
list_directory("F:\\sd/wipes")     # Mixed format

这为何重要

• 🪟 Windows 用户可以直接输入 F:\sd\wipes
• 🐧 Unix 用户可以使用传统的 F:/sd/wipes
• 🔧 不再有路径格式错误——一切都能正常使用
• 🛡️ 无论分隔符样式如何，安全检查都能正常运行

高级及真实场景 MCP 配置示例

如需查看更高级、特定平台或旧版 MCP 客户端配置示例（包括 "servers" 和 "mcpServers" 两种格式），请参阅本仓库中的 mcp_configuration_examples.json 文件。

此文件包含：

• 适用于 Windows、Linux 和 macOS 的其他真实场景配置
• 精简的 Web 开发配置
• 多种目录和文件类型示例
• 从 config.json 迁移到命令行参数的提示
• 使用 "mcpServers" 格式的旧版 MCP 客户端支持

如果您需要更大的灵活性，或正在使用非标准 MCP 客户端，请参阅此文件。