使用说明

项目简介

本项目 'mcp_server_filesystem' 是一个实现了 Model Context Protocol (MCP) 的服务器，专注于提供文件系统操作能力。它允许AI助手等MCP客户端通过标准化的MCP协议，安全地与您本地文件系统进行交互，从而实现代码读取、文件编辑、项目分析等功能。所有操作都限定在您指定的项目目录内，保障安全性。

主要功能点

目录列表 (list_directory)：列出项目目录中的所有文件和文件夹，支持根据 '.gitignore' 文件进行过滤。
文件读取 (read_file)：读取指定文件内容。
文件保存 (save_file)：原子性地保存文件内容，确保数据一致性。
文件追加 (append_file)：向文件末尾追加内容。
文件删除 (delete_this_file)：删除指定文件。
文件编辑 (edit_file)：基于文本匹配进行文件内容编辑，支持精确匹配和模糊匹配，并能保留代码缩进和格式。
结构化日志：提供详细的日志记录，包括控制台日志和可选的JSON格式文件日志，方便问题排查。
安全性：所有文件操作均限制在预设的项目目录内，防止路径遍历攻击，保障本地文件安全。

安装步骤

克隆仓库

git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp_server_filesystem

创建并激活虚拟环境 (可选，推荐)

python -m venv venv
source venv/bin/activate   # Linux/macOS
# venv\Scripts\activate  # Windows

安装依赖
```
pip install -e .
```

服务器配置

MCP客户端（如Claude Desktop）需要配置MCP服务器的启动命令和参数才能连接。以下是配置示例，请根据您的实际路径进行修改：

{
    "mcpServers": {
        "filesystem_server": {  // 服务器名称，客户端配置中引用
            "command": "python",  // 启动命令，通常是Python解释器路径
            "args": [                 // 启动参数列表
                "-m",
                "src.main",         // 运行主模块
                "--project-dir",    // 指定项目目录参数
                "/path/to/your/project" //  <-- 替换为您的项目目录的绝对路径
                // "--log-level",    // (可选) 日志级别，默认为INFO
                // "DEBUG",
                // "--log-file",     // (可选) 结构化日志文件路径
                // "/path/to/logs/mcp_server.log"
            ],
            "env": {
                // "PYTHONPATH": "/path/to/mcp_server_filesystem/" // (可选) 如果需要可以设置PYTHONPATH
            }
        }
    }
}

参数说明:

'server name': 'filesystem_server' - 您为该文件系统服务器自定义的名称，在MCP客户端配置中会使用此名称。
'command': 'python' - 执行服务器程序的命令，通常设置为您的Python解释器路径。
'args': 启动参数列表，包含：
- '-m src.main': 运行 'src/main.py' 作为主模块启动服务器。
- '--project-dir': 必需参数，指定服务器允许访问的项目根目录。 请务必将其替换为您希望AI助手访问的本地项目目录的绝对路径。
- '--log-level' (可选): 设置日志输出级别，例如 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'。默认为 'INFO'。
- '--log-file' (可选): 指定结构化JSON格式日志的输出文件路径。如果不设置，则仅输出控制台日志。
'env': 环境变量设置 (可选)，例如 'PYTHONPATH'。在大多数情况下，虚拟环境已经处理了路径问题，所以通常不需要额外设置。

请注意:

将 '/path/to/your/project' 替换为您希望共享给MCP客户端访问的实际项目目录的绝对路径。
如果您使用了虚拟环境，请确保 'command' 指向虚拟环境中的Python解释器。
可以根据需要配置可选的 '--log-level' 和 '--log-file' 参数。

基本使用方法

启动服务器：根据 "运行服务器" 部分的命令启动 MCP 文件系统服务器，确保指定了正确的 '--project-dir' 参数。
配置MCP客户端：在您的MCP客户端（如Claude Desktop）中，按照上述 "服务器配置" 示例，添加或修改服务器配置，确保 'command' 和 'args' 参数正确指向您启动的服务器。
连接和使用：启动MCP客户端，客户端应该能够连接到您的文件系统服务器。之后，您可以通过客户端提供的界面或指令，让AI助手执行文件系统操作，例如：
- 请求AI助手列出项目目录中的文件。
- 让AI助手读取指定文件的内容。
- 指示AI助手编辑或修改项目中的代码文件。

请参考MCP客户端的文档，了解如何具体调用文件系统服务器提供的功能。

关键词