使用说明

文件系统MCP服务器

通过STDIO和Streamable HTTP传输选项，为您的AI代理提供强大的、与平台无关的文件系统功能。

这模型上下文协议（MCP）服务器为AI代理和本地文件系统交互提供了一个安全可靠的接口。它支持读取、写入、更新和管理文件和目录，由生产就绪的TypeScript基础提供支持，该基础具有全面的日志记录、错误处理、安全措施，现在支持这两者 STDIO和HTTP传输.

概述

模型上下文协议（MCP）是一个标准框架，允许AI模型与外部工具和数据源（资源）安全地交互。此服务器实现了MCP标准，将基本的文件系统操作作为工具公开，使AI代理能够：

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

该服务器采用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 该工具建立了一个默认工作目录，用于在会话期间解析相对路径。
双重运输支持:
- 工作室：作为子进程运行时，用于直接、高效的通信。
- 超文本传输协议：用于基于网络的交互，具有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.

配置

使用环境变量（a）配置服务器 .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 （可选）：定义所有文件系统操作的根目录。这可能是 绝对路径 或a 相对于项目根的路径 （例如。， ./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
# Or if you are in the project root:
# npm start

配置客户端： 将服务器添加到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"
        // Other relevant env vars
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```
对于HTTP传输： 客户端将需要知道服务器的URL（例如。， http://localhost:3010)以及如何进行身份验证（例如，在以下情况下提供JWT承载令牌 MCP_AUTH_SECRET_KEY 已设置）。有关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`).接受相对或绝对路径。

请参阅工具注册文件(src/mcp-server/tools/*/registration.ts)详细的输入/输出模式（Zod/JSON模式）。

项目结构

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

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 是变化的一部分）。

开发者说明： 此存储库包括 .微规则文件。此备忘单为您的LLM编码助手提供了有关代码库模式、文件位置和使用示例的基本上下文。随着服务器的发展保持更新！

许可证

此项目根据Apache许可证2.0获得许可。请参阅许可证文件以获取详细信息。

Built with ❤️ and the Model Context Protocol

使用说明

文件系统MCP服务器

目录

概述

建筑

特性

安装

步骤

配置

与MCP客户端一起使用

可用工具

项目结构

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器