文件系统 MCP 服务器

通过强大、与平台无关的文件系统功能为您的 AI 代理提供支持。

该模型上下文协议 (MCP)服务器为 AI 代理提供了一个安全可靠的接口，用于与本地文件系统交互。它支持读取、写入、更新和管理文件和目录，并以可用于生产的 TypeScript 基础架构为后盾，并具备全面的日志记录、错误处理和安全措施。

目录

• 概述

• 特征

• 安装

• 配置

• 与 MCP 客户端一起使用

• 可用工具

• 项目结构

• 发展

• 执照

概述

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

• 读取并分析文件内容。

• 创建、修改或覆盖文件。

• 管理目录和文件路径。

• 在文件内执行有针对性的更新。

该服务器采用 TypeScript 构建，强调类型安全性、模块化和强大的错误处理，使其适合可靠地集成到 AI 工作流程中。

建筑学

为了清晰和可维护性，服务器采用分层架构：

• API 层：处理 MCP 通信，使用 Zod 验证输入，并清理路径。

• 核心服务：管理配置、日志记录、错误报告、会话状态（如默认工作目录）和主 MCP 服务器实例。

• 工具实现：包含每个文件系统工具的特定逻辑，利用共享实用程序。

特征

• 全面的文件操作：用于读取、写入、列出、删除、移动和复制文件和目录的工具。

• 有针对性的更新： update_file工具允许在文件内进行精确的搜索和替换操作，支持纯文本和正则表达式。

• 会话感知路径管理： set_filesystem_default工具建立一个默认工作目录，用于在会话期间解析相对路径。

• 安全第一：内置路径清理功能可防止目录遍历攻击。可选的基目录限制功能可增强安全性。

• 强大的基础：包括以下生产级实用程序：

  • 结构化、上下文感知的日志记录。

  • 使用特定错误代码的标准化错误处理。

  • 用于请求跟踪的唯一 ID 生成。

  • 输入清理。

  • 可选速率限制（实用程序文件已创建但尚未集成）。

• 类型安全：在 TypeScript 中完全实现，以提高可靠性和可维护性。

安装

步骤

1. 克隆存储库：

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

2. 安装依赖项：

   npm install

3. 构建项目：

   npm run build

   这会将dist/目录中的 TypeScript 代码编译为 JavaScript，并使主脚本可执行。可执行文件位于dist/index.js 。

配置

使用环境变量配置服务器：

• FS_BASE_DIRECTORY （可选，出于安全考虑建议使用）：

  • 如果设置为绝对路径，服务器执行的所有文件操作都将严格限制在此目录及其子目录中。这可以防止 AI 代理访问预期范围之外的文件。

  • 例如： FS_BASE_DIRECTORY=/Users/casey/safe-agent-files

• LOG_LEVEL （可选）：

  • 控制日志的详细程度。选项： error 、 warn 、 info 、 http 、 verbose 、 debug 、 silly 。

  • 默认为info 。

• LOG_DIR （可选）：

  • 指定存储日志文件（ combined.log 、 error.log ）的目录。

  • 默认为相对于服务器执行目录的./logs 。

与 MCP 客户端一起使用

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

1. **运行服务器：**从终端启动服务器：

   node dist/index.js # Or if you are in the project root: # npm start

2. **配置客户端：**将服务器添加到 MCP 客户端的配置中。具体方法取决于客户端，但通常需要指定以下内容：

   • 命令： node

   • **参数：**构建的服务器可执行文件的绝对路径（例如， /path/to/filesystem-mcp-server/dist/index.js mcp-server/dist/index.js）。

   • **环境变量（可选）：**根据需要设置FS_BASE_DIRECTORY 、 LOG_LEVEL或LOG_DIR 。

   MCP 设置示例（概念）：

   { "mcpServers": { "filesystem": { "command": "node", "args": ["/path/to/filesystem-mcp-server/dist/index.js"], "env": { "FS_BASE_DIRECTORY": "/path/to/base/directory", "LOG_LEVEL": "debug" }, "disabled": false, "autoApprove": [] } // ... other servers } }

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

可用工具

服务器公开了以下用于文件系统交互的工具：

有关详细的输入/输出模式（Zod/JSON Schema），请参阅工具注册文件（

项目结构

代码库的组织清晰且易于维护：

要查看当前结构的实时详细视图，请运行： npm run tree

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

执照

本项目遵循 Apache License 2.0 许可协议。详情请参阅LICENSE文件。