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 倉庫地址