文件系统 MCP 服务器

这是一个通过标准化工具接口提供文件系统操作、分析和处理能力的 Model Context Protocol (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;
        mode: string;
    }[];
}

create_directory

创建新目录。

interface CreateDirectoryParams {
    path: string;       // 目录路径
    recursive?: boolean; // 是否创建父目录（默认：true）
}

文件操作

read_file

读取文件内容并支持编码。

interface ReadFileParams {
    path: string;     // 文件路径
    encoding?: string; // 文件编码（默认：'utf8'）
}

write_file

写入内容到文件。

interface WriteFileParams {
    path: string;     // 文件路径
    content: string;  // 要写入的内容
    encoding?: string; // 文件编码（默认：'utf8'）
}

append_file

追加内容到文件。

interface AppendFileParams {
    path: string;     // 文件路径
    content: string;  // 要追加的内容
    encoding?: string; // 文件编码（默认：'utf8'）
}

分析操作

analyze_text

分析文本文件属性。

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

interface AnalyzeTextResult {
    lineCount: number;
    wordCount: number;
    charCount: number;
    encoding: string;
    mimeType: string;
}

calculate_hash

使用指定算法计算文件哈希值。

interface CalculateHashParams {
    path: string;           // 文件路径
    algorithm?: 'md5' | 'sha1' | 'sha256' | 'sha512'; // 哈希算法
}

interface CalculateHashResult {
    hash: string;
    algorithm: string;
}

find_duplicates

识别目录中的重复文件。

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

interface FindDuplicatesResult {
    duplicates: {
        hash: string;
        size: number;
        files: string[];
    }[];
}

压缩操作

create_zip

创建 ZIP 归档文件。

interface CreateZipParams {
    files: string[];  // 要包含的文件
    output: string;   // 输出 ZIP 路径
}

extract_zip

提取 ZIP 归档文件。

interface ExtractZipParams {
    path: string;    // ZIP 文件路径
    output: string;  // 输出目录
}

错误处理

服务器使用标准 MCP 错误码：

enum ErrorCode {
    ParseError = -32700,
    InvalidRequest = -32600,
    MethodNotFound = -32601,
    InvalidParams = -32602,
    InternalError = -32603
}

错误响应包括：

• 错误码
• 可读性消息
• 当可用时的附加上下文

示例错误：

{
    "code": -32602,
    "message": "未找到文件：/path/to/file.txt"
}

开发

项目结构

src/
├── 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: 开发服务器

贡献

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

许可证

MIT