Filesystem MCP Server Vrm

🚀 文件系統 MCP 服務器

本項目是一個提供文件系統操作、分析和管理功能的 MCP 服務實現，藉助標準化工具接口來提供服務。

🚀 快速開始

本服務器基於 MCP SDK 構建，且分為不同層次，架構如下：

graph TD
    A[MCP 服務器層] --> B[工具註冊表]
    B --> C[操作層]
    C --> D[文件系統操作]
    C --> E[分析操作]
    C --> F[流操作]

組件介紹

• 服務器層：負責處理 MCP 協議通信和工具調度。
• 工具註冊表：對工具註冊和執行進行管理。
• 操作層：實現核心功能。
• 文件系統接口：提供安全的文件系統訪問。

📦 安裝指南

1. 克隆倉庫：

git clone <repository-url>
cd filesystem-server

2. 安裝依賴項：

npm install

3. 構建服務器：

npm run build

4. 配置 MCP 設置（cline_mcp_settings.json）：

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["path/to/filesystem-server/build/index.js"]
    }
  }
}

💻 使用示例

基礎用法

目錄操作

list_directory

用於列出目錄內容及其元數據。

interface ListDirectoryParams {
    path: string;       // 目錄路徑
    recursive?: boolean; // 是否遞歸列出（默認：false）
}

interface ListDirectoryResult {
    entries: {
        name: string;
        path: string;
        isDirectory: boolean;
        size: number;
        created: string;
        modified: string;
        accessed: string;
    }[];
}

create_directory

用於創建新目錄。

interface CreateDirectoryParams {
    path: string;       // 目錄路徑
}

interface CreateDirectoryResult {
    success: boolean;
    message?: string;
}

文件操作

read_file

用於讀取文件內容。

interface ReadFileParams {
    path: string;         // 文件路徑
    encoding?: string;   // 字符編碼（默認：utf-8）
}

interface ReadFileResult {
    content: Buffer | string;
    mimeType: string;
}

write_file

用於寫入文件內容。

interface WriteFileParams {
    path: string;       // 文件路徑
    content: string | Buffer; // 文件內容
    encoding?: string;  // 字符編碼（默認：utf-8）
}

interface WriteFileResult {
    success: boolean;
    message?: string;
}

delete_file

用於刪除文件。

interface DeleteFileParams {
    path: string;       // 文件路徑
}

interface DeleteFileResult {
    success: boolean;
    message?: string;
}

錯誤處理

MCP 協議定義了以下錯誤代碼：

• 100：通用錯誤
• 101：身份驗證失敗
• 102：權限 denied
• 103：文件或目錄不存在
• 104：系統資源不足
• 105：操作超時
• 106：無效參數

錯誤響應格式如下：

{
    "error": {
        "code": number,
        "message": string
    }
}

📚 詳細文檔

開發信息

項目結構

.
├── operations/         # 核心操作實現
├── tools/             # MCP 工具定義和處理程序
├── __tests__/         # 測試套件
├── index.ts           # 入口點
├── server.ts          # MCP 服務器設置
├── types.ts           # 類型定義
└── utils.ts           # 工具函數

運行測試

運行測試套件：

npm test

帶有覆蓋的運行：

npm run test:coverage

開發模式

以觀察模式運行：

npm run watch

代碼質量

檢查代碼基線：

npm run lint

進行類型檢查：

npm run type-check

依賴項

核心依賴項

• @modelcontextprotocol/sdk：MCP 服務器實現
• file-type：文件類型檢測
• mime-types：MIME 類型查找
• crypto-js：文件哈希
• archiver：ZIP 創建
• extract-zip：ZIP 提取
• iconv-lite：文本編碼
• chardet：編碼檢測

開發依賴項

• typescript：類型系統
• jest：測試
• eslint：ing
• prettier：格式化
• ts-node：TypeScript 執行
• nodemon：開發服務器

貢獻指南

1. 叉克隆倉庫
2. 創建功能分支
3. 為新功能編寫測試
4. 確保所有測試通過
5. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證。