MCP文件操作服务器

Name: MCP文件操作服务器
Author: bsmi021

作者：bsmi02119 星标更新：2025-07-11

安装使用来源：spider==github.com

项目介绍

文件操作MCP服务器

这是一个提供增强文件操作能力的Model Context Protocol (MCP)服务器，支持流式传输、补丁更新和变更追踪。

功能

基本文件操作：复制、读取、写入、移动和删除文件
目录操作：创建、移除和复制目录
文件监控：监控文件和目录的变化
变更追踪：跟踪和查询文件操作历史
流式支持：高效处理大文件的流式传输
HTTP接口：支持Server-Sent Events (SSE)的流式HTTP接口
资源访问：通过MCP资源访问文件和目录
进度报告：长时间操作的实时进度更新
速率限制：防止过多请求的保护机制
增强安全：路径验证和输入清理
健壮错误处理：全面的错误处理和报告
类型安全：完整的TypeScript支持和严格的类型检查
Docker支持：带有卷挂载的容器化部署

安装

通过Smithery安装

要通过Smithery自动安装文件操作服务器到Claude桌面：

npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude

手动安装

npm install

Docker安装

参见DOCKER.md，了解包括Windows和Linux本地驱动挂载在内的综合Docker设置指南。

快速Docker启动：

# Stdio传输（适用于MCP客户端）
docker run -it --rm -v "$(pwd):/workspace" ghcr.io/bsmi021/mcp-file-operations-server

# HTTP传输（适用于web/远程访问）
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http ghcr.io/bsmi021/mcp-file-operations-server

使用

传输模式

服务器支持两种传输模式：

1. Stdio传输（默认）

用于与Claude桌面等MCP客户端直接集成：

npm start

2. HTTP传输带SSE（v1.5新功能）

用于远程连接和web应用：

npm run start:http

HTTP服务器提供：

SSE端点：GET http://localhost:3001/sse - 建立流式连接
消息端点：POST http://localhost:3001/messages - 接收客户端消息
健康检查：GET http://localhost:3001/health - 服务器状态
会话：GET http://localhost:3001/sessions - 活跃连接信息

启动服务器

开发模式

# Stdio传输带自动重载
npm run dev

# HTTP传输带自动重载
npm run dev:http

生产模式

# Stdio传输
npm start

# HTTP传输
npm run start:http

# 自定义HTTP端口
npm run start:http -- --port 8080

可用工具

基本文件操作

copy_file：将文件复制到新位置
read_file：从文件中读取内容
write_file：向文件写入内容
move_file：移动/重命名文件
delete_file：删除文件
append_file：追加内容到文件

目录操作

make_directory：创建目录
remove_directory：移除目录
copy_directory：递归复制目录（带进度报告）

监控操作

watch_directory：开始监控目录变化
unwatch_directory：停止监控目录

变更追踪

get_changes：获取记录的变更列表
clear_changes：清除所有记录的变更

可用资源

静态资源

file:///recent-changes：最近的文件系统变更列表

资源模板

file://{path}：访问文件内容
metadata://{path}：访问文件元数据
directory://{path}：列出目录内容

示例使用

使用Stdio传输（MCP客户端）

// 复制文件
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// 监控目录
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// 通过资源访问文件内容
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// 带进度报告的目录复制
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// 结果中的进度令牌可用于跟踪进度
console.log(result.progressToken);

使用HTTP传输（Web/远程）

通过JavaScript连接：

// 建立SSE连接
const eventSource = new EventSource('http://localhost:3001/sse');
let sessionId = null;

eventSource.onopen = function() {
    console.log('已连接到MCP服务器');
};

eventSource.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    // 从第一条消息中提取会话ID
    if (!sessionId && message.sessionId) {
        sessionId = message.sessionId;
    }
    
    console.log('收到：', message);
};

// 向服务器发送消息
async function sendMessage(method, params) {
    const message = {
        jsonrpc: '2.0',
        id: Date.now(),
        method: method,
        params: params
    };
    
    const response = await fetch('http://localhost:3001/messages', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-Session-ID': sessionId
        },
        body: JSON.stringify(message)
    });
    
    return response.json();
}

// 示例：列出工具
sendMessage('tools/list', {});

// 示例：读取文件
sendMessage('tools/call', {
    name: 'read_file',
    arguments: { path: '/workspace/example.txt' }
});

使用curl进行测试：

# 在后台启动SSE连接
curl -N http://localhost:3001/sse &

# 检查服务器健康状况
curl http://localhost:3001/health

# 列出活跃会话
curl http://localhost:3001/sessions

交互式Web客户端：

一个完整的交互示例在examples/http-client.html中可用。在浏览器中打开此文件以使用用户友好的GUI测试HTTP接口。

v1.5的新特性

MCP SDK v1.5升级

流式HTTP接口：新的HTTP传输带Server-Sent Events (SSE)
增强API：升级到MCP SDK v1.5，改进了基于zod的模式
多连接支持：支持同时HTTP连接和会话管理
更好的类型安全：改进的TypeScript集成和错误处理

流式特性

大文件支持：大文件操作的高效流式传输
实时进度：通过SSE为长时间运行的操作提供进度更新
会话管理：多个客户端连接和隔离会话
HTTP API：传统的MCP协议之外的RESTful端点

Docker支持

使用Docker快速启动

# 构建镜像
docker build -t mcp-file-operations-server .

# 运行带stdio（适用于MCP客户端）
docker run -it --rm -v "$(pwd):/workspace" mcp-file-operations-server

# 运行带HTTP接口
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http mcp-file-operations-server

卷挂载

Windows:

docker run -it --rm -v "C:\MyProject:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server

Linux/macOS:

docker run -it --rm -v "/home/user/project:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server

对于包括Windows和Linux本地驱动挂载在内的综合Docker设置指南，请参见DOCKER.md。

速率限制

服务器实现速率限制以防止滥用：

工具：每分钟100次请求
资源：每分钟200次请求
监控操作：每分钟20次操作

速率限制错误包含错误消息中的重试时间。

安全特性

路径验证

所有文件路径都经过验证，以防止目录遍历攻击：

不允许父目录引用（../）
正确的路径规范化
输入清理

资源保护

对所有操作进行速率限制
正确的错误处理和日志记录
对所有参数进行输入验证
安全的资源清理

进度报告

长时间操作如目录复制提供进度更新：

interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}

可以通过操作结果返回的进度令牌来跟踪进度。

开发

构建

npm run build

代码检查

npm run lint

格式化

npm run format

测试

npm test

配置

环境变量

变量	默认值	描述
`MCP_TRANSPORT`	`stdio`	传输模式：`stdio`或`http`
`MCP_HTTP_PORT`	`3001`	HTTP传输端口

传输选择

Stdio：适用于MCP客户端如Claude桌面，直接集成
HTTP：适用于web应用，远程访问，开发/测试

服务器可以通过各种设置进行配置：

速率限制：配置请求限制和窗口
进度报告：控制更新频率和详细程度
资源访问：配置资源权限和限制
安全设置：配置路径验证规则
变更追踪：设置保留周期和存储选项
监控设置：配置防抖时间和递归监控

错误处理

服务器通过FileOperationError类和MCP错误码提供详细的错误信息：

标准MCP错误码

InvalidRequest：无效参数或请求格式
MethodNotFound：未知的工具或资源请求
InvalidParams：无效参数（例如，路径验证失败）
InternalError：服务器端错误

自定义错误类型

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

每个错误包括：

特定的错误码
详细的错误消息
相关的元数据（文件路径、限制等）
开发模式下的堆栈跟踪

贡献

分叉仓库
创建你的功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m '添加惊人的功能'）
推送到分支（git push origin feature/amazing-feature）
打开Pull Request

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。