文件系统 MCP 服务器

一个基于 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;
}

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', '写入的内容');
// 返回写入的字节数

错误处理

错误码和信息

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

开发模式

监视模式

npm run watch

代码质量

检查代码：

npm run lint

类型检查：

npm run type-check

贡献指南

1. 叉仓库
2. 创建功能分支
3. 为新功能编写测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT