文件系统-mcp服务器

Name: 文件系统-mcp服务器
Author: cyanheads

作者：cyanheads22 星标更新：2025-07-22

安装使用来源：spider==github.com

项目介绍

文件系统 MCP 服务器

通过强大的、平台无关的文件系统能力增强您的AI代理，现在支持STDIO和可流式传输的HTTP传输选项。

此 Model Context Protocol (MCP) 服务器提供了一个安全可靠的接口，使AI代理能够与本地文件系统进行交互。它支持读取、写入、更新和管理文件及目录，基于一个生产就绪的TypeScript基础，该基础具有全面的日志记录、错误处理、安全措施，并且现在支持STDIO和HTTP传输。

概述

Model Context Protocol (MCP) 是一个标准框架，允许AI模型安全地与外部工具和数据源（资源）进行交互。此服务器实现了MCP标准，以暴露基本的文件系统操作作为工具，使AI代理能够：

读取并分析文件内容。
创建、修改或覆盖文件。
管理目录和文件路径。
在文件中执行有针对性的更新。

该服务器使用TypeScript构建，强调类型安全性、模块化和健壮的错误处理，使其适合可靠地集成到AI工作流程中。它现在支持STDIO用于直接进程通信以及HTTP用于网络交互。

架构

服务器采用分层架构以提高清晰度和可维护性：

flowchart TB
    subgraph TransportLayer["传输层"]
        direction LR
        STDIO["STDIO传输"]
        HTTP["HTTP传输（Express，JWT认证）"]
    end

    subgraph APILayer["API层"]
        direction LR
        MCP["MCP协议接口"]
        Val["输入验证（Zod）"]
        PathSan["路径净化"]

        MCP --> Val --> PathSan
    end

    subgraph CoreServices["核心服务"]
        direction LR
        Config["配置（Zod验证环境变量）"]
        Logger["日志记录（Winston，上下文感知）"]
        ErrorH["错误处理（McpError，ErrorHandler）"]
        ServerLogic["MCP服务器逻辑"]
        State["会话状态（默认路径）"]

        Config --> ServerLogic
        Logger --> ServerLogic & ErrorH
        ErrorH --> ServerLogic
        State --> ServerLogic
    end

    subgraph ToolImpl["工具实现"]
        direction LR
        FSTools["文件系统工具"]
        Utils["核心实用程序（内部，安全，指标，解析）"]

        FSTools --> ServerLogic
        Utils -- 使用于 --> FSTools
        Utils -- 使用于 --> CoreServices
        Utils -- 使用于 --> APILayer
    end

    TransportLayer --> MCP
    PathSan --> FSTools

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class TransportLayer,APILayer,CoreServices,ToolImpl layer
    class STDIO,HTTP,MCP,Val,PathSan,Config,Logger,ErrorH,ServerLogic,State,FSTools,Utils component

传输层：通过STDIO或HTTP（带有Express.js和JWT认证）处理通信。
API层：管理MCP通信，使用Zod验证输入，并净化路径。
核心服务：监督配置（Zod验证的环境变量）、上下文感知的日志记录、标准化的错误报告、会话状态（如默认工作目录），以及主要的MCP服务器实例。
工具实现：包含每个文件系统工具的具体逻辑，利用一组重构的共享实用程序，分类为内部、安全、指标和解析模块。

特性

全面的文件操作：用于读取、写入、列出、删除、移动和复制文件及目录的工具。
有针对性的更新：update_file 工具允许在文件内进行精确的查找和替换操作，支持纯文本和正则表达式。
会话感知的路径管理：set_filesystem_default 工具为会话期间解析相对路径设置默认工作目录。
双传输支持：
- STDIO：当作为子进程运行时，用于直接高效的通信。
- HTTP：用于基于网络的交互，包括RESTful端点、服务器发送事件（SSE）用于流式传输，以及基于JWT的身份验证。
安全第一：
- 内置路径净化防止目录遍历攻击。
- HTTP传输的JWT身份验证。
- 使用Zod进行输入验证。
稳健的基础：包括生产级实用程序，现在重新组织以提高模块化：
- 内部实用程序：上下文感知的日志记录（Winston）、标准化的错误处理（McpError，ErrorHandler）、请求上下文管理。
- 安全实用程序：输入净化、速率限制、UUID和前缀ID生成。
- 指标实用程序：令牌计数。
- 解析实用程序：自然语言日期解析、部分JSON解析。
增强的配置：使用Zod验证的环境变量进行类型安全和可靠的设置。
类型安全性：完全使用TypeScript实现，以提高可靠性和可维护性。

安装

步骤

克隆仓库：

git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server

安装依赖项：
```
npm install
```
构建项目：
```
npm run build
```
这将编译TypeScript代码到JavaScript，并将其放置在dist/目录中，同时使主脚本可执行。可执行文件位于dist/index.js。

配置

使用环境变量配置服务器（支持.env文件）：

核心服务器设置：

MCP_LOG_LEVEL（可选）：最小日志级别（例如，debug，info，warn，error）。默认为debug。
LOGS_DIR（可选）：日志文件的目录。默认为项目根目录下的./logs。
NODE_ENV（可选）：运行时环境（例如，development，production）。默认为development。

传输设置：

MCP_TRANSPORT_TYPE（可选）：通信传输（stdio或http）。默认为stdio。
- 如果选择http：
  - MCP_HTTP_PORT（可选）：HTTP服务器的端口。默认为3010。
  - MCP_HTTP_HOST（可选）：HTTP服务器的主机。默认为127.0.0.1。
  - MCP_ALLOWED_ORIGINS（可选）：允许的CORS来源的逗号分隔列表（例如，http://localhost:3000,https://example.com）。
  - MCP_AUTH_SECRET_KEY（HTTP认证所需）：用于JWT认证的安全密钥（至少32个字符长）。生产环境中至关重要。

文件系统安全：

FS_BASE_DIRECTORY（可选）：定义所有文件系统操作的根目录。这可以是绝对路径或相对于项目根目录的路径（例如，./data_sandbox）。如果设置了此值，服务器的工具将仅限于访问指定（并解析为绝对路径）及其子目录中的文件和目录。这是一个关键的安全功能，以防止意外访问文件系统的其他部分。如果不设置（不推荐用于生产环境），将记录警告，操作不会受到限制。

LLM & API 集成（可选）：

OPENROUTER_APP_URL：您的应用程序在OpenRouter上的URL。
OPENROUTER_APP_NAME：您的应用程序在OpenRouter上的名称。默认为MCP_SERVER_NAME。
OPENROUTER_API_KEY：OpenRouter服务的API密钥。
LLM_DEFAULT_MODEL：默认使用的LLM模型（例如，google/gemini-2.5-flash-preview-05-20）。
LLM_DEFAULT_TEMPERATURE，LLM_DEFAULT_TOP_P，LLM_DEFAULT_MAX_TOKENS，LLM_DEFAULT_TOP_K，LLM_DEFAULT_MIN_P：LLM调用的默认参数。
GEMINI_API_KEY：Google Gemini服务的API密钥。

OAuth代理集成（可选，适用于高级场景）：

OAUTH_PROXY_AUTHORIZATION_URL，OAUTH_PROXY_TOKEN_URL，OAUTH_PROXY_REVOCATION_URL，OAUTH_PROXY_ISSUER_URL，OAUTH_PROXY_SERVICE_DOCUMENTATION_URL，OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS：OAuth代理的配置。

参见src/config/index.ts和.clinerules文件以获取完整的列表和Zod模式定义。

与MCP客户端的使用

要允许MCP客户端（如AI助手）使用此服务器：

运行服务器：从终端启动服务器：

node dist/index.js
# 或者如果您在项目根目录下：
# npm start

配置客户端：将服务器添加到您的MCP客户端配置中。具体方法取决于客户端。

对于STDIO传输（默认）： 通常涉及指定：
- 命令：node
- 参数：已构建服务器可执行文件的绝对路径（例如，/path/to/filesystem-mcp-server/dist/index.js）。
- 环境变量（可选）：根据配置部分设置任何必需的环境变量。
示例MCP设置（概念性）：
```
{
  "mcpServers": {
    "filesystem_stdio": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "debug"
        // 其他相关环境变量
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```
对于HTTP传输： 客户端需要知道服务器的URL（例如，http://localhost:3010）以及如何进行身份验证（例如，提供JWT Bearer令牌，如果设置了MCP_AUTH_SECRET_KEY）。请参考您的MCP客户端文档以了解HTTP服务器配置。

一旦配置并运行，客户端将检测到服务器及其可用工具。

可用工具

服务器提供了以下工具用于文件系统交互：

工具	描述
`set_filesystem_default`	设置当前会话的默认绝对路径。后续工具调用中使用的相对路径将以此默认路径为基础解析。服务器重启后重置。
`read_file`	读取指定文件的整个内容为UTF-8文本。接受相对（解析为默认）或绝对路径。
`write_file`	将内容写入指定文件。如果文件不存在，则创建文件（以及必要的父目录），如果存在，则覆盖。接受相对或绝对路径。
`update_file`	对现有文件执行有针对性的查找和替换操作，使用一个由`{search, replace}`块组成的数组。适用于局部更改。支持纯文本或正则表达式搜索（`useRegex: true`）和替换所有出现（`replaceAll: true`）。接受相对或绝对路径。文件必须存在。
`list_files`	列出指定路径内的文件和目录。选项包括递归列出（`includeNested: true`）和限制条目数量（`maxEntries`）。返回格式化的树形结构。接受相对或绝对路径。
`delete_file`	永久删除特定文件。接受相对或绝对路径。
`delete_directory`	永久删除目录。使用`recursive: true`来删除非空目录及其内容（谨慎使用！）。接受相对或绝对路径。
`create_directory`	在指定路径创建新目录。默认情况下（`create_parents: true`），还会创建任何必要的父目录。接受相对或绝对路径。
`move_path`	移动或重命名文件或目录从源路径到目标路径。接受源路径和目标路径的相对或绝对路径。
`copy_path`	复制文件或目录从源路径到目标路径。对于目录，默认递归复制（`recursive: true`）。接受源路径和目标路径的相对或绝对路径。

参见工具注册文件（src/mcp-server/tools/*/registration.ts）以获取详细的输入/输出模式（Zod/JSON模式）。

项目结构

代码库为了清晰和可维护性而组织：

filesystem-mcp-server/
├── dist/                 # 编译后的JavaScript输出（在npm run build之后）
├── logs/                 # 日志文件（运行时创建）
├── node_modules/         # 项目依赖项
├── src/                  # TypeScript源代码
│   ├── config/           # 配置加载（index.ts）
│   ├── mcp-server/       # 核心MCP服务器逻辑
│   │   ├── server.ts     # 服务器初始化、工具注册、传输处理
│   │   ├── state.ts      # 会话状态管理（例如，默认路径）
│   │   ├── tools/        # 各个工具实现（每个工具一个子目录）
│   │   │   ├── readFile/
│   │   │   │   ├── index.ts
│   │   │   │   ├── readFileLogic.ts
│   │   │   │   └── registration.ts
│   │   │   └── ...       # 其他工具（writeFile，updateFile等）
│   │   └── transports/   # 通信传输实现
│   │       ├── authentication/ # HTTP的认证中间件
│   │       │   └── authMiddleware.ts
│   │       ├── httpTransport.ts
│   │       └── stdioTransport.ts
│   ├── types-global/     # 共享的TypeScript类型和接口
│   │   ├── errors.ts     # 自定义错误类和代码（McpError，BaseErrorCode）
│   │   ├── mcp.ts        # 与MCP相关的类型
│   │   └── tool.ts       # 工具定义类型
│   ├── utils/            # 可重用的实用程序模块，分类
│   │   ├── internal/     # 核心内部实用程序（errorHandler，logger，requestContext）
│   │   ├── metrics/      # 与指标相关的实用程序（tokenCounter）
│   │   ├── parsing/      # 解析实用程序（dateParser，jsonParser）
│   │   ├── security/     # 与安全相关的实用程序（idGenerator，rateLimiter，sanitization）
│   │   └── index.ts      # 所有实用程序的barrel导出
│   └── index.ts          # 主应用入口点
├── .clinerules           # LLM助手的速查表
├── .dockerignore
├── Dockerfile
├── LICENSE
├── mcp.json              # MCP服务器清单（由SDK生成或手动）
├── package.json
├── package-lock.json
├── README.md             # 本文档
├── repomix.config.json
├── smithery.yaml         # 如果使用Smithery配置
└── tsconfig.json         # TypeScript编译器选项

要查看当前结构的实时详细视图，请运行：npm run tree（此脚本可能需要更新，如果src/scripts/tree.ts是更改的一部分）。

开发者提示：此仓库包含一个.clinerules文件。此速查表为您的LLM编码助手提供了关于代码库模式、文件位置和使用示例的重要上下文。随着服务器的发展，请保持其更新！

许可证

本项目根据Apache License 2.0许可。详情请参阅LICENSE文件。

<div align="center"> 由 ❤️ 和 <a href="https://modelcontextprotocol.io/">Model Context Protocol</a> 构建 </div>