🚀 文件系统 MCP 服务器

文件系统 MCP 服务器是一个基于 MCP 协议的标准工具接口，它具备文件系统操作、分析和管理等功能，为文件系统相关操作提供了便捷、高效的解决方案。

🚀 快速开始

文件系统 MCP 服务器基于 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"]
    }
  }
}

✨ 主要特性

• 分层架构：采用分层设计，包括服务器层、工具注册表、操作层和文件系统接口，各层分工明确，便于维护和扩展。
• 丰富的工具接口：提供了目录操作、文件操作等多种工具接口，支持列出目录内容、读取和写入文件等常见操作。
• 错误处理机制：定义了详细的错误码和信息，方便开发者快速定位和解决问题。
• 开发友好：支持监视模式、代码检查和类型检查，有助于提高开发效率和代码质量。

📦 安装指南

克隆仓库

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"]
    }
  }
}

💻 使用示例

目录操作

list_directory

列出目录内容及其元数据。

interface ListDirectoryParams {
  /** 要列出的目录路径 */
  path: string;
}

interface ListDirectoryResult {
  /** 目录中的文件和子目录列表 */
  entries: Array<{
    /** 文件或子目录的名称 */
    name: string;
    /** 文件类型（'file' 或 'directory'） */
    type: string;
    /** 修改时间 */
    modifiedTime: Date;
  }>;
}

const result = await filesystem.listFiles('/path/to/dir');
// 结果结构如上所示

文件操作

read_file

读取文件内容。

interface ReadFileParams {
  /** 要读取的文件路径 */
  path: string;
}

interface ReadFileResult {
  /** 文件内容（二进制缓冲区） */
  content: Buffer;
}

const content = await filesystem.readFile('/path/to/file.txt');
// content 包含文件数据

write_file

写入文件内容。

interface WriteFileParams {
  /** 要写的文件路径 */
  path: string;
  /** 文件内容 */
  content: Buffer | string;
}

interface WriteFileResult {
  /** 写入的字节数 */
  bytesWritten: number;
}

const result = await filesystem.writeFile('/path/to/file.txt', '写入的内容');
// 返回写入的字节数

📚 详细文档

结构

该服务器基于 MCP SDK 构建，并划分为不同的层次：

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

组件

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

错误处理

错误码和信息

• 400 Bad Request：无效请求参数。
• 401 Unauthorized：权限不足，无法执行操作。
• 404 Not Found：指定文件或目录不存在。
• 500 Internal Server Error：服务器内部错误。

开发模式

监视模式

npm run watch

代码质量

检查代码

npm run lint

类型检查

npm run type-check

🤝 贡献指南

1. 叉仓库：将项目仓库 fork 到自己的 GitHub 账户下。
2. 创建功能分支：在自己的仓库中创建新的功能分支。
3. 编写测试：为新功能编写相应的测试用例。
4. 确保测试通过：运行所有测试，确保新功能不会引入新的问题。
5. 提交拉取请求：将自己的修改提交到原仓库，等待审核和合并。

📄 许可证

本项目采用 MIT 许可证。