local-file-operation-mcp

# 本地文件操作 MCP 服务器 v2.0.1 一个功能强大的 MCP (Model Context Protocol) 服务器，为大模型应用提供安全的本地文件操作、行级编辑、文件搜索、文件比较、文件哈希、文件权限、文件压缩、文件监控、命令执行和任务管理功能。 ## ✨ 功能特性 ### 📁 文件操作工具 - **读取文件** - 安全读取本地文件内容 - **写入文件** - 创建或更新文件内容 - **列出目录** - 查看目录结构和文件列表 - **创建目录** - 创建新的目录结构 - **删除文件/目录** - 安全删除文件和目录 ### ✏️ 文件编辑工具 (v1.1.0 新增) - **删除行** - 删除指定行号范围的内容 - **插入行** - 在指定位置插入新内容 - **替换行** - 替换指定行号范围的内容 - **追加行** - 在文件末尾追加新内容 ### 🔍 文件搜索工具 (v1.2.0 新增) - **内容搜索** - 在文件中搜索指定内容 - **正则表达式** - 支持正则表达式搜索 - **文件类型过滤** - 按文件类型过滤搜索结果 - **大小写控制** - 支持区分/不区分大小写搜索 ### 📊 文件比较工具 (v1.2.0 新增) - **差异对比** - 比较两个文件的差异 - **行级对比** - 显示具体的行级差异 - **多种输出格式** - 支持文本和JSON格式输出 ### 🔐 文件哈希工具 (v1.2.0 新增) - **多种算法** - 支持MD5、SHA1、SHA256、SHA512 - **文件完整性** - 验证文件完整性 - **快速计算** - 高效的文件哈希计算 ### 🛡️ 文件权限工具 (v1.2.0 新增) - **权限修改** - 修改文件权限 - **递归应用** - 支持递归应用权限 - **权限显示** - 显示详细的权限信息 ### 📦 文件压缩工具 (v1.2.0 新增) - **多种格式** - 支持ZIP、TAR、GZ、TAR.GZ格式 - **压缩解压** - 支持压缩和解压操作 - **批量处理** - 支持目录批量压缩 ### 👁️ 文件监控工具 (v1.2.0 新增) - **实时监控** - 监控文件变化 - **事件类型** - 支持创建、删除、修改事件 - **定时监控** - 可设置监控时长 ### 📋 任务管理工具 (v2.0.1 新增) - **任务分解** - 支持创建复杂任务和子任务 - **优先级管理** - 支持低、中、高、紧急四个优先级 - **进度跟踪** - 实时跟踪任务完成进度 - **排期管理** - 支持设置截止日期 - **状态管理** - 待处理、进行中、已完成、已取消 - **模型隔离** - 不同模型拥有独立的任务列表 ### ⚡ 命令执行工具 - **执行本地命令** - 在指定工作目录下执行系统命令 - **安全限制** - 自动过滤危险命令，保护系统安全 ### 🔒 安全特性 ### 🕒 时间工具 (v2.0.2 新增) - **当前时间** - 获取当前真实时间 - **多种格式** - ISO、RFC3339、UNIX(秒/毫秒)、本地格式 - **时区支持** - 指定 IANA 时区（如 `Asia/Shanghai`） - **路径限制** - 禁止访问敏感系统目录 - **命令过滤** - 阻止执行危险的系统命令 - **权限控制** - 确保操作在安全范围内 ## 🚀 快速开始 ### 环境要求 - Node.js >= 18.0.0 - npm 或 yarn ### 安装依赖 ```bash cd /Users/abc/research/mcp npm install ``` ## 📋 配置说明 ### LM Studio 配置 ```json { "mcpServers": { "file_operation": { "command": "/Users/abc/.nvm/versions/node/v22.16.0/bin/node", "args": ["/Users/abc/research/mcp/index.js"], "env": { "PATH": "/Users/abc/.nvm/versions/node/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin", "NODE_PATH": "/Users/abc/research/mcp" } } } } ### 注意这里的 "/Users/abc/research/mcp" 是下载到的文件夹的位置.要改成自己的路径. ``` ### Qwen 配置 ```json { "mcpServers": { "file_operation": { "command": "npx", "args": [ "-y", "local-file-operation-mcp@file:/Users/abc/research/mcp" ] } } } ### 注意这里的 "local-file-operation-mcp@file:/Users/abc/research/mcp" @file: 后面是下载到的文件夹的位置.要改成自己的路径. ``` ## 🛠️ 工具使用 ### 文件操作工具 #### 工作目录概念为了安全性和灵活性，MCP服务器支持工作目录概念： - **工作目录**：通过 `working_directory` 参数指定一个安全的基础目录 - **相对路径**：在 `path` 参数中使用相对路径，会自动基于工作目录解析 - **智能检测**：自动识别常见的项目目录模式，支持直接使用绝对路径 - **安全限制**：只有在允许的项目目录下的操作才被允许 - **跨平台兼容**：不硬编码特定路径，适用于不同用户和系统 #### 允许的项目目录模式系统自动识别以下目录模式，允许直接使用绝对路径： - `/isoftstone/` - 项目目录 - `/Desktop/` - 桌面 - `/Documents/` - 文档 - `/Downloads/` - 下载 - `/Projects/` - 项目 - `/Workspace/` - 工作空间 - `/Code/` - 代码 - `/Development/` - 开发 - `/Work/` - 工作 - `/Study/` - 学习 - `/Research/` - 研究 #### 读取文件 ```json { "name": "file_operation", "arguments": { "operation": "read", "path": "/path/to/file.txt" } } ``` #### 写入文件 ```json { "name": "file_operation", "arguments": { "operation": "write", "path": "/path/to/file.txt", "content": "文件内容" } } ``` #### 列出目录 ```json { "name": "file_operation", "arguments": { "operation": "list", "path": "/path/to/directory" } } ``` #### 创建目录 ```json { "name": "file_operation", "arguments": { "operation": "create_dir", "path": "/path/to/new/directory" } } ``` #### 使用工作目录（推荐） ```json { "name": "file_operation", "arguments": { "operation": "create_dir", "path": "售前类业务/自动HMI", "working_directory": "/Users/abc/isoftstone" } } ``` #### 删除文件/目录 ```json { "name": "file_operation", "arguments": { "operation": "delete", "path": "/path/to/file_or_directory" } } ``` ### 文件编辑工具 #### 删除行 ```json { "name": "file_edit", "arguments": { "operation": "delete_lines", "path": "/path/to/file.txt", "start_line": 3, "end_line": 5 } } ``` #### 插入行 ```json { "name": "file_edit", "arguments": { "operation": "insert_lines", "path": "/path/to/file.txt", "start_line": 3, "content": "新插入的内容" } } ``` #### 替换行 ```json { "name": "file_edit", "arguments": { "operation": "replace_lines", "path": "/path/to/file.txt", "start_line": 3, "end_line": 5, "content": "替换后的内容" } } ``` #### 追加行 ```json { "name": "file_edit", "arguments": { "operation": "append_lines", "path": "/path/to/file.txt", "content": "追加到文件末尾的内容" } } ``` ### 命令执行工具 #### 执行命令 ```json { "name": "execute_command", "arguments": { "command": "ls -la", "working_directory": "/path/to/working/dir" } } ``` ### 文件搜索工具 #### 搜索文件内容 ```json { "name": "file_search", "arguments": { "search_path": "/path/to/search", "pattern": "function.*\\(", "file_types": "js,ts", "case_sensitive": false, "max_results": 50 } } ``` ### 文件比较工具 #### 比较两个文件 ```json { "name": "file_compare", "arguments": { "file1": "/path/to/file1.txt", "file2": "/path/to/file2.txt", "output_format": "text" } } ``` ### 文件哈希工具 #### 计算文件哈希 ```json { "name": "file_hash", "arguments": { "path": "/path/to/file.txt", "algorithm": "sha256" } } ``` ### 文件权限工具 #### 修改文件权限 ```json { "name": "file_permissions", "arguments": { "path": "/path/to/file.txt", "mode": "755", "recursive": false } } ``` ### 文件压缩工具 #### 压缩文件 ```json { "name": "file_archive", "arguments": { "operation": "compress", "source": "/path/to/source", "destination": "/path/to/archive.zip", "format": "zip" } } ``` #### 解压文件 ```json { "name": "file_archive", "arguments": { "operation": "extract", "source": "/path/to/archive.zip", "destination": "/path/to/extract" } } ``` ### 文件监控工具 #### 监控文件变化 ```json { "name": "file_watch", "arguments": { "path": "/path/to/watch", "events": "create,delete,modify", "duration": 60, "output_format": "text" } } ``` ### 任务管理工具 ### 时间工具 #### 获取当前时间（ISO，含毫秒） ```json { "name": "time_tool", "arguments": { "format": "iso", "include_milliseconds": true } } ``` #### 获取 UNIX 时间戳（秒） ```json { "name": "time_tool", "arguments": { "format": "unix" } } ``` #### 获取本地时间并指定时区 ```json { "name": "time_tool", "arguments": { "format": "locale", "time_zone": "Asia/Shanghai", "include_milliseconds": false } } ``` #### 创建任务 ```json { "name": "task_manager", "arguments": { "operation": "create", "model_name": "claude-3.5-sonnet", "title": "完成项目文档", "description": "编写API文档和使用说明", "priority": "high", "due_date": "2024-01-15T10:00:00Z", "subtasks": ["编写API文档", "创建使用示例", "更新README"] } } ``` #### 列出任务 ```json { "name": "task_manager", "arguments": { "operation": "list", "model_name": "claude-3.5-sonnet", "status": "pending" } } ``` #### 更新任务 ```json { "name": "task_manager", "arguments": { "operation": "update", "model_name": "claude-3.5-sonnet", "task_id": "task_1758140089301_bi4kwqkcl", "status": "in_progress", "progress": 50 } } ``` #### 完成任务 ```json { "name": "task_manager", "arguments": { "operation": "complete", "model_name": "claude-3.5-sonnet", "task_id": "task_1758140089301_bi4kwqkcl" } } ``` ## 🔧 工作原理 ### MCP 协议通信 1. **大模型应用启动** - 根据配置自动启动 MCP 服务器进程 2. **建立连接** - 通过 stdio 协议建立通信连接 3. **工具发现** - 大模型应用发送 `ListTools` 请求获取可用工具 4. **工具调用** - 当需要文件操作时，发送工具调用请求 5. **自动管理** - 大模型应用负责管理 MCP 服务器的生命周期 ### 安全机制 - **路径检查** - 禁止访问 `/`, `/Users/<username>`, `/etc`, `/bin` 等敏感目录 - **命令过滤** - 阻止执行 `rm -rf`, `sudo`, `chmod 777` 等危险命令 - **权限验证** - 确保所有操作在安全范围内 ## 📁 项目结构 ``` mcp/ ├── index.js # MCP 服务器主文件 ├── package.json # Node.js 项目配置 ├── mcp_config.json # LM Studio 配置 ├── qwen_config_final.json # Qwen 配置 ├── mcp_config_template.json # 配置模板 ├── tools/ # 工具模块目录 │ ├── fileOperation.js # 文件操作工具 │ ├── fileEdit.js # 文件编辑工具 │ ├── fileSearch.js # 文件搜索工具 │ ├── fileCompare.js # 文件比较工具 │ ├── fileHash.js # 文件哈希工具 │ ├── filePermissions.js # 文件权限工具 │ ├── fileArchive.js # 文件压缩工具 │ ├── fileWatch.js # 文件监控工具 │ ├── commandExecution.js # 命令执行工具 │ ├── taskManager.js # 任务管理工具 │ └── securityValidator.js # 安全验证模块 ├── temps/ # 临时文件目录（自动创建） │ └── todo_<model_name>.json # 任务数据存储（运行时生成） ├── share4u.md # 中文分享文档 ├── share4u_en.md # 英文分享文档 ├── share4u_jp.md # 日文分享文档 └── README.md # 项目文档 ``` ## 🎯 支持的大模型应用 - ✅ **LM Studio** - 使用直接 node 执行 - ✅ **Qwen** - 使用 npx 本地包 - ✅ **其他支持 MCP 协议的应用** ## 🔍 故障排除 ### 常见问题 1. **连接失败** - 检查 Node.js 路径和文件权限 2. **工具不可用** - 确认 MCP 服务器正常启动 3. **权限错误** - 检查文件系统权限 ### 调试方法 1. **手动测试** - 运行 `npx -y local-file-operation-mcp@file:/Users/abc/research/mcp` 2. **检查日志** - 查看大模型应用的错误日志 3. **验证配置** - 确认配置文件格式正确 ## 📄 许可证 MIT License ## 🤝 贡献欢迎提交 Issue 和 Pull Request！ --- **享受强大的本地文件操作能力！** 🚀✨ --- ## 📦 安装与使用（无需下载源码）支持通过 npm 全局安装或直接使用 npx 运行，无需手动克隆仓库或修改本地路径。 ### 全局安装 ```bash npm install -g local-file-operation-mcp ``` 安装后，可在支持 MCP 的客户端中直接引用可执行文件 `local-file-operation-mcp`。 ### 直接使用 npx 无需安装，直接启动： ```bash npx -y local-file-operation-mcp ``` ### 在 LM Studio 中使用将可执行文件设置为 `local-file-operation-mcp`（无需绝对路径）： ```json { "mcpServers": { "file_operation": { "command": "local-file-operation-mcp" } } } ``` ### 在 Qwen 中使用使用 npx 直接调用（无需本地源码路径）： ```json { "mcpServers": { "file_operation": { "command": "npx", "args": ["-y", "local-file-operation-mcp"] } } } ``` > 提示：若公司网络限制 npm，亦可发布到 GitHub Packages 或设置内部 npm 镜像，详见 `dev.md` 发布章节。