文件系统资源管理器MCP服务器
一个安全的TypeScript MCP（模型上下文协议）服务器，允许使用谷歌的Gemini AI对您的文件系统进行自然语言查询。用户可以问“我在哪里可以找到我的简历文档？”等问题，并获得由AI驱动的文件系统探索提供的智能响应。
特性
- 自然语言查询：用简单的英语询问有关文件的问题
- 人工智能驱动的规划：Gemini AI分析查询并创建执行计划
- 安全的文件系统访问：所有操作都包含在配置的根目录中
- 多种工具类型：列出文件、按名称搜索、读取文本文件和获取文件元数据
- React客户端接口：用户友好的网络交互界面
- 全面安全：输入净化、路径验证和速率限制
- 详细日志记录：所有人工智能决策和工具执行的审计跟踪
建筑
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ React Client │───▶│ MCP Server │───▶│ Gemini AI │
│ (Vite SPA) │ │ (TypeScript) │ │ Agent │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Filesystem │
│ Tools │
│ (Secure) │
└─────────────────┘快速开始
1.安装依赖项
npm install2.环境设置
复制 .env.example 向 .env 并配置：
cp .env.example .env编辑 .env:
- 集
GEMINI_API_KEY到您的Google AI API密钥 - 集
ROOT_DIR到要浏览的目录（默认为./sandbox) - 集
API_TOKEN到用于客户端身份验证的安全令牌
3.创建沙盒目录
mkdir sandbox
# Add some test files and directories
mkdir sandbox/documents sandbox/projects
echo "John Doe Resume" > sandbox/documents/resume.txt
echo "My Project" > sandbox/projects/readme.md4.构建和运行
# Development mode (with hot reload)
npm run dev
# Or build and run for production
npm run build
npm start服务器将于启动 http://localhost:3001.
5.测试API
curl -X POST http://localhost:3001/api/query \
-H "Content-Type: application/json" \
-H "X-API-Token: token" \
-d '{"text": "What files are in the documents folder?"}'可用工具
MCP服务器将这些安全文件系统工具暴露给AI代理：
list_files(dir, page?, limit?)
- 列出指定路径中的文件和目录
- 支持对大型目录进行分页
- 返回元数据：名称、isDir、大小、修改时间
read_file(path, maxBytes?)
- 读取文本文件的内容（默认情况下最大200KB）
- 自动检测并拒绝二进制文件
- 为各种故障情况返回有意义的错误代码
search_files(directory, query, depth?, limit?)
- 在目录树中按名称（而非内容）搜索文件
- 可配置的搜索深度和结果限制
- 不区分大小写的文件名匹配
get_file_info(path)
- 返回有关文件或目录的详细元数据
- 包括大小、修改时间和文件权限
API终点
POST /api/query
提交关于文件系统的自然语言查询。
标题：
Content-Type: application/jsonX-API-Token:
请求正文：
{
"text": "Where can I find my resume documents?"
}答复：
{
"success": true,
"explanation": "I'll search for files containing 'resume' in their name.",
"data": { /* Tool execution results */ },
"toolCalls": [
{
"tool": "search_files",
"params": { "directory": ".", "query": "resume" },
"result": { /* Search results */ }
}
]
}GET /health
健康检查端点。
答复：
{
"status": "healthy",
"timestamp": "2024-01-01T00:00:00.000Z",
"rootDir": "/path/to/root"
}安全功能
路径安全
- 所有路径都相对于配置的路径进行解析
ROOT_DIR - 目录遍历攻击(
../../../etc/passwd)被阻止 - 绝对路径被拒绝
- 空字节注入保护
输入验证
- 使用定时安全比较的API令牌验证
- 文件路径清理和验证
- 搜索查询净化以防止正则表达式注入
- 读取操作的文件大小限制
速率限制
- 可配置每个客户端的速率限制
- 基于内存的实现，具有自动清理功能
- 防止滥用和资源枯竭
日志记录和审计
- 所有人工智能决策和工具调用都会被记录下来
- 日志中的敏感信息已被净化
- 结构化JSON日志记录，便于分析
React客户端
附带的React客户端提供了一个用户友好的界面：
- 自然语言输入：提问文本区
- 查询示例：预构建查询建议
- 丰富的结果显示：格式化的文件列表、搜索结果和文件内容
- 查询历史：最近带有成功/失败指示器的查询
- 实时反馈：加载状态和错误处理
客户端功能
- 文件和目录图标便于识别
- 格式化文件大小和修改日期
- 可扩展的工具调用结果
- 复制粘贴友好的文件路径
- 移动和桌面的响应式设计
发展
项目结构
src/
├── server.ts # Main Express server
├── filesystem-tools.ts # Secure filesystem operations
├── gemini-agent.ts # Gemini AI integration
├── security.ts # Security utilities
└── logger.ts # Logging utilities
client/ # React client (included as artifact)
├── src/
│ └── App.tsx # Main React component
└── package.json # Client dependencies可用脚本
npm run dev # Development server with hot reload
npm run build # Build for production
npm start # Start production server
npm run type-check # TypeScript type checking
npm run lint # ESLint code linting
npm test # Run tests
npm run clean # Clean build directory测试
带卷曲的API基本测试：
# Test health endpoint
curl http://localhost:3001/health
# Test file listing
curl -X POST http://localhost:3001/api/query \
-H "Content-Type: application/json" \
-H "X-API-Token: your-token" \
-d '{"text": "List all files in the root directory"}'
# Test file search
curl -X POST http://localhost:3001/api/query \
-H "Content-Type: application/json" \
-H "X-API-Token: your-token" \
-d '{"text": "Find files containing the word config"}'
# Test file reading
curl -X POST http://localhost:3001/api/query \
-H "Content-Type: application/json" \
-H "X-API-Token: your-token" \
-d '{"text": "Read the contents of readme.txt"}'查询示例
以下是一些您可以尝试的自然语言查询示例：
文件发现
- “我在哪里可以找到我的简历文件？”
- “显示所有PDF文件”
- “我有什么配置文件？”
- “查找上周修改的文件”
目录探索
- “文档文件夹中有什么？”
- “列出根目录中的所有目录”
- “显示项目目录的结构”
- “最大的目录中有哪些文件？”
内容分析
- “阅读README文件”
- “显示config.json的内容”
- “错误日志文件中有什么？”
- “显示许可证文件的第一部分”
文件信息
- “获取有关该大文件的详细信息”
- “上次修改数据库文件是什么时候？”
- “备份目录的大小是多少？”
- “显示所有图像文件的信息”
部署
生产注意事项
- 环境变量：使用安全、随机生成的令牌
- 超文本传输安全协议：使用SSL/TLS在反向代理后部署
- 速率限制：为您的用例配置适当的限制
- 文件权限：以所需的最小文件系统权限运行
- 监控：设置日志聚合和监控
- 备份：定期备份重要目录
Docker部署
创建一个 Dockerfile:
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
COPY .env ./
USER node
EXPOSE 3001
CMD ["node", "dist/server.js"]构建并运行：
npm run build
docker build -t mcp-filesystem-server .
docker run -p 3001:3001 -v /your/files:/app/sandbox mcp-filesystem-server环境特定配置
发展
NODE_ENV=development
LOG_LEVEL=debug
ROOT_DIR=./sandbox生产
NODE_ENV=production
LOG_LEVEL=info
ROOT_DIR=/app/data
RATE_LIMIT_MAX_REQUESTS=30故障排除
常见问题
“无效的API令牌”错误
- 检查一下
X-API-Token标题与您的匹配.env文件 - 确保令牌中没有多余的空格
“目录访问被拒绝”错误
- 验证请求的路径是否在
ROOT_DIR - 检查文件系统权限
“Gemini API调用失败”错误
- 验证您的
GEMINI_API_KEY有效且有效 - 检查您的Google AI配额和计费状态
“文件太大”错误
- 默认情况下无法读取超过200KB的文件
- 调整
maxBytes参数或用途get_file_info相反
调试模式
启用详细日志记录：
LOG_LEVEL=debug npm run dev这将显示：
- 所有API请求和响应
- Gemini AI提示和响应
- 工具执行细节
- 安全验证步骤
安全最佳实践
服务器安全
- 始终以所需的最小文件权限运行
- 使用强大、独特的API令牌
- 在生产环境中实施适当的HTTPS
- 依赖关系的定期安全更新
- 监控异常访问模式
文件系统安全
- 集
ROOT_DIR走尽可能严格的道路 - 避免暴露系统目录
- 尽可能使用只读挂载
- 定期备份重要数据
- 文件完整性监控
AI安全
- 监控人工智能对意外行为的反应
- 记录所有人工智能决策以供审计
- 实施查询复杂性限制
- 费率限制昂贵的操作
- 定期查看Gemini的使用情况和成本
贡献
- 分叉存储库
- 创建要素分支：
git checkout -b feature-name - 使用正确的TypeScript类型进行更改
- 添加新功能的测试
- 运行linting和类型检查：
npm run lint && npm run type-check - 提交带有详细描述的拉取请求
代码的风格
- 使用TypeScript严格模式
- 遵循现有代码格式
- 为公共API添加JSDoc注释
- 包括对所有外部呼叫的错误处理
- 写有意义的提交消息
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
对于问题和疑问：
- 检查上面的故障排除部分
- 查看服务器日志以了解错误详细信息
- 使用curl进行测试，以隔离客户端和服务器问题
- 在复制步骤中产生问题
路线图
计划的未来增强功能：
- \[\]基于内容的文件搜索（不仅仅是文件名）
- \[\]文件上传/修改功能
- \[\]与其他MCP服务器集成
- \[\]通过文件内容分析增强AI上下文
- \[\]实时文件系统监视
- \[\]具有权限的多用户支持
- \[\]自定义工具插件系统