File Operations MCP Server

文件操作MCP服务器

](https://smithery.ai/server/@bsmi021/mcp-file-operations-server)

一种模型上下文协议（MCP）服务器，提供增强的文件操作功能，支持流式传输、修补和更改跟踪。

特性

• 基本文件操作：复制、读取、写入、移动和删除文件
• 目录操作：创建、删除和复制目录
• 文件监视：监视文件和目录的更改
• 更改跟踪：跟踪和查询文件操作历史
• 流媒体支持：通过流媒体高效处理大文件
• HTTP接口：具有服务器发送事件（SSE）的流式HTTP接口
• 资源支持：通过MCP资源访问文件和目录
• 进度报告：长时间操作的实时进度更新
• 速率限制：防止过度请求
• 增强的安全性：路径验证和输入净化
• 稳健的错误处理：全面的错误处理和报告
• 类型安全：完全支持TypeScript，具有严格的类型检查
• Docker支持：具有卷装载的容器化部署

安装

通过Smithery安装

通过以下方式自动安装克劳德桌面文件操作服务器 史密瑟里:

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

手动安装

npm install

Docker安装

看 医生.md 获取全面的Docker设置说明，包括Windows和Linux的本地驱动器挂载。

Docker快速入门：

# Stdio transport (for MCP clients)
docker run -it --rm -v "$(pwd):/workspace" ghcr.io/bsmi021/mcp-file-operations-server

# HTTP transport (for web/remote access)
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http ghcr.io/bsmi021/mcp-file-operations-server

用法

运输方式

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

1.标准运输（默认）

对于与Claude Desktop等MCP客户端的直接集成：

npm start

2.使用SSE的HTTP传输（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 transport with auto-reload
npm run dev

# HTTP transport with auto-reload
npm run dev:http

生产模式

# Stdio transport
npm start

# HTTP transport
npm run start:http

# Custom port for 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}：列出目录内容

示例用法

使用标准传输（MCP客户端）

// Copy a file
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// Watch a directory
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// Access file contents through resource
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// Copy directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Progress token in result can be used to track progress
console.log(result.progressToken);

使用HTTP传输（Web/Remote）

通过JavaScript连接：

// Establish SSE connection
const eventSource = new EventSource('http://localhost:3001/sse');
let sessionId = null;

eventSource.onopen = function() {
    console.log('Connected to MCP server');
};

eventSource.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    // Extract session ID from first message
    if (!sessionId && message.sessionId) {
        sessionId = message.sessionId;
    }
    
    console.log('Received:', message);
};

// Send a message to the server
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();
}

// Example: List tools
sendMessage('tools/list', {});

// Example: Read a file
sendMessage('tools/call', {
    name: 'read_file',
    arguments: { path: '/workspace/example.txt' }
});

使用curl进行测试：

# Start SSE connection in background
curl -N http://localhost:3001/sse &

# Check server health
curl http://localhost:3001/health

# List active sessions
curl http://localhost:3001/sessions

交互式Web客户端：

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

v1.5的新增功能

MCP SDK v1.5升级

• 流式HTTP接口：带有服务器发送事件（SSE）的新HTTP传输
• 增强型API：升级到MCP SDK v1.5，改进了基于zod的模式
• 多个连接：支持通过会话管理同时进行HTTP连接
• 更好的类型安全性：改进了TypeScript集成和错误处理

流媒体功能

• 大文件支持：用于大文件操作的高效流媒体
• 实时进度：通过SSE更新长时间运行的进度
• 会话管理：具有隔离会话的多个客户端连接
• HTTP API：RESTful端点与传统MCP协议并存

Docker支持

Docker快速入门

# Build the image
docker build -t mcp-file-operations-server .

# Run with stdio (for MCP clients)
docker run -it --rm -v "$(pwd):/workspace" mcp-file-operations-server

# Run with HTTP interface
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http mcp-file-operations-server

数据载体安装

窗户：

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

有关全面的Docker设置说明，包括Windows和Linux的本地驱动器挂载，请参阅 医生.md.

速率限制

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

• 工具：每分钟100个请求
• 资源：每分钟200个请求
• 观察操作：每分钟20次操作

速率限制错误包括在错误消息中的句点后重试。

安全功能

路径验证

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

• 没有父目录引用(../)
• 正确的路径规范化
• 输入净化

资源保护

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

进度报告

目录复制等长时间运行的操作提供进度更新：

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

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

发展

建筑

npm run build

掉毛

npm run lint

格式化

npm run format

测试

npm test

配置

环境变量

运输选择

• 工作室：最适合Claude Desktop等MCP客户，直接集成
• 超文本传输协议：最适合web应用程序、远程访问、开发/测试

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

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

错误处理

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

标准MCP错误代码

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

自定义错误类型

• 文件操作失败
• 请求频率超限
• 路径验证错误
• 资源访问错误

每个错误包括：

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

贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。