Filesystem MCP

🚀 文件系统服务器说明

本项目是一个遵循 Model Context Protocol（MCP）协议的文件系统交互服务器，为 AI 代理提供安全、高效且功能全面的接口，以执行各类文件操作任务。

🚀 快速开始

安装依赖

pip install zstandard python-multipart uvicorn[server,cli]

初始化配置文件

cp config.example.yaml config.yaml && nano config.yaml

启动服务

uvicorn server:app --host 0.0.0.0 --port 8000

✨ 主要特性

文件浏览与检查

• list_files 和 stat_items：可列出文件和目录（支持递归），并获取多项文件状态信息。
• get_file_info：获取单个文件的详细信息，包含元数据和内容摘要。

内容读写

• read_content、write_content 和 append_content：实现多文件的读取、写入和追加功能，会自动创建父目录。
• search_files：通过关键字或正则表达式在多个文件中进行搜索，并返回匹配结果。

精准编辑与查找

• edit_file 和 replace_content：支持多文件的精准内容修改（包括插入、替换和删除操作），保留代码缩进并输出变更日志。
• search_files 和 replace_in_files：实现跨文件的文本搜索与替换，提供上下文信息以便更准确地定位目标内容。

目录管理

• create_directories：创建一个或多个目录，支持递归创建父目录。
• delete_items 和 move_items：实现安全的文件和目录删除、移动以及重命名操作。

权限控制

• chmod_items 和 chown_items：批量更改文件和目录的 POSIX 权限和所有者信息，确保权限设置准确无误。

🌟 优势特点

1. 安全性高：所有操作都被限制在指定的根目录内，防止越界访问。
2. 效率优异：支持批量处理多个文件，显著减少与 AI 代理之间的通信开销。
3. 可靠性强：每个操作都会返回详细的执行结果和错误报告，便于调试和问题排查。
4. 功能全面：提供覆盖文件生命周期的丰富操作接口，满足多种场景需求。

📚 详细文档

设计理念

• 安全为先：严格限制所有操作在指定根目录内进行。
• 效率优先：通过直接 API 调用减少资源消耗和延迟。
• 简洁明了：提供清晰一致的 MCP 协议接口，便于集成和使用。
• 稳定可靠：每个功能都经过全面测试，并使用 Zod 模式严格验证输入参数。

使用场景

1. 代码仓库管理：执行自动化的文件检查和修复操作。
2. 内容生成工具：提供高效的多文件读写能力，加速内容生成流程。
3. 数据处理平台：实现复杂的数据处理逻辑，包括文件筛选、转换和归档等。

项目架构

该服务器采用模块化设计：

• 核心管理层：负责权限校验和操作合法性检查。
• 文件操作层：封装具体的文件系统调用。
• 网络通信层：提供基于 HTTP 或 WebSocket 的接口。
• 日志与监控层：记录操作日志并提供实时监控功能。

请求示例

列举目录内容

GET /api/list HTTP/1.1
Host: localhost:8000
Authorization: Bearer <your-token>
Directory: ./examples

写入文件内容

POST /api/write HTTP/1.1
Host: localhost:8000
Authorization: Bearer <your-token>
Content-Type: multipart/form-data

-- boundary
filename=example.txt
content=hello world
-- boundary--

项目演示视频

• 链接：服务器运行演示
• 时长：5 分钟

💻 使用示例

基础用法

以下是启动服务的示例：

uvicorn server:app --host 0.0.0.0 --port 8000

高级用法

在实际使用中，可以根据不同的需求调整启动服务的参数，例如更改主机地址和端口号：

uvicorn server:app --host 127.0.0.1 --port 8080

❓ 常见问题解答

1. 如何处理大文件？ 支持分块上传和下载功能，确保高效处理大文件。
2. 如何保证安全性？ 所有操作都被限制在预设的根目录内，并且严格校验用户权限。
3. 如何扩展功能？ 可通过插件机制灵活添加新功能，保持核心代码的简洁性。

🚧 未来发展

• 计划开发基于 Websocket 的长连接支持，提升实时文件操作的效率。
• 考虑增加版本控制功能，便于管理文件变更历史。
• 探索与主流代码仓库（如 Git）的集成可能性。

👥 开发团队

维护者：John Doe 贡献者：Alice Smith，Bob Johnson

⚠️ 重要提示

本文档中的部分信息（如链接和示例）尚未完全准备就绪，相关内容将陆续补充完善。