MCP Filesystem Server (mcp-filesystem-server)

文件系统MCP服务器

一种模型上下文协议（MCP）服务器实现，通过标准化的工具接口提供文件系统操作、分析和操纵功能。

建筑

服务器基于MCP SDK构建，并组织成不同的层：

graph TD
    A[MCP Server Layer] --> B[Tool Registry]
    B --> C[Operations Layer]
    C --> D[File System Operations]
    C --> E[Analysis Operations]
    C --> F[Stream Operations]

组件

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

安装

1. 克隆存储库：

git clone 
cd filesystem-server

1. 安装依赖项：

npm install

1. 构建服务器：

npm run build

1. 配置MCP设置（cline_MCP_settings.json）：

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

工具参考

目录操作

list_directory

列出包含元数据的目录内容。

interface ListDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // List recursively (default: 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;       // Directory path
    recursive?: boolean; // Create parent directories (default: true)
}

文件操作

read_file

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

interface ReadFileParams {
    path: string;     // File path
    encoding?: string; // File encoding (default: 'utf8')
}

write_file

将内容写入文件。

interface WriteFileParams {
    path: string;     // File path
    content: string;  // Content to write
    encoding?: string; // File encoding (default: 'utf8')
}

附录文件

将内容附加到文件。

interface AppendFileParams {
    path: string;     // File path
    content: string;  // Content to append
    encoding?: string; // File encoding (default: 'utf8')
}

分析操作

analyze_text

分析文本文件属性。

interface AnalyzeTextParams {
    path: string; // File path
}

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

计算现金

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

interface CalculateHashParams {
    path: string;           // File path
    algorithm?: 'md5' | 'sha1' | 'sha256' | 'sha512'; // Hash algorithm
}

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

查找重复项

标识目录中的重复文件。

interface FindDuplicatesParams {
    path: string; // Directory path
}

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

压缩操作

create_zip

创建ZIP存档。

interface CreateZipParams {
    files: string[];  // Files to include
    output: string;   // Output ZIP path
}

提取_压缩

提取ZIP存档。

interface ExtractZipParams {
    path: string;    // ZIP file path
    output: string;  // Output directory
}

错误处理

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

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

错误响应包括：

• 错误代码
• 人类可读信息
• 附加上下文（如果可用）

示例错误：

{
    "code": -32602,
    "message": "File not found: /path/to/file.txt"
}

发展

项目结构

src/
├── operations/     # Core operations implementation
├── tools/         # MCP tool definitions and handlers
├── __tests__/     # Test suites
├── index.ts       # Entry point
├── server.ts      # MCP server setup
├── types.ts       # Type definitions
└── utils.ts       # Utility functions

运行测试

运行测试套件：

npm test

跑步覆盖：

npm run test:coverage

发展模式

在监视模式下运行：

npm run watch

代码质量

浏览代码库：

npm run lint

类型检查：

npm run type-check

依赖项

核心依赖关系：

• @modelcontextprotocol/sdk:MCP服务器实现
• 文件类型：文件类型检测
• mime类型：mime类型查找
• crypto-js：文件哈希
• 归档程序：ZIP创建
• 解压zip：zip解压
• iconv-lite：文本编码
• chardet：编码检测

开发依赖关系：

• typescript:字体系统
• jest：测试
• eslint：棉绒
• 更漂亮：格式化
• ts节点：TypeScript执行
• nodemon：开发服务器

贡献

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

许可证

麻省理工学院