STARWARCLOUD STARWAR.AI
返回市场
文件系统服务器

文件系统服务器

作者：yinzhouzhi4 星标更新：2025-04-26
安装使用来源：spider==github.com

项目介绍

MCP文件系统服务器

版本 许可证 node版本

基于模型上下文协议（MCP）的文件系统操作服务器，提供对本地文件系统的访问和操作能力。

目录

功能特性

  • ✅ 基于MCP SDK实现，符合MCP规范
  • 📂 提供完整的文件操作能力：读/写、复制、移动、删除等
  • 📁 支持目录操作：创建、删除、列出等
  • 📝 支持文件内容行级操作：读写特定行、搜索内容等
  • 👀 支持文件监控：监听文件和目录的变化
  • 🔄 通过标准输入输出(STDIO)通信易于集成
  • 🛠️ 包含命令行工具，便于直接使用
  • 📊 高性能设计：缓存机制、流处理、异步操作

光标

{
    "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": [
            "-y",
            "@yinzhouzhi/mcp-filesystem-server",
            "start"
          ],
          "autoConnect": true
        },
    }
}

安装

# 全局安装
npm install -g @yinzhouzhi/mcp-filesystem-server

# 或者局部安装到项目
npm install --save @yinzhouzhi/mcp-filesystem-server

# 无需安装，直接通过npx使用
npx @yinzhouzhi/mcp-filesystem-server <命令>

命令行使用

基本命令

# 启动服务器
mcp-filesystem-server start

# 查看帮助
mcp-filesystem-server --help

# 列出所有可用工具
mcp-filesystem-server list-tools

# 查看连接示例
mcp-filesystem-server example

使用NPX（无需安装）

# 启动服务器
npx @yinzhouzhi/mcp-filesystem-server start

# 查看帮助
npx @yinzhouzhi/mcp-filesystem-server --help

# 列出所有可用工具
npx @yinzhouzhi/mcp-filesystem-server list-tools

启动选项

选项:
  -d, --debug              启用调试模式
  -l, --log-level <level>  设置日志级别 (debug, info, warn, error) (默认: "info")
  -p, --log-path <path>    设置日志文件路径 (默认: 当前目录下的logs文件夹)
  -r, --rotation-type <type> 设置日志轮转类型 (size, daily, weekly, monthly) (默认: "size")
  -s, --max-size <size>    设置日志文件最大大小 (如 10MB) (默认: 10MB)
  -f, --max-files <num>    设置保留的轮转日志文件数量 (默认: 5)
  --no-rotate              禁用日志轮转
  --no-compress            禁用轮转日志压缩
  -h, --help               显示帮助信息

编程方法使用

作为服务器启动

const { startServer } = require('@yinzhouzhi/mcp-filesystem-server');

// 启动服务器
startServer({
  debug: true,
  logLevel: 'debug',
  logPath: './logs/server.log',
  // 日志轮转配置
  rotateLogFiles: true,             // 是否启用日志轮转
  rotationType: 'daily',            // 轮转类型: 'size', 'daily', 'weekly', 'monthly'
  maxLogFileSize: 20 * 1024 * 1024, // 按大小轮转时的最大文件大小 (20MB)
  maxLogFiles: 10,                  // 保留的轮转日志文件数量
  compressRotatedLogs: true         // 是否压缩轮转后的日志文件
}).then(result => {
  console.log('服务器启动成功:', result);
}).catch(err => {
  console.error('服务器启动失败:', err);
});

连接到MCP服务器

const { McpClient } = require('@modelcontextprotocol/sdk/client/mcp.js');
const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
const { spawn } = require('child_process');

async function connectToMcpServer() {
  // 启动MCP服务器进程
  const serverProcess = spawn('mcp-filesystem-server', ['start'], {
    stdio: ['pipe', 'pipe', 'pipe']
  });
  
  // 创建STDIO传输
  const transport = new StdioClientTransport({
    input: serverProcess.stdout,
    output: serverProcess.stdin,
    error: serverProcess.stderr
  });
  
  // 创建客户端
  const client = new McpClient();
  await client.connect(transport);
  
  // 调用工具示例
  const result = await client.invokeTool('read_file', {
    path: './example.txt',
    encoding: 'utf8'
  });
  
  console.log('文件内容:', result);
  
  // 关闭连接
  await client.disconnect();
  serverProcess.kill();
}

connectToMcpServer().catch(console.error);

通过NPX连接到MCP服务器

const { spawn } = require('child_process');
const { McpClient } = require('@modelcontextprotocol/sdk/client/mcp.js');
const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');

async function connectWithNpx() {
  // 使用npx启动MCP服务器
  const serverProcess = spawn('npx', ['@yinzhouzhi/mcp-filesystem-server', 'start'], {
    stdio: ['pipe', 'pipe', 'pipe']
  });
  
  // 创建STDIO传输
  const transport = new StdioClientTransport({
    input: serverProcess.stdout,
    output: serverProcess.stdin,
    error: serverProcess.stderr
  });
  
  // 创建客户端并连接
  const client = new McpClient();
  await client.connect(transport);
  
  // 调用MCP工具
  const result = await client.invokeTool('read_file', {
    path: './example.txt',
    encoding: 'utf8'
  });
  
  console.log('文件内容:', result);
  
  // 关闭连接
  await client.disconnect();
  serverProcess.kill();
}

connectWithNpx().catch(console.error);

可用工具

服务器提供了以下MCP工具：

文件操作

工具名称描述主要参数
read_file读取文件内容path, encoding
write_file写入文件内容path, content, encoding
append_file添加文件内容path, content, encoding
delete_file删除文件path
copy_file复制文件sourcePath, destinationPath, overwrite
move_file移动文件sourcePath, destinationPath, overwrite
get_file_info获取文件信息path
file_exists检查文件是否存在path

Office文件操作

read_word_document

读取Word文档内容并转换为文本（支持.doc和.docx格式）

参数

  • path: Word文件路径（.doc或.docx格式）[必填]
  • outputFormat 输出格式，支持'text'和'html'，默认'text'
  • extractImages 提取图像信息，默认false
  • includeStyles 是否包含样式信息？默认是false
  • pagination 分页参数，用于读取大型文档页面，格式如下：{pageSize: 1000, pageNum: 1}
  • range 读取范围，指定起始和结束行，格式如下：{startLine: 1, endLine: 100}
  • splitByParagraphs: 是否按段落分割并返回，默认false

read_excel_file

读取Excel文件内容（支持.xlsx、.xls和.csv格式）

参数

  • path Excel文件路径（在.xlsx、.xls或.csv格式）[必填]
  • sheet: 工作表名称或索引（从0开始），默认读取第一个工作表
  • outputFormat 输出格式，支持'json'、'csv'和'array'，默认为'array'
  • range 读取范围，例如{startRow:1, endRow:10, startCol:1, endCol:5}
  • includeFormulas 是否包含公式？默认是false
  • headerRow 是否应将第一行用作标题？默认是false

目录操作

工具名称描述主要参数
list_directory列出目录内容path, recursive, pattern
create_directory创建目录path, recursive
remove_directory删除目录path, recursive, force
directory_exists检查目录是否存在path

行操作

工具名称描述主要参数
read_lines读取文件指定行path, startLine, endLine, encoding
write_lines写入文件指定行path, lineNumber, content, encoding
insert_line插入行path, lineNumber, content, encoding
delete_lines删除行path, startLine, endLine, encoding
search_file_content搜索文件内容path, searchTerm, regex, caseSensitive

监控工具

工具名称描述主要参数
watch_path监控文件或目录变化path, recursive, events
stop_watch停止监控watcherId
list_watchers列出所有监控-

系统工具

工具名称描述主要参数
get_server_status获取服务器状态包括Stats

使用示例

文件读写

// 读取文件
const content = await client.invokeTool('read_file', {
  path: './example.txt',
  encoding: 'utf8'
});

// 写入文件
await client.invokeTool('write_file', {
  path: './output.txt',
  content: '这是文件内容',
  encoding: 'utf8'
});

// 追加内容
await client.invokeTool('append_file', {
  path: './log.txt',
  content: '新的日志条目\n',
  encoding: 'utf8'
});

按行操作

// 读取特定行
const lines = await client.invokeTool('read_lines', {
  path: './data.txt',
  startLine: 10,
  endLine: 20
});

// 插入一行
await client.invokeTool('insert_line', {
  path: './config.txt',
  lineNumber: 5,
  content: 'new_setting=value'
});

// 删除多行
await client.invokeTool('delete_lines', {
  path: './log.txt',
  startLine: 100,
  endLine: 200
});

文件和目录管理

// 复制文件
await client.invokeTool('copy_file', {
  sourcePath: './original.txt',
  destinationPath: './backup/copy.txt',
  overwrite: true
});

// 创建目录
await client.invokeTool('create_directory', {
  path: './data/reports/2023',
  recursive: true
});

// 列出目录内容
const files = await client.invokeTool('list_directory', {
  path: './documents',
  recursive: true,
  pattern: '*.pdf'
});

监控文件变化

// 开始监控
const watcherId = await client.invokeTool('watch_path', {
  path: './config',
  recursive: true,
  events: 'change,add,unlink'
});

// 列出所有监控
const watchers = await client.invokeTool('list_watchers');

// 停止监控
await client.invokeTool('stop_watch', {
  watcherId: watcherId
});

性能优化

文件系统服务器实现了多项性能优化以确保高吞吐量和低延迟：

文件操作性能优化

  1. 文件缓存

    • 缓存小文件内容以减少频繁的IO操作
    • 可配置的缓存大小和过期时间
    • 智能的LRU（最近最少使用）清理策略

  2. 流处理

    • 自动使用流处理大型文件以减少内存使用
    • 可配置的文件大小流处理阈值
    • 支持读取、写入、追加和复制操作

  3. 异步操作

    • 文件压缩/解压缩采用异步流处理
    • 日志轮转采用异步压缩
    • 大型目录操作使用优化算法

目录操作性能优化

  1. 目录内容缓存

    • 缓存目录列表结果以减少频繁读取
    • 智能的缓存失效机制确保数据一致性
    • 可配置的缓存大小和生命周期

  2. 递归操作优化

    • 优化递归列表和删除操作
    • 减少文件系统调用次数
    • 平衡内存使用和性能

日志系统优化

  1. 日志缓冲

    • 使用内存缓冲合并写操作
    • 减少磁盘IO频率并提高性能
    • 可配置的缓冲区大小和刷新间隔

  2. 日志轮转优化

    • 异步压缩旋转日志文件
    • 智能检查间隔减少不必要的文件检查
    • 压缩队列处理防止IO阻塞

性能配置示例

在defaults.js中可以自定义以下与性能相关的配置：

// 文件操作配置
const fileOperations = {
  // 文件缓存配置
  fileCache: {
    enabled: true,          // 是否启用文件缓存
    maxSize: 100,           // 最大缓存文件数
    maxAge: 60000,          // 缓存有效期 (ms)
  },
  // 流处理阈值（字节）
  streamThresholds: {
    read: 10 * 1024 * 1024,  // 10MB以上使用流读取
    write: 5 * 1024 * 1024,  // 5MB以上使用流写入
    append: 1 * 1024 * 1024, // 1MB以上使用流追加
    copy: 10 * 1024 * 1024,  // 10MB以上使用流复制
  },
  // 压缩选项
  compression: {
    defaultLevel: 6,         // 默认压缩级别 (1-9)
    useForLogs: true,        // 是否为日志启用压缩
  }
};

// 日志配置
const loggerConfig = {
  // ...基本配置...
  
  // 性能优化相关
  useBuffer: true,           // 使用缓冲区
  bufferSize: 64 * 1024,     // 缓冲区大小 (64KB)
  flushInterval: 1000,       // 缓冲区刷新间隔 (ms)
  asyncCompression: true,    // 异步压缩
  checkRotationInterval: 60000 // 日志轮转检查间隔 (ms)
};

监控管理池

文件系统服务器使用一个监控管理池来控制和管理系统中的文件和目录监控数量，防止资源泄露。

主要功能

  • 资源限制控制 限制系统中总监控器的数量、每个路径的监控器数量以及每个进程的监控器数量
  • 自动资源回收 定期清理长时间未使用的监控器，确保系统资源不被浪费
  • 智能资源管理 当系统达到限制时，移除最旧的监控器以腾出空间
  • 统计和监控 提供完整的监控器使用统计信息

配置选项

// 在 src/config/defaults.js 中配置
const watchPool = {
  maxWatchers: 200,            // 最大监控器数量
  maxPerPath: 5,               // 每个路径的最大监控器数量
  maxPerProcess: 50,           // 每个进程的最大监控器数量
  cleanupInterval: 3600000,    // 清理间隔 (1小时)
  maxIdleTime: 7200000         // 最大闲置时间 (2小时)
};

监控池API示例

// 导入监控工具模块
const watchTools