AI导哈

文件系统服务器

一个安全的沙盒MCP服务器，为Void Editor提供文件系统访问功能，包括创建、读取、修改和删除文件，具有全面的安全控制。

  • by EdibleTuber
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 EdibleTuber/void-mcp-server

使用说明

无效MCP文件系统服务器

一个安全的沙盒MCP（模型上下文协议）服务器，为Void Editor提供安全的文件系统访问。使您的AI能够在项目中创建、读取、修改和删除文件——所有这些都有全面的安全控制。

特性

✅ 文件操作 -创建、读取、写入、删除和移动文件
✅ 目录管理 -创建并列出目录
✅ 搜索能力 -在多个文件中查找文本
✅ 安全沙盒 -路径受限、扩展受阻、大小限制
✅ 轻松设置 -使用JSON进行简单配置
✅ 错误处理 -明确的运营反馈

快速开始

先决条件

  • Python 3.10或更高版本
  • Void编辑器
  • pip （Python包管理器）

安装

  1. 克隆存储库
git clone https://github.com/yourusername/void-mcp-filesystem-server.git
cd void-mcp-filesystem-server
  1. 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# or on Windows:
# .venv\Scripts\activate
  1. 安装依赖项
pip install -r requirements.txt
  1. 创建配置文件 （可选）
cp mcp_config.example.json mcp_config.json
# Edit mcp_config.json with your settings

配置Void编辑器

选项1：通过作废设置界面

  1. 打开空编辑器
  2. 转到设置/首选项
  3. 查找MCP配置部分
  4. 添加您的服务器：
    • 命令： /path/to/.venv/bin/python3
    • Args： ["/full/path/to/mcp_server.py"]
    • 工作目录： 您的项目根

选项2：编辑MCP配置文件

创建或编辑MCP服务器配置文件：

macOS/Linux： ~/.config/void/mcp_servers.json
窗户： %APPDATA%\void\mcp_servers.json

{
  "mcpServers": {
    "filesystem": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["/absolute/path/to/mcp_server.py"],
      "cwd": "/your/project/directory"
    }
  }
}

重要提示： 为Python可执行文件和脚本使用绝对路径。

将系统提示添加为无效

在Void的设置中，找到提示/说明部分并添加：

You have access to filesystem tools via the MCP (Model Context Protocol) server. Use them to create, read, modify, and delete files as requested by the user.

Available tools:
- read_file(path: str) - Read file contents
- write_file(path: str, content: str) - Write or overwrite a file
- create_file(path: str, content: str = "") - Create a new file (fails if exists)
- edit_file(file_path: str, old_string: str, new_string: str, replace_all: bool = False) - Precisely edit file by replacing exact text
- delete_file(path: str) - Delete a file
- list_directory(path: str = ".") - List directory contents
- create_directory(path: str) - Create a directory
- move_file(source: str, destination: str) - Move or rename a file
- search_in_files(search_term: str, directory: str = ".", file_pattern: str = "*.py") - Search for text in files

When calling these tools, use the exact function name and parameters. Paths can be relative or absolute (if within project). Always use forward slashes (/) in paths.

Examples:
- Create: create_file("src/utils.py", "def helper():\n    pass")
- Read: read_file("src/main.py")
- Edit: edit_file("config.py", "DEBUG = True", "DEBUG = False")
- Modify: For complete rewrites, use read_file() then write_file()
- Search: search_in_files("TODO", "src", "*.py")

用法

配置后，要求您的AI执行文件操作：

  • “在以下位置创建一个新的Python文件 src/handlers.py 基本结构”
  • “阅读 config.json 并解释其结构”
  • “In main.py，将DEBUG变量从True更改为False”
  • “将docstring添加到utils.py中的计算函数中”
  • “在代码库中搜索所有TODO注释”
  • “创建一个 tests/ 目录并添加测试文件”

配置

编辑 mcp_config.json 要自定义安全设置，请执行以下操作：

{
  "allowed_root": "/absolute/path/to/your/project",
  "additional_blocked": [
    "secrets",
    "credentials"
  ],
  "additional_extensions": [
    ".vue",
    ".svelte"
  ],
  "max_file_size_mb": 10
}

配置选项

  • allowed_root -限制操作的项目目录（默认：当前目录）
  • additional_blocked -要阻止的额外模式（超出默认值，如.git、.env、.ssh）
  • additional_extensions -允许的其他文件扩展名
  • max_file_size_mb -最大文件大小（MB）（默认值：10）

安全

服务器实现了多层保护：

路径限制

  • 所有操作仅限于 allowed_root 目录
  • 无目录遍历攻击(../../../etc/passwd 封锁）
  • 用途 Path.resolve() 用于绝对路径验证

文件阻止

  • 阻止敏感文件： .env, .key, .pem, id_rsa等等。
  • 阻止目录： .git, .ssh, node_modules, __pycache__
  • 仅允许特定的文本文件扩展名

大小限制

  • 默认10MB文件大小限制
  • 防止大文件操作产生内存问题

无外壳访问权限

  • 不执行子进程或shell命令
  • 即使AI的行为出乎意料，也很安全

测试

运行附带的测试套件以验证所有功能：

  1. 创建测试目录： mkdir test_workspace && cd test_workspace
  2. 配置MCP以使用此目录
  3. 遵循以下测试用例 测试_会话.md

每个测试都验证一个特定的工具，并包括安全测试。

故障排除

服务器无法启动

# Check Python version
python3 --version  # Must be 3.10+

# Check mcp is installed
pip list | grep mcp

# Try running manually
python3 mcp_server.py

虚空无法连接

  • 验证MCP配置中的路径是否为绝对路径
  • 检查Python解释器路径是否正确
  • 确保工作目录存在
  • 检查Void的开发人员控制台是否有错误

LLM不会使用工具

  • 验证系统提示是否已添加到“无效”设置中
  • 检查MCP服务器是否显示已连接（查找工具图标）
  • 尝试重新启动Void
  • 确认模型支持工具使用（Claude、GPT-4、Command-R+效果最佳）

拒绝访问错误-“路径超出允许的目录”

⚠️ 已知无效问题： Void当前将MCP服务器限制在Void安装目录中，忽略 cwd 开始 mcp.json这是Void的MCP通道实现中的一个错误（请参见 无效GitHub问题).

解决方法： 将您的项目放置在Void的安装目录中：

# Move your project to Void's directory
mv /your/project/path /home/edible/Tools/Void/your_project

然后更新 mcp_config.json:

{
  "allowed_root": "/home/edible/Tools/Void/your_project"
}

注： 这是一个临时的解决方法。正确的修复需要更改Void的MCP实现，以遵守配置 cwd.

其他拒绝访问错误

  • 检查文件/目录是否在 allowed_root
  • 验证文件扩展名是否在允许的列表中
  • 检查路径是否包含被阻止的模式（.git、.env等）
  • 审查 mcp_config.json 设置

高级用法

自定义工具提示

在 mcp_server.py，系统提示通过自动提供 @mcp.prompt() 装饰师。修改此功能，为您的用例自定义工具说明。

扩展工具

通过使用创建函数来添加新工具 @mcp.tool() 装饰师：

@mcp.tool()
def count_lines(path: str) -> str:
    """Count lines in a file"""
    with open(path) as f:
        return str(len(f.readlines()))

添加资源

通过以下方式公开只读数据 @mcp.resource():

@mcp.resource("custom://data")
def get_custom_data() -> str:
    """Provide custom context data"""
    return "Custom data here"

局限性

  • 不支持符号链接
  • 无二进制文件操作
  • 无任意命令执行（出于安全考虑）
  • 10MB文件大小限制（可配置）
  • 操作速度比本机文件系统访问慢（网络开销）

贡献

  1. 复刻仓库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交更改(git commit -m 'Add amazing feature')
  4. 推送到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

测试与验证

在提交PR之前：

  • 在中运行所有测试用例 TEST_CASES.md
  • 测试安全约束（路径遍历、被阻止的扩展）
  • 验证错误消息是否清晰
  • 检查操作是否适用于不同的LLM模型

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

支持

路线图

  • []备份/撤消功能
  • []操作日志和审计跟踪
  • []速率限制
  • []预览更改的模拟运行模式
  • []Git集成（更改后自动提交）
  • []多用户支持

相关 MCP