MCP文件服务器
一种使用模型上下文协议（MCP）的安全文件服务器实现，为文件系统操作提供标准化接口。
概述
MCP文件服务器是一个Node.js应用程序，它实现了专门用于文件操作的MCP服务器。它提供了一种安全和标准化的方式，通过MCP协议与文件系统进行交互，适用于与Claude等AI助手和Cursor等开发工具集成。
服务器提供以下工具：
文件操作
list_files：列出指定目录中的文件read_file：读取文件的内容write_file：将内容写入文件delete_file：删除文件或目录set_base_directory：直接从聊天设置文件操作的基本目录get_base_directory：获取当前基目录
Git操作
git_command：执行基目录中的git命令
项目结构
该项目遵循模块化架构，服务按责任组织：
mcp-file-server/
├── services/ # Service modules
│ ├── configService.js # Configuration management
│ ├── fileService.js # File system operations
│ ├── gitService.js # Git operations
│ ├── loggerService.js # Logging functionality
│ └── toolService.js # MCP tool registration
├── files/ # Default storage directory
├── log/ # Log files
├── examples/ # Example scripts and usage demos
├── mcp_server.js # Main application entry point
├── package.json # Project metadata and dependencies
└── README.md # Documentation安全功能
- 强健的路径验证，防止目录遍历攻击
- 仔细规范和解析文件路径
- 命令验证以防止命令注入
- 操作记录到专用日志文件中以供审计
- 安全处理相关路径
先决条件
- Node.js>=16.0.0
- npm或yarn包管理器
- Git（用于Git_command功能）
安装
- 克隆此存储库：
git clone
cd mcp-file-server- 安装依赖项：
npm install配置
环境变量
BASE_DIRECTORY：（可选）文件操作的基目录路径。如果未指定，则默认为files项目根目录中的目录。
目录结构
/files：文件操作的默认基目录/log：包含调试日志文件
用法
启动服务器
npm start对于自动重新加载的开发：
npm run dev服务器将运行并连接到标准输入/输出进行通信。
从聊天设置基本目录
此实现的关键功能之一是能够直接从聊天界面设置基本目录。这意味着您不需要重新启动服务器或修改配置文件来更改文件的存储和访问位置。
只需让AI助手设置基本目录，例如：
- “将基本目录设置为C:/Users/username/Documents”
- “将文件存储位置更改为/home/user/data”
助理将使用 set_base_directory 工具来更新位置。您可以随时通过询问当前基本目录来验证当前位置。
使用Git命令
服务器允许您直接从聊天界面执行Git命令。只需让AI助手运行一个git命令，例如：
- “运行git状态”
- “执行git日志--oneline”
- “使用git checkout-b feature/new feature创建一个新分支”
您还可以指定要使用的shell：
- 使用PowerShell，运行git status
- 在bash中，执行git diff
- 使用cmd运行git pull-origin main
配置对象示例
以下是将MCP文件服务器与Claude Desktop或Cursor集成的示例配置对象：
{
"mcpServers": {
"file-server": {
"command": "node",
"args": ["/path/to/mcp-file-server/mcp_server.js"],
"disabled": false,
"autoApprove": ["list_files", "read_file", "write_file", "delete_file", "set_base_directory", "get_base_directory", "git_command"]
}
}
}配置属性说明：
mcpServers：所有MCP服务器配置的容器file-server：此特定MCP服务器的唯一标识符command：要执行的命令（在这种情况下，node运行JavaScript文件）args：传递给命令的参数数组（服务器脚本的路径）disabled：此服务器当前是否已禁用（false=已启用）autoApprove：无需用户确认即可自动批准的工具列表
扩展服务器
模块化架构使服务器易于扩展新功能：
- 在中创建新服务
services/目录 - 将您的服务注册添加到
toolService.js文件 - 更新主
mcp_server.js用于初始化服务的文件
例如，要添加新的压缩服务：
- 创建
services/compressionService.js - 添加a
registerCompressionTools()方法totoolService.js - 更新主服务器以初始化压缩服务
api参考
set_base_directory
为文件操作设置新的基目录。
参数：
path：新基目录的绝对路径
退货：
- 确认消息
get_base_directory
获取当前基目录路径。
参数：
- 无
退货：
- 当前基本目录路径
列表文件
列出指定目录中的文件。
参数：
directory：（可选）列表的目录路径（默认为root）
退货：
- 格式化的文件和目录列表
read_file
读取文件的内容。
参数：
path：要读取的文件的路径
退货：
- 文件内容
write_file
将内容写入文件。
参数：
path：要写入的文件的路径content：要写入文件的内容
退货：
- 确认消息
删除文件
删除文件或目录。
参数：
path：要删除的文件或目录的路径
退货：
- 确认消息
git_命令
在基目录中执行git命令。
参数：
command：要执行的Git命令（不带“Git”前缀）shell：（可选）用于执行的Shell（cmd、powershell、bash）
退货：
- 命令输出（stdout和stderr）
故障排除
请检查以下位置的日志文件 log/mcp_debug.log 有关服务器操作和可能发生的任何错误的详细信息。
常见问题：
- 路径访问错误：确保BASE_DIRECTORY设置为进程有权访问的位置。
- 连接被拒绝：在尝试连接之前，请确保服务器正在运行。
- 未找到工具：验证配置中的工具名称是否与服务器中定义的名称完全匹配。
- 端口冲突：如果您正在运行多个MCP服务器，请确保它们使用不同的端口。
- 无效的基目录：从聊天设置基本目录时，请确保提供绝对路径（而不是相对路径）。
- Git命令错误：使用Git命令时，请确保已安装Git，并且基目录是有效的Git存储库。
贡献
我们欢迎为改进MCP文件服务器做出贡献！以下是您可以提供帮助的方式：
贡献方式
- 错误报告：提交详细的错误报告，并说明重现步骤
- 功能请求：建议新功能或改进
- 文档：帮助改进或扩展文档
- 代码贡献：提交带有错误修复或新功能的pull请求
开发过程
- 分叉存储库：创建自己的项目分支
- 创建分支：在新分支中进行更改
- 遵循编码标准：保持现有的代码样式
- 编写测试：添加新功能或错误修复的测试
- 文档：更新文档以反映您的更改
- 提交拉取请求：打开一个PR，清楚地描述变化
拉取请求指南
- 让PR专注于单一功能或错误修复
- 包括对更改内容及其原因的清晰描述
- 确保所有测试都通过
- 更新相关文件
报告问题
在报告问题时，请包括：
- 对问题的清晰描述
- 重现问题的步骤
- 预期行为与实际行为
- 环境详细信息（操作系统、Node.js版本等）
