文件操作 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

使用说明

功能概述

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

使用示例

1. 创建新文件：

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

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

2. 复制文件：

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

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

3. 读取文件内容：

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 文件。