File Operations MCP Server

File Operations MCP 服务

一种 Model Context Protocol（MCP）服务，提供增强的文件操作功能，并支持流式处理、补丁和更改跟踪。

功能

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

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 File Operations Server：

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

手动安装

npm install

Docker 安装

请参阅 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. Stdio 传输（默认）

用于与 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}：列出目录内容

使用示例

使用 Stdio 传输（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/远程）

通过 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：在传统 MCP 协议之外提供 RESTful 端点

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

卷挂载

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

如需了解完整的 Docker 设置说明，包括如何在 Windows 和 Linux 上挂载本地驱动器，请参阅 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：最适合 Claude Desktop 等 MCP 客户端，以及直接集成
• HTTP：最适合 Web 应用、远程访问和开发／测试

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

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

错误处理

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

标准 MCP 错误代码

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

自定义错误类型

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

每个错误都包含：

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

贡献

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 将更改推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。