文件操作MCP服务器
一种模型上下文协议（MCP）服务器，提供增强的文件操作功能，支持流式传输、修补和更改跟踪。
特性
- 基本文件操作：复制、读取、写入、移动和删除文件
- 目录操作：创建、删除和复制目录
- 文件监视：监视文件和目录的更改
- 更改跟踪：跟踪和查询文件操作历史
- 流媒体支持：通过流媒体高效处理大文件
- HTTP接口：具有服务器发送事件（SSE）的流式HTTP接口
- 资源支持：通过MCP资源访问文件和目录
- 进度报告：长时间操作的实时进度更新
- 速率限制：防止过度请求
- 增强的安全性：路径验证和输入净化
- 稳健的错误处理：全面的错误处理和报告
- 类型安全：完全支持TypeScript，具有严格的类型检查
- Docker支持：具有卷装载的容器化部署
安装
通过Smithery安装
通过以下方式自动安装克劳德桌面文件操作服务器 史密瑟里:
npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude手动安装
npm installDocker安装
看 医生.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 start2.使用SSE的HTTP传输（v1.5中的新功能）
对于远程连接和web应用程序：
npm run start:httpHTTP服务器提供：
- 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-serverLinux/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配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_TRANSPORT | stdio | 运输方式： stdio 或 http |
MCP_HTTP_PORT | 3001 | HTTP传输端口 |
运输选择
- 工作室：最适合Claude Desktop等MCP客户，直接集成
- 超文本传输协议：最适合web应用程序、远程访问、开发/测试
服务器可以通过各种设置进行配置：
- 速率限制：配置请求限制和窗口
- 进度报告：控制更新频率和详细程度
- 资源访问：配置资源权限和限制
- 安全设置：配置路径验证规则
- 更改跟踪：设置保留期和存储选项
- 观看设置：配置去抖动时间和递归监视
错误处理
服务器通过提供详细的错误信息 FileOperationError 类和MCP错误代码：
标准MCP错误代码
InvalidRequest：参数或请求格式无效MethodNotFound：请求的工具或资源未知InvalidParams：无效参数（例如，路径验证失败）InternalError：服务器端错误
自定义错误类型
- 文件操作失败
- 请求频率超限
- 路径验证错误
- 资源访问错误
每个错误包括：
- 特定错误代码
- 详细错误消息
- 相关元数据（文件路径、限制等）
- 开发模式下的堆栈跟踪
贡献
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。