MCP 服务器

Filesystem MCP Server

一个模型上下文协议服务器，通过标准化的工具接口提供文件系统操作、分析和处理能力。

README

文件系统 MCP 服务器

一个模型上下文协议 (MCP) 服务器实现，通过标准化的工具接口提供文件系统操作、分析和处理能力。

架构

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

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

组件

服务器层: 处理 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"]
    }
  }
}

工具参考

目录操作

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": "File not found: /path/to/file.txt"
}

开发

项目结构

src/
├── operations/     # 核心操作实现
├── tools/         # MCP 工具定义和处理程序
├── __tests__/     # 测试套件
├── index.ts       # 入口点
├── server.ts      # MCP 服务器设置
├── types.ts       # 类型定义
└── utils.ts       # 实用函数