mcp-server-wsl-filesystem

🚀 WSL文件系统MCP服务器

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

🚀 快速开始

安装说明

通用安装步骤

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

✨ 主要特性

核心功能

• 跨平台文件操作：借助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

💻 使用示例

基础用法

访问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环境进行了专门优化。

🔧 技术细节

该项目是针对WSL优化的分支，主要功能包括：

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

📄 许可证

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

贡献指南

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

GitHub 仓库地址

⚠️ 重要提示

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

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

并提供了以下示例配置：

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