MCP File Operations Server

🚀 MCP文件操作服務器

這是一個用於文件和目錄操作的MCP（Meta Computing Protocol）服務器，提供了基本文件操作、目錄管理、變更跟蹤等功能，能高效處理文件系統相關任務。

🚀 快速開始

安裝

• 自動安裝：通過Smithery自動安裝：

  npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude
  

• 手動安裝：直接運行：

  npm install
  

啟動服務器

npm start

開發模式（自動重載）：

npm run dev

✨ 主要特性

可用工具

基本文件操作

• copy_file：複製文件到新位置
• read_file：讀取文件內容
• write_file：寫入內容到文件
• move_file：移動/重命名文件
• delete_file：刪除文件
• append_file：追加內容到文件

目錄操作

• make_directory：創建目錄
• remove_directory：刪除目錄
• copy_directory：遞歸複製目錄（帶進度報告）

監控操作

• watch_directory：開始監控目錄變化
• unwatch_directory：停止監控目錄

變更跟蹤

• get_changes：獲取記錄的變更列表
• clear_changes：清除所有變更記錄

可用資源

靜態資源

• file:///recent-changes：最近文件系統變更列表

資源模板

• file://{path}：訪問文件內容
• metadata://{path}：訪問文件元數據
• directory://{path}：列出目錄內容

速率限制

服務器實現速率限制以防止濫用：

• 工具：每分鐘100次請求
• 資源：每分鐘200次請求
• 監控操作：每分鐘20次操作

速率限制錯誤包含重試-after時間段信息。

安全特性

路徑驗證

所有文件路徑均經過驗證以防止目錄遍歷攻擊：

• 禁止使用父目錄引用（../）
• 正確進行路徑規範化
• 輸入參數淨化

資源保護

• 所有操作均有速率限制
• 正確的錯誤處理和日誌記錄
• 驗證所有參數輸入
• 安全的資源清理機制

進度報告

長時間運行的操作（如目錄複製）提供進度更新：

interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}

通過操作結果中的進度令牌跟蹤進度。

性能優化

緩存機制

服務器內置文件操作緩存，可提高重複操作的效率。默認啟用。

並行處理

支持多線程和併發操作以提升性能，具體取決於系統負載和配置。

💻 使用示例

基礎用法

// 複製文件
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// 監控目錄
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// 通過資源訪問文件內容
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// 帶進度跟蹤複製目錄
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// 通過結果中的進度令牌跟蹤進度
console.log(result.progressToken);

📚 詳細文檔

配置

基本配置

可以通過環境變量或配置文件設置以下選項：

• PORT：服務器監聽端口，默認為3000
• LOG_LEVEL：日誌級別，可選值為debug, info, warning, error, 默認為info
• MAX_FILE_SIZE：允許的最大文件大小，默認為1MB

高級配置

• 啟用/禁用變更跟蹤：

  {
    enableChangeTracking: true // 默認為true
  }
  

• 配置目錄複製的併發數：

  {
    copyConcurrency: 5 // 複製操作默認併發數為5
  }
  

錯誤處理

常見錯誤

1. 文件不存在：嘗試訪問或操作未存在的文件時拋出。

   Error: File not found
   

2. 權限不足：沒有足夠的權限進行操作時拋出。

   Error: Permission denied
   

3. 目錄遍歷拒絕：嘗試進行目錄遍歷攻擊時被阻止。

   Error: Directory traversal attempt detected
   

自定義錯誤處理

可以通過註冊全局錯誤處理器捕獲和處理錯誤：

mcp errorHandler(error) {
    console.error('An error occurred:', error);
    // 自定義處理邏輯
}

日誌記錄

日誌格式

默認的日誌格式為：

[timestamp] - [level] - message

例如：

2023-10-05 12:34:56 - info - File operation completed successfully.

日誌級別

支持以下日誌級別：

• debug：調試信息
• info：一般信息
• warning：警告消息
• error：錯誤信息

FAQ

1. 如何查看當前日誌？

   • 使用mcp logs命令查看即時日誌。

2. 能否禁用變更跟蹤？

   • 是的，通過設置enableChangeTracking: false可以禁用變更跟蹤功能。

3. 服務器支持哪些協議？

   • 當前版本僅支持MCP協議，未來計劃添加更多協議支持。

🔧 技術細節

該服務器基於MCP協議構建，在實現文件和目錄操作功能時，採用了路徑驗證機制防止目錄遍歷攻擊，通過速率限制避免濫用，內置緩存機制和支持並行處理提升性能。同時，對各類操作和錯誤進行了詳細的日誌記錄，方便後續排查和維護。

📄 許可證

文檔未提及相關信息。

👥 貢獻者

• 開發者：[你的名字]
• 維護者：[項目維護團隊]

以上是項目的完整文檔，包含安裝、配置、使用說明以及常見問題解答。如果有任何疑問或需要進一步幫助，請隨時聯繫項目維護團隊。