文件系统 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