MCP Server Filesystem

🚀 MCP 文件系統服務器

MCP 文件系統服務器提供了一系列強大的文件操作工具，可與 VSCode 等工具集成，幫助開發者高效地進行文件管理和編輯，同時具備安全特性保障文件和目錄結構的安全。

🚀 快速開始

在 Windows 上設置開發環境

REM 克隆倉庫
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-filesystem

REM 創建並激活虛擬環境
python -m venv .venv
.venv\Scripts\activate

REM 安裝依賴項
pip install -e .

REM 安裝開發依賴項
pip install -e ".[dev]"

配置說明

要將此服務器與 VSCode 或其他支持 Cline 的工具集成，請按照以下步驟配置：

1. VSCode 集成：
   • 打開 VSCode 並安裝 Cline 擴展。
   • 在項目根目錄中創建一個 mcp-config.json 文件，並添加以下內容：

{
  "mcp": {
    "servers": [
      {
        "id": "filesystem",
        "class": "mcp_server_filesystem.FileSystemServer",
        "args": {
          "project_dir": "."
        }
      }
    ]
  }
}

2. 啟動服務器：
   • 在 VSCode 中，打開終端並運行以下命令：

python src/server.py

✨ 主要特性

• 豐富的文件操作工具：提供了列出目錄、讀取文件、保存文件、追加文件、刪除文件和編輯文件等多種操作。
• 安全可靠：具備文件訪問控制和目錄結構保護功能，確保文件和目錄的安全。
• 易於集成：可與 VSCode 等支持 Cline 的工具集成，方便開發者使用。
• 詳細日誌：服務器提供詳細的日誌輸出，便於調試和監控運行狀態。

📦 安裝指南

在 Windows 上設置開發環境的步驟如下：

REM 克隆倉庫
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-filesystem

REM 創建並激活虛擬環境
python -m venv .venv
.venv\Scripts\activate

REM 安裝依賴項
pip install -e .

REM 安裝開發依賴項
pip install -e ".[dev]"

💻 使用示例

基礎用法

啟動服務器：

python src/server.py

使用 VSCode 的 Cline 工具進行交互式測試：

• 打開 Cline 工具。
• 選擇 filesystem 服務器並開始會話。

高級用法

單元測試

在項目根目錄中運行：

python -m pytest tests/

📚 詳細文檔

可用工具

該服務器提供了以下 MCP 工具：

工具詳情

列出目錄

• 返回文件和目錄名稱的列表。
• 默認情況下，結果會根據 .gitignore 模式過濾，並排除 .git 文件夾。

讀取文件

• 參數：file_path（字符串）：要讀取的文件路徑（相對於項目目錄）
• 返回文件內容作為字符串。

保存文件

• 參數：
  • file_path（字符串）：要寫入的文件路徑
  • content（字符串）：要寫入的內容
• 返回布爾值，表示操作是否成功。

追加文件

• 參數：
  • file_path（字符串）：要追加的文件路徑
  • content（字符串）：要追加的內容
• 返回布爾值，表示操作是否成功。
• 注意：文件必須已經存在；使用 save_file 創建新文件。

刪除文件

• 參數：file_path（字符串）：要刪除的文件路徑
• 返回布爾值，表示操作是否成功。
• 注意：此操作不可逆，將永久刪除文件。

編輯文件

• 參數：
  • file_path（字符串）：要編輯的文件
  • edits（數組）：編輯操作列表，每個操作包含：
    • old_text（字符串）：要替換的文本
    • new_text（字符串）：新的替換文本
  • dry_run（布爾值，可選）：預覽更改而不應用
  • options（對象，可選）：格式化設置
• 功能：
  • 支持行範圍和文件路徑的模式匹配。
  • 支持同時進行多處替換。

🔧 技術細節

安全特性

• 文件訪問控制：

  • 僅允許讀取、寫入和追加操作，嚴格禁止刪除操作。
  • 所有更改都需要顯式確認，避免意外修改。

• 目錄結構保護：

  • 根目錄及其子目錄的結構受到保護，防止意外刪除或重命名。

開發說明

• 代碼結構：

  • 項目基於標準 Python 包結構組織。
  • 主要模塊包括 server.py 和 filesystem_server.py。

• 日誌與調試：

  • 服務器提供詳細日誌輸出，便於調試和監控運行狀態。
  • 可通過配置文件調整日誌級別和輸出格式。

📄 許可證

本項目遵循 MIT 許可證，允許自由使用、修改和分發。詳細許可內容請參考 LICENSE 文件。

通過以上配置與說明，您可以順利地將 MCP 文件系統服務器集成到開發環境中，並利用其強大的文件操作功能進行高效開發。