MCP Server Wsl Filesystem

🚀 WSL文件系统MCP服务器

本项目是一个基于Node.js的服务器，实现了模型上下文协议（MCP），专为Windows Subsystem for Linux (WSL)环境量身打造。它是原始文件系统MCP服务器的分支，在性能和对Linux命令的支持方面进行了显著优化。

🚀 快速开始

重要提示

⚠️ 重要提示

原项目支持通过网络路径访问WSL文件，例如：

node dist/index.js '\\.\pipe\windows-to-ubuntu'

并提供了以下示例配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["dist/index.js", "\\\\.", "pipe", "windows-to-ubuntu"]
    }
  }
}

✨ 主要特性

项目简介

该项目作为针对WSL优化的分支，具备以下主要功能：

1. 摒弃原项目的直接Node.js文件系统调用，采用WSL命令执行。
2. 新增特定WSL发行版支持。
3. 实现Windows与Linux路径的自动转换。
4. 增强文件内容处理的跨平台兼容性。
5. 添加专门针对WSL管理的功能。

功能概述

核心功能

• 跨平台文件操作：借助WSL命令执行，实现Windows和Linux之间的文件操作互通。
• 发行版支持：可选择指定的WSL发行版（如Ubuntu - 20.04），也可使用默认发行版。
• 路径转换：自动处理Windows与Linux格式之间的路径转换。
• 性能优化：针对WSL环境进行专门优化，显著提升文件操作效率。

工具集

项目提供了丰富的功能工具：

• 基础文件操作：支持读取文件内容、写入文件内容、创建目录、删除目录、移动文件/目录以及复制文件/目录。
• 高级功能：涵盖文件搜索与查找（支持复杂条件）、文件属性查询（获取详细信息和元数据）、权限管理（设置和修改文件权限）、压缩与解压（支持常见归档格式，如zip、tar.gz等）以及日志记录（提供详细的操作日志）。

📦 安装指南

通用安装步骤

1. 克隆项目仓库：

git clone https://github.com/yourusername/mcp-server-wsl-filesystem.git

2. 进入项目目录：

cd mcp-server-wsl-filesystem

3. 安装依赖项：

npm install

4. 构建TypeScript项目：

npm run build

开发环境配置

1. 确保安装Node.js（v14.0.0或更高版本）。
2. 安装完成后验证版本：

node --version
npm --version

💻 使用示例

基础用法

在运行服务器之前，必须先构建TypeScript项目：

npm install
npm run build

然后运行服务器，可指定使用的WSL发行版（可选）和要暴露的目录：

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

• 若不指定发行版，将默认使用系统默认发行版。
• 可以指定多个目录进行暴露。

高级用法

访问Ubuntu - 20.04发行版

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

使用默认发行版

node dist/index.js /home/user/documents

📚 详细文档

与Claude Desktop集成

在claude_desktop_config.json中添加以下配置：

方案1：指定特定WSL发行版

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

方案2：使用默认WSL发行版

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

在第二种方案中，系统将自动使用默认WSL发行版，无需额外配置。

与原项目的主要区别

此分支针对WSL环境进行了以下优化：

1. 命令执行替代：用WSL命令执行替换原项目的直接Node.js调用。
2. 发行版支持：增加了对指定WSL发行版的支持。
3. 路径转换功能：实现了Windows与Linux路径的自动转换。
4. 性能改进：针对WSL环境进行了专门优化。

📄 许可证

项目遵循MIT许可证，具体许可内容请参考LICENSE文件。

🤝 贡献指南

欢迎社区贡献！如果发现任何问题或有改进建议，请提交Issues或Pull Request到仓库： GitHub 仓库地址