🚀 文件操作 MCP 服务器

一个提供增强文件操作功能的模型上下文协议（MCP）服务器，支持流式传输、补丁处理和变更跟踪，能有效提升文件操作的效率与安全性。

🚀 快速开始

此 MCP 服务器提供了增强的文件操作功能，支持流式传输、补丁处理和变更跟踪等。以下将为你介绍其安装和使用方法。

✨ 主要特性

• 基本文件操作：支持复制、读取、写入、移动和删除文件等常规操作。
• 目录操作：可创建、移除和复制目录，方便进行目录管理。
• 文件监控：能监视文件和目录的变更，及时掌握文件状态。
• 变更跟踪：可跟踪和查询文件操作历史记录，便于追溯操作。
• 流式支持：能高效处理大文件，提供高效分块传输。
• 资源访问：可通过 MCP 资源访问文件和目录。
• 进度报告：长操作可实时进行进度更新。
• 速率限制：防止过多请求，保护服务器稳定运行。
• 增强安全性：进行路径验证和输入清理，保障操作安全。
• robust 错误处理：具备全面的错误处理和报告机制。
• 类型安全：拥有完整的 TypeScript 支持，带有严格的类型检查。

📦 安装指南

通过史密斯ery 安装

1. 访问 https://smithery.ai/
2. 登录并导航至“工作区”。
3. 点击“从代码库创建新工作区”。
4. 在 URL 栏输入仓库地址：git+ssh://github.com/bsmi021/mcp-file-operations-server.git
5. 完成工作区设置后，点击“创建”。

手动安装

1. 克隆此仓库：

git clone git@github.com:bsmi021/mcp-file-operations-server.git
cd mcp-file-operations-server

2. 安装依赖项：

npm install

3. 启动服务器：

node src/index.js

💻 使用示例

功能概述

• 文件操作：支持复制、移动、读取和写入文件。
• 目录管理：可创建、删除和遍历目录结构。
• 变更跟踪：能记录和检索文件变更历史。
• 流式传输：处理大文件时提供高效分块传输。

基础用法

创建新文件

POST /operations/create-file
Content-Type: application/json

{
  "path": "example.txt",
  "content": "Hello, World!"
}

复制文件

POST /operations/copy-file
Content-Type: application/json

{
  "sourcePath": "example.txt",
  "destinationPath": "copy_example.txt"
}

读取文件内容

GET /operations/read-file?path=example.txt

📚 详细文档

项目结构

1. 核心模块

   • file-system：处理文件和目录的基本操作。
   • operations：包含各种文件操作工具。
   • resources：定义可访问的资源接口。

2. 日志系统

// 配置日志记录器
const logger = require('mcp-logger');

// 记录不同级别的日志信息
logger.debug("调试信息");
logger.info("一般信息");
logger.warn("警告信息");
logger.error("错误信息");

依赖管理

项目使用 npm 进行依赖管理，主要依赖包括：

• express：Web 服务器框架。
• mcp-core：MCP 协议核心库。
• fs-extra：增强的文件系统操作。

错误处理

标准错误代码

1. InvalidRequest：请求格式或参数无效
2. MethodNotFound：请求的工具或资源不存在
3. InvalidParams：参数验证失败（如路径无效）
4. InternalError：服务器内部错误

自定义错误类型

• 文件操作失败
• 速率限制超出
• 路径验证错误
• 资源访问错误

每个错误都包含详细的上下文信息，包括错误代码、具体消息和相关元数据。

配置选项

通过 config.json 定义服务器行为：

{
  "rateLimits": {
    "requestsPerMinute": 100,
    "windowMs": 60000
  },
  "progressReporting": {
    "updateInterval": 1000,
    "detailLevel": "high"
  }
}

贡献指南

1. 参与项目：查看 Issues 找到适合的任务。
2. 提交代码：
   • 创建功能分支：git checkout -b feature/amazing-feature
   • 提交变更：git commit -m '添加 amazing 功能'
   • 推送到远程仓库：git push origin feature/amazing-feature
3. 创建拉取请求：前往 Pull Requests 提交您的贡献。

📄 许可证

本项目遵循 MIT 许可证，具体内容请参阅 LICENSE 文件。