Filesystem MCP Server

文件系统 MCP 服务

为你的 AI Agent 提供强大、跨平台的文件系统功能，现支持 STDIO 和 Streamable HTTP 传输选项。

这个 Model Context Protocol (MCP) 服务为 AI Agent 提供安全、可靠的接口，以便与本地文件系统交互。它支持读取、写入、更新和管理文件及目录，并基于可用于生产环境的 TypeScript 基础构建，具备全面的日志记录、错误处理和安全措施，现同时支持 STDIO 和 HTTP 传输。

目录

• 概述
• 功能
• 安装
• 配置
• 与 MCP 客户端配合使用
• 可用工具
• 项目结构
• 开发
• 许可证

概述

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

• 读取和分析文件内容。
• 创建、修改或覆盖文件。
• 管理目录和文件路径。
• 在文件中进行定向更新。

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

架构

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

flowchart TB
    subgraph TransportLayer["Transport Layer"]
        direction LR
        STDIO["STDIO Transport"]
        HTTP["HTTP Transport (Express, JWT Auth)"]
    end

    subgraph APILayer["API Layer"]
        direction LR
        MCP["MCP Protocol Interface"]
        Val["Input Validation (Zod)"]
        PathSan["Path Sanitization"]

        MCP --> Val --> PathSan
    end

    subgraph CoreServices["Core Services"]
        direction LR
        Config["Configuration (Zod-validated Env Vars)"]
        Logger["Logging (Winston, Context-aware)"]
        ErrorH["Error Handling (McpError, ErrorHandler)"]
        ServerLogic["MCP Server Logic"]
        State["Session State (Default Path)"]

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

    subgraph ToolImpl["Tool Implementation"]
        direction LR
        FSTools["Filesystem Tools"]
        Utils["Core Utilities (Internal, Security, Metrics, Parsing)"]

        FSTools --> ServerLogic
        Utils -- Used by --> FSTools
        Utils -- Used by --> CoreServices
        Utils -- Used by --> 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 生成。
  • 指标工具：Token 计数。
  • 解析工具：自然语言日期解析、部分 JSON 解析。
• 增强的配置：使用 Zod 验证环境变量，确保设置具备类型安全性和可靠性。
• 类型安全：完全使用 TypeScript 实现，提升可靠性和可维护性。

安装

步骤

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 构建项目：

   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）。如果设置了此项，服务的工具将仅限于访问此指定路径（解析后的绝对路径）及其子目录中的文件和目录。这是一项关键的安全功能，可防止意外访问文件系统的其他部分。如果未设置（不建议用于生产环境），系统将记录一条警告，且操作不会受到限制。

大模型与 API 集成（可选）：

• OPENROUTER_APP_URL：你的应用在 OpenRouter 上的 URL。
• OPENROUTER_APP_NAME：你的应用在 OpenRouter 上的名称。默认为 MCP_SERVER_NAME。
• OPENROUTER_API_KEY：OpenRouter 服务的 API 密钥。
• LLM_DEFAULT_MODEL：要使用的默认大模型（例如，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：大模型调用的默认参数。
• 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 代理的配置。

完整列表和 Zod schema 定义请参阅 src/config/index.ts 和 .clinerules 文件。

在 MCP 客户端中使用

如需让 MCP 客户端（例如 AI 助手）使用此服务：

1. 运行服务： 在终端中启动服务：

   node dist/index.js
   # 或者，如果你位于项目根目录：
   # npm start
   

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

   对于 STDIO 传输（默认）： 通常需要指定：

   • 命令： node
   • 参数： 已构建服务可执行文件的绝对路径（例如 /path/to/filesystem-mcp-server/dist/index.js）。
   • 环境变量（可选）： 设置配置部分中所需的环境变量。

   STDIO 的 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）以及如何进行身份验证（例如，在设置了 MCP_AUTH_SECRET_KEY 时提供 JWT Bearer 令牌）。有关 HTTP 服务配置，请参阅 MCP 客户端文档。

配置并运行后，客户端会检测到此服务及其可用工具。

可用工具

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

工具	描述
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）。接受相对路径或绝对路径。
有关详细的输入/输出架构（Zod/JSON Schema），请参阅工具注册文件（src/mcp-server/tools/*/registration.ts）。

项目结构

代码库的组织方式注重清晰性和可维护性：

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization, tool registration, transport handling
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   ├── tools/        # Individual tool implementations (one subdir per tool)
│   │   │   ├── readFile/
│   │   │   │   ├── index.ts
│   │   │   │   ├── readFileLogic.ts
│   │   │   │   └── registration.ts
│   │   │   └── ...       # Other tools (writeFile, updateFile, etc.)
│   │   └── transports/   # Communication transport implementations
│   │       ├── authentication/ # Auth middleware for HTTP
│   │       │   └── authMiddleware.ts
│   │       ├── httpTransport.ts
│   │       └── stdioTransport.ts
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes (McpError, BaseErrorCode)
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules, categorized
│   │   ├── internal/     # Core internal utilities (errorHandler, logger, requestContext)
│   │   ├── metrics/      # Metrics-related utilities (tokenCounter)
│   │   ├── parsing/      # Parsing utilities (dateParser, jsonParser)
│   │   ├── security/     # Security-related utilities (idGenerator, rateLimiter, sanitization)
│   │   └── index.ts      # Barrel export for all utilities
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .dockerignore
├── Dockerfile
├── LICENSE
├── mcp.json              # MCP server manifest (generated by SDK or manually)
├── package.json
├── package-lock.json
├── README.md             # This file
├── repomix.config.json
├── smithery.yaml         # Smithery configuration (if used)
└── tsconfig.json         # TypeScript compiler options

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

开发者提示： 本仓库包含一个 .clinerules 文件。此速查表为你的 LLM 编码助手提供有关代码库模式、文件位置和用法示例的必要上下文。随着服务的演进，请及时更新！

许可证

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

---