Filesystem MCP

🚀 文件系統服務器說明

本項目是一個遵循 Model Context Protocol（MCP）協議的文件系統交互服務器，為 AI 代理提供安全、高效且功能全面的接口，以執行各類文件操作任務。

🚀 快速開始

安裝依賴

pip install zstandard python-multipart uvicorn[server,cli]

初始化配置文件

cp config.example.yaml config.yaml && nano config.yaml

啟動服務

uvicorn server:app --host 0.0.0.0 --port 8000

✨ 主要特性

文件瀏覽與檢查

• list_files 和 stat_items：可列出文件和目錄（支持遞歸），並獲取多項文件狀態信息。
• get_file_info：獲取單個文件的詳細信息，包含元數據和內容摘要。

內容讀寫

• read_content、write_content 和 append_content：實現多文件的讀取、寫入和追加功能，會自動創建父目錄。
• search_files：通過關鍵字或正則表達式在多個文件中進行搜索，並返回匹配結果。

精準編輯與查找

• edit_file 和 replace_content：支持多文件的精準內容修改（包括插入、替換和刪除操作），保留代碼縮進並輸出變更日誌。
• search_files 和 replace_in_files：實現跨文件的文本搜索與替換，提供上下文信息以便更準確地定位目標內容。

目錄管理

• create_directories：創建一個或多個目錄，支持遞歸創建父目錄。
• delete_items 和 move_items：實現安全的文件和目錄刪除、移動以及重命名操作。

權限控制

• chmod_items 和 chown_items：批量更改文件和目錄的 POSIX 權限和所有者信息，確保權限設置準確無誤。

🌟 優勢特點

1. 安全性高：所有操作都被限制在指定的根目錄內，防止越界訪問。
2. 效率優異：支持批量處理多個文件，顯著減少與 AI 代理之間的通信開銷。
3. 可靠性強：每個操作都會返回詳細的執行結果和錯誤報告，便於調試和問題排查。
4. 功能全面：提供覆蓋文件生命週期的豐富操作接口，滿足多種場景需求。

📚 詳細文檔

設計理念

• 安全為先：嚴格限制所有操作在指定根目錄內進行。
• 效率優先：通過直接 API 調用減少資源消耗和延遲。
• 簡潔明瞭：提供清晰一致的 MCP 協議接口，便於集成和使用。
• 穩定可靠：每個功能都經過全面測試，並使用 Zod 模式嚴格驗證輸入參數。

使用場景

1. 代碼倉庫管理：執行自動化的文件檢查和修復操作。
2. 內容生成工具：提供高效的多文件讀寫能力，加速內容生成流程。
3. 數據處理平臺：實現複雜的數據處理邏輯，包括文件篩選、轉換和歸檔等。

項目架構

該服務器採用模塊化設計：

• 核心管理層：負責權限校驗和操作合法性檢查。
• 文件操作層：封裝具體的文件系統調用。
• 網絡通信層：提供基於 HTTP 或 WebSocket 的接口。
• 日誌與監控層：記錄操作日誌並提供即時監控功能。

請求示例

列舉目錄內容

GET /api/list HTTP/1.1
Host: localhost:8000
Authorization: Bearer <your-token>
Directory: ./examples

寫入文件內容

POST /api/write HTTP/1.1
Host: localhost:8000
Authorization: Bearer <your-token>
Content-Type: multipart/form-data

-- boundary
filename=example.txt
content=hello world
-- boundary--

項目演示視頻

• 鏈接：服務器運行演示
• 時長：5 分鐘

💻 使用示例

基礎用法

以下是啟動服務的示例：

uvicorn server:app --host 0.0.0.0 --port 8000

高級用法

在實際使用中，可以根據不同的需求調整啟動服務的參數，例如更改主機地址和端口號：

uvicorn server:app --host 127.0.0.1 --port 8080

❓ 常見問題解答

1. 如何處理大文件？ 支持分塊上傳和下載功能，確保高效處理大文件。
2. 如何保證安全性？ 所有操作都被限制在預設的根目錄內，並且嚴格校驗用戶權限。
3. 如何擴展功能？ 可通過插件機制靈活添加新功能，保持核心代碼的簡潔性。

🚧 未來發展

• 計劃開發基於 Websocket 的長連接支持，提升即時文件操作的效率。
• 考慮增加版本控制功能，便於管理文件變更歷史。
• 探索與主流代碼倉庫（如 Git）的集成可能性。

👥 開發團隊

維護者：John Doe 貢獻者：Alice Smith，Bob Johnson

⚠️ 重要提示

本文檔中的部分信息（如鏈接和示例）尚未完全準備就緒，相關內容將陸續補充完善。