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 /workspace2LLM使用模式
模式1：查找类型声明（未知类型）
当你不知道某个东西是类、结构、接口还是记录时：
search_code({
pattern: "\\b(class|struct|record|interface|enum)\\s+MyType\\b",
filePattern: "*.cs"
})模式2：探索然后阅读
- 搜索您需要的内容：
search_code(pattern="functionName") - 获取文件信息：
get_file_info(path="src/module.ts") - 战略性阅读：
read_file(path="src/module.ts", start_line=0)
模式3：大文件导航
- 检查尺寸：
get_file_info(path="big-file.ts")→ “1500行” - 搜索范围：
search_in_file(path="big-file.ts", pattern="export class") - 遍历匹配：使用搜索中的行号读取特定块
模式4：查找文件，然后搜索
- 查找文件：
find_files(pattern="*Service*.ts") - 在结果中搜索：
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
安全
此服务器实现了多个安全层：
- 目录沙盒：仅访问允许目录内的文件
- Symlink分辨率：通过检查真实路径防止符号链接攻击
- 路径验证：阻止路径遍历尝试（../等）
- 只读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构建。