使用说明

MCP文件系统服务器

具有严格安全边界的AI代理的高级文件系统操作。部分 AI功能套件.

🔗 仓库

此软件包保存在 AI功能套件 monorepo。

概述

MCP文件系统服务器为AI代理提供了基本读/写之外的高级文件操作，包括：

批量操作：使用回滚支持原子地执行多个文件操作
目录监视：通过事件过滤实时监控文件系统更改
文件搜索和索引：具有元数据过滤功能的快速全文搜索
校验和操作：计算并验证文件完整性（MD5、SHA-1、SHA-256、SHA-512）
Symlink管理：在工作区边界内创建和管理符号链接
磁盘使用情况分析：分析目录大小并识别大文件
目录操作：递归复制、同步和原子文件替换

所有操作都限制在严格的安全边界内，以防止未经授权的访问。

🚨 安全第一

关键的：此服务器通过10层路径验证实现了深度防御安全。所有操作都仅限于配置的工作区根。看安全.md 获取完整的安全文档。

安装

NPM

npm install -g @ai-capabilities-suite/mcp-filesystem

纱线

yarn global add @ai-capabilities-suite/mcp-filesystem

码头工人

docker pull ghcr.io/digital-defiance/mcp-filesystem:latest

看医生.md Docker部署指南。

快速开始

1.创建配置文件

创建 mcp-filesystem-config.json 文件：

{
  "workspaceRoot": "/path/to/your/workspace",
  "blockedPaths": [".git", ".env", "node_modules"],
  "blockedPatterns": ["*.key", "*.pem", "*.env"],
  "maxFileSize": 104857600,
  "maxBatchSize": 1073741824,
  "maxOperationsPerMinute": 100,
  "enableAuditLog": true,
  "readOnly": false
}

2.启动服务器

mcp-filesystem --config ./mcp-filesystem-config.json

3.在MCP客户端中配置

添加到您的MCP客户端配置中（例如，Claude Desktop、Kiro）：

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": ["--config", "/path/to/mcp-filesystem-config.json"]
    }
  }
}

可用工具

服务器为文件系统操作提供了12个MCP工具：

1.fs_batch_operations

使用回滚支持原子地执行多个文件系统操作。

参数：

operations：操作数组（复制、移动、删除）
atomic：Boolean（默认值：true）-失败时全部回滚

例子：

{
  "operations": [
    { "type": "copy", "source": "file1.txt", "destination": "backup/file1.txt" },
    { "type": "move", "source": "temp.txt", "destination": "archive/temp.txt" },
    { "type": "delete", "source": "old.txt" }
  ],
  "atomic": true
}

2.fs_watch_directory

监控目录中的文件系统更改。

参数：

path：要查看的目录
recursive：布尔值-监视子目录
filters：用于过滤事件的glob模式数组

退货： 用于检索事件的会话ID

例子：

{
  "path": "src",
  "recursive": true,
  "filters": ["*.ts", "*.js"]
}

3.fs_get_watch_events

从监视会话中检索累积的事件。

参数：

sessionId：从fs_Watch_directory监视会话ID

退货： 文件系统事件数组（创建、修改、删除、重命名）

4.fs_stop_watch

停止目录监视会话并清理资源。

参数：

sessionId：监视会话ID以停止

5.fs_search_files

按名称、内容或元数据搜索文件。

参数：

query：搜索查询字符串
searchType：“名称”、“内容”或“两者都有”
fileTypes：要筛选的文件扩展名数组
minSize, maxSize：大小限制（以字节为单位）
modifiedAfter：ISO日期字符串
useIndex：Boolean-使用文件索引进行更快的搜索

例子：

{
  "query": "TODO",
  "searchType": "content",
  "fileTypes": [".ts", ".js"],
  "useIndex": true
}

6.fs_build_index

构建一个可搜索的文件索引，以便快速搜索。

参数：

path：要索引的目录
includeContent：布尔值-索引文件内容（仅限文本文件）

退货： 索引统计（文件计数、总大小、索引大小）

7.fs_create_symlink

在工作空间内创建符号链接。

参数：

linkPath：将创建符号链接的路径
targetPath：符号链接指向的路径（必须在工作区内）

8.fs_计算机_校验和

计算文件校验和以进行完整性验证。

参数：

path：文件路径
algorithm：“md5”、“sha1”、“sha256”或“sha512”

退货： 校验和十六进制字符串

9.fs_verify_checksum

验证文件的校验和是否与预期值匹配。

参数：

path：文件路径
checksum：预期的校验和十六进制字符串
algorithm：使用的哈希算法

退货： 布尔验证结果

10.fs_analysize_disk_usage

分析磁盘使用情况并识别大文件/目录。

参数：

path：要分析的目录
depth：可穿越的最大深度
groupByType：布尔值-按文件扩展名对结果进行分组

退货： 包含大小、最大文件和类型细分的使用情况报告

11.fs_copy_directory

使用选项递归复制目录。

参数：

source：源目录
destination：目标目录
preserveMetadata：Boolean-保留时间戳和权限
exclusions：要排除的glob模式数组

退货： 复制统计信息（复制的文件、传输的字节数、持续时间）

12.fs_sync_directory

通过仅复制较新或缺失的文件来同步目录。

参数：

source：源目录
destination：目标目录
exclusions：要排除的glob模式数组

退货： 同步统计信息（复制的文件、跳过的文件、传输的字节数）

配置参考

所需配置

workspaceRoot：工作区目录的绝对路径（必需）
- 所有操作都仅限于此目录
- 服务器启动后无法更改

安全配置

允许的子目录：工作区内的子目录数组（可选）
- 如果指定，操作将进一步限制在这些路径上
- 例子： ["src", "tests", "docs"]
封锁的路径：要阻止的路径数组（相对于工作区）
- 例子： [".git", ".env", "node_modules", ".ssh"]
块状图案：要阻止的正则表达式模式数组
- 例子： ["*.key", "*.pem", "*.env", "*secret*", "*password*"]

资源限制

最大文件大小：最大文件大小（以字节为单位）（默认值：100MB）
maxBatchSize：批处理操作的最大总大小（默认值：1GB）
每分钟最大操作数：每个代理的费率限制（默认值：100）

操作设置

启用审核日志：启用操作日志记录（默认值：true）
要求确认：破坏性操作需要确认（默认值：true）
只读：启用只读模式（默认值：false）

安全功能

多层安全架构

服务器实现了10层路径验证：

绝对路径分辨率：防止相对路径技巧
工作区边界检查：确保路径在工作区内
路径遍历检测：块 .. 和 ./ 序列
系统路径阻止列表：硬编码系统目录（不能覆盖）
敏感模式阻止列表：硬编码敏感文件（不能覆盖）
子目录限制：工作区内的可选满列表
用户阻止列表：自定义阻止路径
用户模式阻止列表：自定义块状图案
只读模式：防止写入/删除操作
Symlink验证：验证符号链接目标是否在工作区内

硬编码安全（无法禁用）

系统路径（始终被阻止）：

/etc, /sys, /proc, /dev, /boot, /root
C:\Windows, C:\Program Files
/System, /Library, /Applications （macOS）
/bin, /sbin, /usr/bin, /usr/sbin

敏感图案（始终被屏蔽）：

.ssh/, .aws/, .kube/
id_rsa, *.pem, *.key, *.p12, *.pfx
包含以下内容的文件： password, secret, token
.env 文件

审计日志

所有操作都记录在：

时间戳
操作类型
涉及的路径
结果（成功/失败）
单独记录安全违规行为

使用示例

示例1：批处理文件操作

// Copy multiple files atomically
const result = await mcpClient.callTool("fs_batch_operations", {
  operations: [
    { type: "copy", source: "src/file1.ts", destination: "backup/file1.ts" },
    { type: "copy", source: "src/file2.ts", destination: "backup/file2.ts" },
    { type: "copy", source: "src/file3.ts", destination: "backup/file3.ts" },
  ],
  atomic: true, // All succeed or all rollback
});

示例2：监视目录的更改

// Start watching
const watchResult = await mcpClient.callTool("fs_watch_directory", {
  path: "src",
  recursive: true,
  filters: ["*.ts", "*.tsx"],
});

const sessionId = watchResult.sessionId;

// Later, get events
const events = await mcpClient.callTool("fs_get_watch_events", {
  sessionId,
});

// Stop watching
await mcpClient.callTool("fs_stop_watch", { sessionId });

示例3：使用索引搜索文件

// Build index first
await mcpClient.callTool("fs_build_index", {
  path: "src",
  includeContent: true,
});

// Fast search using index
const results = await mcpClient.callTool("fs_search_files", {
  query: "TODO",
  searchType: "content",
  fileTypes: [".ts", ".js"],
  useIndex: true,
});

示例4：验证文件完整性

// Compute checksum
const checksumResult = await mcpClient.callTool("fs_compute_checksum", {
  path: "important-file.zip",
  algorithm: "sha256",
});

// Later, verify integrity
const verifyResult = await mcpClient.callTool("fs_verify_checksum", {
  path: "important-file.zip",
  checksum: checksumResult.checksum,
  algorithm: "sha256",
});

示例5：同步目录

// Sync only newer/missing files
const syncResult = await mcpClient.callTool("fs_sync_directory", {
  source: "src",
  destination: "backup",
  exclusions: ["*.test.ts", "node_modules/**"],
});

console.log(
  `Copied: ${syncResult.filesCopied}, Skipped: ${syncResult.filesSkipped}`
);

故障排除

错误：“检测到路径遍历-工作区外的路径”

原因：正在尝试访问配置的工作区根目录之外的文件。

解决方案:

验证您的 workspaceRoot 配置正确
确保所有路径都相对于工作区根目录
检查 .. 路径中的序列

错误：“无法访问系统目录”

原因：正在尝试访问硬编码的系统路径。

解决方案：出于安全考虑，这些路径始终被阻止。配置您的工作区以避免使用系统目录。

错误：“无法访问敏感文件”

原因：尝试访问与敏感模式匹配的文件(.ssh/, *.key等等）。

解决方案：这些模式总是被屏蔽的。如果需要访问这些文件，则必须将其重命名或移动到敏感模式之外。

错误：“超出速率限制”

原因：短时间内操作过多。

解决方案:

增加 maxOperationsPerMinute 在配置中
使用批处理操作 fs_batch_operations
增加操作之间的延迟

错误：“文件大小超过最大值”

原因：文件大小超过 maxFileSize 配置。

解决方案：增加 maxFileSize 在配置或拆分大文件时。

观看未出现的事件

原因：事件可能已被筛选或观察会话未处于活动状态。

解决方案:

验证监视会话是否处于活动状态，并使用正确的 sessionId
检查 filters 参数-确保模式与文件匹配
确保文件在监视的目录中（检查 recursive 设置）

搜索未返回任何结果

原因：索引可能已过时或搜索参数限制过多。

解决方案:

使用重建索引 fs_build_index
检查 fileTypes 筛选器未排除您的文件
验证 query 匹配文件内容/名称
试试看 useIndex: false 用于文件系统搜索

Symlink创建失败

原因：Symlink目标位于工作区之外。

解决方案：所有符号链接目标都必须位于工作区根目录内。这是一项安全要求，不能禁用。

性能提示

对大型代码库使用索引：使用以下内容构建索引 fs_build_index 更快的搜索
批量操作：使用 fs_batch_operations 而不是单独操作
筛选监视事件：使用特定的glob模式来减少事件量
限制搜索范围：使用 fileTypes 调整过滤器的大小以缩小搜索结果的范围
增量同步：使用 fs_sync_directory 尽可能不使用完整副本

发展

从源头构建

git clone https://github.com/Digital-Defiance/ai-capabilities-suite.git
cd ai-capabilities-suite/packages/mcp-filesystem
yarn install
yarn build

运行测试

yarn test              # Run all tests
yarn test:coverage     # Run with coverage
yarn test:watch        # Watch mode

本地运行

yarn build
node dist/cli.js --config ./config.json

贡献

欢迎投稿！请看贡献.md 在根存储库中。

许可证

MIT许可证-请参阅许可证了解详情。

支持

问题: GitHub问题
电子邮件: info@digitaldefiance.org
文档: 全部文件

致谢

内置：

模型上下文协议SDK
乔基达尔 -文件监视
周古。 -全文搜索
快速地球仪 -快速文件模式匹配

使用说明

MCP文件系统服务器

🔗 仓库

概述

🚨 安全第一

安装

NPM

纱线

码头工人

快速开始

1.创建配置文件

2.启动服务器

3.在MCP客户端中配置

可用工具

1.fs_batch_operations

2.fs_watch_directory

3.fs_get_watch_events

4.fs_stop_watch

5.fs_search_files

6.fs_build_index

7.fs_create_symlink

8.fs_计算机_校验和

9.fs_verify_checksum

10.fs_analysize_disk_usage

11.fs_copy_directory

12.fs_sync_directory

配置参考

所需配置

安全配置

资源限制

操作设置

安全功能

多层安全架构

硬编码安全（无法禁用）

审计日志

使用示例

示例1：批处理文件操作

示例2：监视目录的更改

示例3：使用索引搜索文件

示例4：验证文件完整性

示例5：同步目录

故障排除

错误：“检测到路径遍历-工作区外的路径”

错误：“无法访问系统目录”

错误：“无法访问敏感文件”

错误：“超出速率限制”

错误：“文件大小超过最大值”

观看未出现的事件

搜索未返回任何结果

Symlink创建失败

性能提示

发展

从源头构建

运行测试

本地运行

贡献

许可证

支持

相关项目

致谢

相关 MCP

网页内容抓取服务

图像压缩微服务

文件系统模型上下文协议服务器

域名批量检查服务

文件系统与Git操作服务器

网页内容抓取服务