本地文件系统操作服务器

简介

本项目是一个基于STDIO通信的本地文件系统操作服务器，作为Electron应用的MCP（Message Communication Protocol）服务提供方，提供完整的文件系统操作能力，包括文件和目录的创建、读取、写入、删除、移动等操作。

功能特点

• 通过STDIO与Electron主进程进行通信
• 提供完整的文件系统操作API
• 确保安全性，防止未授权的文件操作
• 支持异步操作，不阻塞主进程
• 提供详细的错误处理和日志记录

安装

# 进入项目目录
cd filesystem-server

# 安装依赖
npm install

使用方法

直接启动

npm start

在Electron应用中集成

在Electron应用中通过MCP管理器添加STDIO类型的服务器：

// 服务器配置信息
const config = {
  id: 'local-file-system',
  type: 'stdio',
  command: 'node /path/to/filesystem-server/src/main.js',
  autoConnect: true
};

// 注册服务器
const result = await mcpClient.registerServer(config);

支持的文件操作工具

| 工具名称 | 功能描述 | 参数 | |---------|---------|------| | list_files | 列出目录中的文件 | path: 目录路径 | | read_file | 读取文件内容 | path: 文件路径 | | read_file_lines | 读取文件指定行范围 | path: 文件路径, start: 起始行, end: 结束行 | | write_file | 写入文件内容 | path: 文件路径, content: 文件内容 | | append_file | 追加内容到文件 | path: 文件路径, content: 追加内容 | | delete_file | 删除文件 | path: 文件路径 | | create_directory | 创建目录 | path: 目录路径 | | delete_directory | 删除目录 | path: 目录路径, recursive: 是否递归删除 | | copy_file | 复制文件 | source: 源文件路径, destination: 目标文件路径 | | move_file | 移动文件 | source: 源文件路径, destination: 目标文件路径 | | file_info | 获取文件信息 | path: 文件路径 | | count_lines | 统计文件行数 | path: 文件路径 | | file_exists | 检查文件是否存在 | path: 文件路径 | | watch_directory | 监听目录变化 | path: 目录路径 | | watch_path | 监控文件或目录变更 | path: 路径, recursive: 是否递归, events: 事件类型 | | stop_watch | 停止文件或目录监控 | watcherId: 监控ID | | list_watchers | 获取当前活跃的监控列表 | 无参数 |

调用示例

// 读取文件示例
const executionParams = {
  toolName: 'read_file',
  params: { 
    path: '/path/to/your/file.txt' 
  },
  context: {
    serverId: 'local-file-system'
  }
};

try {
  const result = await mcpClient.executeTool(executionParams);
  if (result.success) {
    console.log('文件内容:', result.data);
  } else {
    console.error('读取文件失败:', result.error);
  }
} catch (error) {
  console.error('执行出错:', error);
}

安全性

• 实现了基本的路径验证，防止路径遍历攻击
• 可以根据需要配置路径白名单和黑名单
• 支持权限控制和访问限制

开发说明

工具注册方式

对于服务器开发者，需要注意在注册MCP工具时使用正确的格式：

// 正确的MCP工具注册方式
server.tool(
  'tool_name',        // 工具名称
  '工具描述字符串',     // 工具描述（直接传递字符串）
  {                   // 参数模式
    param1: z.string().describe('参数1描述')
  },
  async (params) => { // 工具处理函数
    // 处理逻辑
  }
);

// 不正确的方式 - 不要使用对象传递description
server.tool(
  'tool_name',
  {                   // 参数模式
    param1: z.string().describe('参数1描述')
  },
  async (params) => { // 工具处理函数
    // 处理逻辑
  },
  { description: '工具描述' }  // ❌ 错误：不要使用对象传递描述
);

MCP规范要求描述作为单独的字符串参数直接传递，而不是作为对象的属性。

日志系统

文件系统服务器集成了强大的日志系统，提供全面的操作记录和错误追踪功能。

日志功能特性

• 多级别日志记录：支持 DEBUG、INFO、WARN、ERROR 和 NONE 五个日志级别
• 双重输出：同时支持控制台和文件输出
• 日志轮转：当日志文件达到指定大小时自动轮转，防止单个日志文件过大
• 格式选择：支持文本和JSON两种日志格式
• 自定义配置：可根据需求自定义日志行为

使用方法

基本用法

const logging = require('./utils/logging');

// 初始化日志系统
logging.initialize();

// 记录不同级别的日志
logging.debug('调试信息', { extraData: 'some debug data' });
logging.info('操作信息', { operation: 'read_file', path: '/path/to/file' });
logging.warn('警告信息', { warning: 'file size exceeds recommended limit' });
logging.error('错误信息', { error: 'permission denied', code: 403 });

自定义配置

logging.initialize({
  level: logging.LOG_LEVELS.DEBUG,  // 设置日志级别
  logToConsole: true,               // 是否输出到控制台
  logToFile: true,                  // 是否输出到文件
  logFilePath: './logs/custom.log', // 自定义日志文件路径
  maxLogFileSize: 5 * 1024 * 1024,  // 设置日志文件最大容量为5MB
  rotateLogFiles: true,             // 启用日志轮转
  maxLogFiles: 3,                   // 保留最近3个日志文件
  format: 'json'                    // 使用JSON格式输出日志
});

动态调整日志级别

// 在运行时调整日志级别
logging.setLevel('DEBUG');  // 设置为调试级别
logging.setLevel('ERROR');  // 仅记录错误信息

关闭日志系统

// 在程序结束时安全关闭日志系统
logging.shutdown();