Filesystem MCP Server

文件系统 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），请参阅工具注册文件（ src/mcp-server/tools/*/registration.ts ）。

项目结构

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

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

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

执照

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