Crav MCP Filesystem

文件系统MCP服务器

用于文件系统操作的模型上下文协议（MCP）服务器。使Javari AI能够通过安全沙盒自主创建、读取、更新和验证文件。

特性

• ✅ 创建和管理工作区（项目目录）
• ✅ 创建具有内容验证的文件
• ✅ 读取文件内容
• ✅ 使用自动备份更新文件
• ✅ 安全删除文件
• ✅ 列出目录内容
• ✅ 验证TypeScript编译
• ✅ 生成Next.js项目模板
• ✅ 安全沙盒（防止目录遍历）
• ✅ 文件类型白名单
• ✅ 大小限制
• ✅ 综合录井

安装

npm install

配置

复制 .env.example 到 .env 并配置：

cp .env.example .env

所需变量：

• MCP_API_KEY：MCP身份验证的安全密钥
• STORAGE_PATH：工作区目录（默认：/tmp/javari build）
• MAX_FILE_SIZE：最大文件大小（以字节为单位）（默认值：10MB）

发展

npm run dev

生产

npm run build
npm start

API终点

健康检查

GET /health

创建工作区

POST /api/workspace/create
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123"
}

创建文件

POST /api/files/create
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123",
  "filePath": "src/index.ts",
  "content": "console.log('Hello');"
}

读取文件

GET /api/files/read?workspaceId=project-123&filePath=src/index.ts
Headers: x-api-key: YOUR_MCP_KEY

更新文件

PUT /api/files/update
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123",
  "filePath": "src/index.ts",
  "content": "console.log('Updated');"
}

删除文件

DELETE /api/files/delete
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123",
  "filePath": "src/index.ts"
}

列出目录

GET /api/dirs/list?workspaceId=project-123&dirPath=src
Headers: x-api-key: YOUR_MCP_KEY

验证TypeScript

POST /api/validate/typescript
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123"
}

生成Next.js模板

POST /api/template/nextjs
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123",
  "name": "my-app",
  "typescript": true
}

清洁工作区

DELETE /api/workspace/clean
Headers: x-api-key: YOUR_MCP_KEY
Body: {
  "workspaceId": "project-123"
}

安全特性

沙箱

• 所有文件操作仅限于工作区目录
• 阻止了路径遍历攻击
• 无法访问系统文件

文件类型白名单

允许的扩展名：

• TypeScript： .ts, .tsx
• JavaScript： .js, .jsx
• 配置： .json, .yml, .yaml, .toml
• 文档： .md, .txt
• 网状物： .html, .css
• 环境： .env, .gitignore, .npmrc

大小限制

• 最大文件大小：10MB（可配置）
• 工作区总大小：受监控但未强制执行（在操作系统级别设置）

速率限制

• 每个IP每小时2000个请求
• 防止虐待

文件操作最佳实践

创建文件

1. 始终指定正确的文件扩展名
2. 发送前验证内容
3. 使用workspaceId组织项目

更新文件

• 更新前创建的自动备份
• 备份存储为 filename.backup
• 如果需要，从备份还原

正在验证TypeScript

• 需要 tsconfig.json 在工作空间中
• 跑动 tsc --noEmit 用于类型检查
• 返回带有行号的详细错误消息

部署

铁路（推荐）

railway up

在Railway仪表板中配置环境变量。

确保为装载了持久卷 STORAGE_PATH.

码头工人

docker build -t crav-mcp-filesystem .
docker run -p 3003:3003 -v /data:/tmp/javari-builds --env-file .env crav-mcp-filesystem

监控

检查服务器运行状况：

curl http://localhost:3003/health

错误处理

所有端点返回一致的错误格式：

{
  "error": "Error description",
  "details": "Detailed message"
}

工作空间管理

工作区是每个项目的独立目录：

/tmp/javari-builds/
  ├── project-123/
  │   ├── src/
  │   ├── package.json
  │   └── ...
  ├── project-456/
  │   └── ...

部署后清理工作区以节省存储空间。

日志

• combined.log：所有操作
• error.log：仅错误
• 控制台：实时彩色输出

许可证

麻省理工学院-CR AudioViz AI