JinDaGe - filesystem-mcp-server-vrm MCP Details

article

README

🚀 文件系统 MCP 服务器

本项目是一个 MCP 服务的实现，提供文件系统操作、分析与管理功能，并通过标准化工具接口对外提供服务。

🚀 快速开始

本文件系统 MCP 服务器基于 MCP SDK 构建，可通过标准化工具接口提供文件系统操作、分析和管理功能。以下为你介绍如何快速搭建此服务器。

✨ 主要特性

分层架构：服务器采用分层架构，基于 MCP SDK 分为不同层次，各层职责明确，提升了系统的可维护性和扩展性。
丰富工具接口：提供了多种目录和文件操作工具，如列出目录内容、创建目录、读写文件等，满足多样化的文件系统操作需求。
错误处理机制：MCP 协议定义了详细的错误代码和错误响应格式，方便开发者定位和处理问题。

📦 安装指南

按照以下步骤完成服务器的安装与配置：

克隆仓库：

git clone <repository-url>
cd filesystem-server

安装依赖项：

npm install

构建服务器：

npm run build

配置 MCP 设置（cline_mcp_settings.json）：

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

💻 使用示例

基础用法

列出目录内容

interface ListDirectoryParams {
    path: string;       // 目录路径
    recursive?: boolean; // 是否递归列出（默认：false）
}

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

创建新目录

interface CreateDirectoryParams {
    path: string;       // 目录路径
}

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

读取文件内容

interface ReadFileParams {
    path: string;         // 文件路径
    encoding?: string;   // 字符编码（默认：utf-8）
}

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

写入文件内容

interface WriteFileParams {
    path: string;       // 文件路径
    content: string | Buffer; // 文件内容
    encoding?: string;  // 字符编码（默认：utf-8）
}

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

删除文件

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

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

高级用法

在实际使用中，你可以根据业务需求组合这些工具接口，实现更复杂的文件系统操作。例如，结合 list_directory 和 delete_file 实现批量删除指定目录下的文件。

📚 详细文档

架构

该服务器基于 MCP SDK 并分为不同的层次，架构图如下：

graph TD
    A[MCP 服务器层] --> B[工具注册表]
    B --> C[操作层]
    C --> D[文件系统操作]
    C --> E[分析操作]
    C --> F[流操作]

组件

服务器层：负责处理 MCP 协议通信和工具调度。
工具注册表：管理工具的注册和执行。
操作层：实现核心功能。
文件系统接口：提供安全的文件系统访问。

工具参考

目录操作

list_directory：列出目录内容及其元数据。
create_directory：创建新目录。

文件操作

read_file：读取文件内容。
write_file：写入文件内容。
delete_file：删除文件。

错误处理

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 | 代码检查 | | prettier | 格式化 | | ts-node | TypeScript 执行 | | nodemon | 开发服务器 |

🔧 技术细节

本服务器基于 MCP SDK 构建，采用分层架构，各层之间职责清晰，通过工具注册表实现工具的统一管理和调度。在文件操作方面，使用了多个第三方库来实现文件类型检测、MIME 类型查找、文件哈希等功能，确保了系统的功能完整性和性能。同时，通过定义详细的错误代码和错误响应格式，方便开发者进行问题定位和处理。

🤝 贡献指南

如果你想为项目做出贡献，请按照以下步骤进行：

叉克隆仓库。
创建功能分支。
为新功能编写测试。
确保所有测试通过。
提交拉取请求。

📄 许可证

本项目采用 MIT 许可证。

filesystem-mcp-server-vrm