AI导哈

智能文件系统服务器

一个专为AI代理交互优化的智能文件系统服务器，提供文件分页、快速代码搜索和安全沙箱等功能。

  • by lofcz
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 lofcz/mcp-filesystem-smart

使用说明

MCP智能文件系统服务器

一个LLM优化的模型上下文协议（MCP）文件系统服务器，具有智能功能，旨在实现有效的AI代理交互。

特性

🚀 智能文件分页

  • 自动将大文件（>500行）分块为可管理的部分
  • 简单 start_line 便于导航的参数
  • 当有更多内容可用时，明确指示
  • 防止LLM对话中的上下文溢出

⚡ Ripgrep集成

  • 在整个代码库中快速搜索代码
  • 正则表达式模式支持，并提供有用的示例
  • 特定于文件的搜索（如使用正则表达式的Ctrl+F）
  • 按文件类型、路径等灵活筛选

🔒 安全沙盒

  • 严格的目录访问控制
  • Symlink攻击防御
  • 路径遍历保护
  • 仅访问允许目录内的文件

🎯 LLM友好设计

  • 回复中的有用建议
  • 常见搜索模式示例
  • 大文件的阅读策略建议
  • 清晰的错误信息和可操作的指导

工具

1. list_directory

列出包含元数据的目录内容。

{
  "path": "src"
}

退货： 文件、目录、大小、行数和摘要统计信息。

2. read_file

读取文件内容，对大文件进行自动分页。

{
  "path": "src/large-file.ts",
  "start_line": 0
}

对于大于500行的文件，返回前500行 hasMore: true 和 nextStartLine.
阅读下一块 start_line: 500那么 1000等等。

3. 搜索代码

使用ripgrep搜索代码模式（非常快）。

示例：

查找任何类型声明（类/结构/接口/枚举）：

{
  "pattern": "\\b(class|struct|interface|enum)\\s+ServiceName\\b",
  "filePattern": "*.ts"
}

使用任何访问修饰符查找方法：

{
  "pattern": "\\b(public|private|protected).*\\s+methodName\\s*\\(",
  "path": "src/directory"
}

查找所有异步函数：

{
  "pattern": "async\\s+.*\\s*\\(",
  "caseInsensitive": true,
  "contextLines": 3
}

选项：

  • pattern （必填）：正则表达式模式
  • path：限制到特定目录
  • filePattern：文件glob（例如。， *.js, *.{ts,tsx}, !*test*)
  • caseInsensitive：忽略案例
  • contextLines：上下文行（默认值：2）
  • maxResults：最大结果（默认值：50）
  • literalString：按字面意思处理，而不是正则表达式
  • wordBoundary：仅匹配整个单词

4. search_in_file

在特定文件内搜索（如使用正则表达式的Ctrl+F）。

{
  "path": "src/server.ts",
  "pattern": "app\\.use\\(",
  "contextLines": 3
}

5. 查找文件

按名称模式查找文件。

{
  "pattern": "*Handler*.ts"
}

模式示例：

  • config.json -确切名称
  • *.config -通配符
  • *Service* -包含“服务”
  • *.{ts,tsx,js} -多个扩展

6. 获取_文件_信息

在不读取内容的情况下获取文件元数据。

{
  "path": "src/large-file.ts"
}

退货： 大文件的大小、行数、语言、二进制状态和读取策略。

7. list_allowed_directories

显示可访问的目录（安全边界）。

{}

安装

Docker（推荐）

# Build image
docker build -t mcp-filesystem-smart .

# Run with workspace mounted
docker run -i --rm \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart

这 :ro 标志使目录为只读，以提高安全性。

通过环境变量进行配置

使用环境变量自定义行为：

docker run -i --rm \
  -e MCP_LINES_PER_PAGE=1000 \
  -e MCP_MAX_SEARCH_RESULTS=200 \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart

可用变量：

  • MCP_LINES_PER_PAGE -读取文件时每页行数（默认值：500）
  • MCP_MAX_SEARCH_RESULTS -每页搜索结果（默认值：100）

本地安装

npm install
npm run build
node dist/index.js /path/to/allowed/directory

与MCP客户端一起使用

配置示例

{
  "mcpServers": {
    "filesystem-smart": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/projects/myapp:/workspace:ro",
        "mcp-filesystem-smart"
      ]
    }
  }
}

允许多个目录

# Local
node dist/index.js /path/to/dir1 /path/to/dir2

# Docker (mount multiple volumes)
docker run -i --rm \
  -v /path/to/dir1:/workspace1:ro \
  -v /path/to/dir2:/workspace2:ro \
  mcp-filesystem-smart /workspace1 /workspace2

LLM使用模式

模式1：查找类型声明（未知类型）

当你不知道某个东西是类、结构、接口还是记录时：

search_code({
  pattern: "\\b(class|struct|record|interface|enum)\\s+MyType\\b",
  filePattern: "*.cs"
})

模式2：探索然后阅读

  1. 搜索您需要的内容： search_code(pattern="functionName")
  2. 获取文件信息： get_file_info(path="src/module.ts")
  3. 战略性阅读： read_file(path="src/module.ts", start_line=0)

模式3：大文件导航

  1. 检查尺寸： get_file_info(path="big-file.ts") → “1500行”
  2. 搜索范围： search_in_file(path="big-file.ts", pattern="export class")
  3. 遍历匹配：使用搜索中的行号读取特定块

模式4：查找文件，然后搜索

  1. 查找文件： find_files(pattern="*Service*.ts")
  2. 在结果中搜索： search_code(pattern="constructor", path="src/services")

常见搜索模式

C网

// Find any type
"\\b(class|struct|record|interface|enum)\\s+TypeName\\b"

// Find method
"\\b(public|private|protected|internal).*\\s+MethodName\\s*\\("

// Find async methods
"async\\s+(Task|ValueTask)<.*>\\s+\\w+\\s*\\("

Types/JavaScript

// Find function/method
"(function|const|let|var)\\s+\\w+\\s*=.*=>|function\\s+\\w+\\s*\\("

// Find class/interface
"(class|interface)\\s+\\w+"

// Find async functions
"async\\s+(function|\\w+\\s*=>|\\(.*\\)\\s*=>)"

python

// Find class
"class\\s+\\w+.*:"

// Find function
"def\\s+\\w+\\s*\\("

// Find async function
"async\\s+def\\s+\\w+"

需求

  • Node.js：22或以上
  • ripgrep：必须在PATH中安装并可用
    • Alpine Linux： apk add ripgrep
    • Ubuntu/Debian： apt install ripgrep
    • macOS： brew install ripgrep
    • 窗户： choco install ripgrep

安全

此服务器实现了多个安全层：

  1. 目录沙盒：仅访问允许目录内的文件
  2. Symlink分辨率：通过检查真实路径防止符号链接攻击
  3. 路径验证：阻止路径遍历尝试（../等）
  4. 只读Docker：将卷装载为 :ro 用于只读访问

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Test locally
node dist/index.js $(pwd)

许可证

麻省理工学院

鸣谢

基于模型上下文协议（MCP）SDK和ripgrep构建。

相关 MCP