MCP File Server

MCP File Server

一个安全的文件服务实现，使用 Model Context Protocol（MCP）为文件系统操作提供标准化接口。

概述

MCP File Server 是一个 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 功能）

安装

1. 克隆此代码库：

   git clone <repository-url>
   cd mcp-file-server
   

2. 安装依赖：

   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 status”
• “执行 git log --oneline”
• “使用 git checkout -b feature/new-feature 创建一个新分支”

你还可以指定要使用的 Shell：

• “使用 PowerShell 运行 git status”
• “在 bash 中执行 git diff”
• “使用 cmd 运行 git pull origin main”

配置对象示例

下面是将 MCP File Server 与 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：无需用户确认即可自动批准的工具列表

扩展服务器

模块化架构让你可以轻松为服务器添加新功能：

1. 在 services/ 目录中创建新服务
2. 在 toolService.js 文件中添加服务注册
3. 更新主 mcp_server.js 文件以初始化你的服务

例如，要添加新的压缩服务：

• 创建 services/compressionService.js
• 在 toolService.js 中添加 registerCompressionTools() 方法
• 更新主服务器以初始化压缩服务

API 参考

set_base_directory

设置文件操作的新基础目录。

参数：

• path：新基础目录的绝对路径

返回：

• 确认消息

get_base_directory

获取当前基础目录路径。

参数：

• 无

返回：

• 当前基础目录路径

list_files

列出指定目录中的文件。

参数：

• directory：（可选）要列出的目录路径（默认为根目录）

返回：

• 格式化的文件和目录列表

read_file

读取文件内容。

参数：

• path：要读取的文件路径

返回：

• 文件内容

write_file

将内容写入文件。

参数：

• path：要写入的文件路径
• content：要写入文件的内容

返回：

• 确认消息

delete_file

删除文件或目录。

参数：

• path：要删除的文件或目录路径

返回：

• 确认消息

git_command

在基础目录中执行 git 命令。

参数：

• command：要执行的 Git 命令（不包含 git 前缀）
• shell：（可选）要用于执行的 Shell（cmd、powershell、bash）

返回：

• 命令输出（stdout 和 stderr）

故障排除

查看 log/mcp_debug.log 日志文件，了解服务器操作的详细信息以及可能发生的错误。

常见问题：

1. 路径访问错误：确保 BASE_DIRECTORY 设置为进程有权限访问的位置。
2. 连接被拒绝：请确保服务器正在运行，然后再尝试连接。
3. 找不到工具：确认配置中的工具名称与服务器中定义的名称完全一致。
4. 端口冲突：如果运行多个 MCP 服务器，请确保它们使用不同的端口。
5. 基础目录无效：通过聊天设置基础目录时，请确保提供绝对路径（而非相对路径）。
6. Git 命令错误：使用 Git 命令时，请确保已安装 Git，且基础目录是有效的 Git 仓库。

贡献

欢迎为改进 MCP File Server 做出贡献！以下是你可以提供帮助的方式：

贡献方式

• 错误报告：提交包含复现步骤的详细错误报告
• 功能请求：提出新功能或改进建议
• 文档：帮助改进或扩展文档
• 代码贡献：提交包含错误修复或新功能的拉取请求

开发流程

1. Fork 仓库：创建项目的个人 Fork
2. 创建分支：在新分支中进行更改
3. 遵循编码规范：保持现有代码风格
4. 编写测试：为新功能或错误修复添加测试
5. 文档：更新文档以反映所做的更改
6. 提交拉取请求：创建 PR，并清晰描述所做的更改

拉取请求指南

• 每个 PR 只针对一项功能或一项错误修复
• 清晰说明更改内容及原因
• 确保所有测试均通过
• 更新相关文档

报告问题

报告问题时，请包含：

• 对问题的清晰描述
• 问题的复现步骤
• 预期行为与实际行为
• 环境详情（操作系统、Node.js 版本等）