file manipulationby mcpserver

MCP文件系统Web应用程序

一个全栈web应用程序，它提供了一个使用模型上下文协议（MCP）管理文件的现代界面。此应用程序允许用户通过React前端、自然语言命令和安全的MCP后端执行文件操作。

🚀 特性

• 现代Web界面：基于React的前端，支持拖放文件上传
• 自然语言命令：使用简明英语执行文件操作
• 安全文件操作：创建、读取、编辑、删除和列出文件
• 实时日志记录：实时操作日志和状态监控
• 文件资源管理器：具有可视化文件管理的交互式文件树
• RESTful API：用于前端后端通信的HTTP桥
• TypeScript：整个堆栈的全类型安全

📋 先决条件

在开始之前，请确保已安装以下内容：

• Node.js （v18或更高版本）
• npm （v8或更高）
• Git （用于克隆存储库）

🏗️ 项目结构

mcp-filesystem/
├── client/                 # MCP Client SDK
│   ├── src/
│   │   ├── client.ts      # Type-safe MCP client
│   │   └── utils/
│   │       └── PromptParser.ts
│   └── package.json
├── frontend/              # React Frontend
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── utils/         # Utility functions
│   │   ├── clientHttp.ts  # HTTP client for API calls
│   │   └── main.tsx       # Main React app
│   ├── index.html
│   └── package.json
├── server/                # MCP Backend Server
│   ├── src/
│   │   ├── server.ts      # MCP server implementation
│   │   ├── httpBridge.ts  # HTTP bridge for frontend
│   │   └── main.tsx       # Server entry point
│   └── package.json
└── workspace/            # File storage directory

🛠️ 安装和设置

步骤1：克隆存储库

git clone 
cd mcp-filesystem

步骤2：安装依赖项

为所有三个组件安装依赖关系：

# Install client dependencies
cd client
npm install

# Install frontend dependencies
cd ../frontend
npm install

# Install server dependencies
cd ../server
npm install

步骤3：创建工作区目录

# From the project root
mkdir workspace

🚀 运行应用程序

步骤1：启动后端服务器

cd server
npm run http

这将启动HTTP网桥服务器 http://localhost:3001 具有以下端点：

• GET /health -健康检查
• POST /api/files -创建文件
• PUT /api/files -编辑文件
• DELETE /api/files -删除文件
• GET /api/files -读取文件
• GET /api/files/list -列出文件

步骤2：启动前端

cd frontend
npm run dev

这将启动React开发服务器 http://localhost:5173.

步骤3：访问应用程序

打开浏览器并导航到 http://localhost:5173 访问MCP文件系统Web应用程序。

📖 使用指南

文件上传

1. 拖放：将文件或文件夹直接拖动到上传区域
2. 单击以选择：单击上传区域打开文件选择器
3. 多个文件：一次选择多个文件
4. 实时反馈：查看上传进度和状态

自然语言命令

使用命令输入框使用自然语言执行文件操作：

创建文件

create test.txt
create config.json with content '{"key": "value"}'
make a new file called readme.md
new file called data.csv

编辑文件

edit test.txt
edit config.json with content '{"updated": "content"}'
modify readme.md
update data.csv

删除文件

delete old.txt
remove temp.json
erase backup.log

读取文件

read config.json
show test.txt
display readme.md

列出文件

list files
show all files
what files are in the directory

文件资源管理器

• 导航：单击文件夹以导航到其中
• 回去：使用“..”按钮返回父目录
• 文件操作：在文件上使用操作按钮：

- 👁️ 读取文件内容 - ✏️ 编辑文件内容 - 🗑️ 删除文件 - 📂 打开目录（用于文件夹）

• 刷新：单击刷新按钮以更新文件列表

状态监测

右侧面板显示：

• 连接状态：与MCP服务器的实时连接
• 操作日志：所有文件操作的详细日志
• 错误消息：清除错误报告
• 成功确认：操作成功通知

🔧 发展

项目架构

前端（React+TypeScript）

• 组件：每个UI部分的模块化React组件
• 状态管理：本地状态的React挂钩
• HTTP客户端：用于API通信的自定义客户端
• 样式：具有响应式设计的CSS模块

后端（Node.js+TypeScript）

• MCP服务器：实现模型上下文协议
• HTTP网桥：用于前端通信的Express服务器
• 文件操作：保护文件系统操作
• 验证：路径和文件扩展名验证

客户端SDK（TypeScript）

• 安全型API：完全支持TypeScript
• 错误处理：全面的错误管理
• 重试逻辑：自动重试失败的操作

关键组件

FileUploader 组件

• 处理拖放文件上传
• 支持多文件选择
• 在上传过程中提供视觉反馈

PromptBox组件

• 自然语言命令输入
• 实时命令解析
• 命令执行反馈

文件树组件

• 交互式文件资源管理器
• 文件操作按钮
• 目录导航

状态栏组件

• 连接状态监控
• 操作日志显示
• 错误报告

API终点

文件操作

// Create file
POST /api/files
{
  "path": "filename.txt",
  "content": "file content",
  "description": "optional description"
}

// Edit file
PUT /api/files
{
  "path": "filename.txt",
  "content": "new content",
  "description": "optional description"
}

// Delete file
DELETE /api/files
{
  "path": "filename.txt",
  "description": "optional description"
}

// Read file
GET /api/files?path=filename.txt

// List files
GET /api/files/list?path=.

🔒 安全功能

路径验证

• 防止路径遍历攻击(../)
• 将操作限制在工作区目录
• 验证文件扩展名

文件扩展名白名单

允许的文件扩展名：

• 文本文件： .txt, .md, .json, .log
• 代码文件： .js, .ts, .jsx, .tsx, .html, .css
• 数据文件： .csv, .xml, .yaml, .yml
• 脚本： .sh, .bat, .ps1
• 配置： .ini, .cfg, .conf

错误处理

• 全面的错误捕捉
• 用户友好的错误消息
• 调试详细日志记录

🧪 测试

手动测试

1. 文件上传：测试拖放和文件选择器
2. 自然语言：测试各种命令模式
3. 文件操作：测试创建、读取、编辑、删除
4. 导航：测试目录导航
5. 错误处理：测试无效的命令和操作

API测试

# Test health endpoint
curl http://localhost:3001/health

# Test file creation
curl -X POST http://localhost:3001/api/files \
  -H "Content-Type: application/json" \
  -d '{"path":"test.txt","content":"Hello World"}'

# Test file listing
curl http://localhost:3001/api/files/list

🐛 故障排除

常见问题

前端未加载

• 检查前端服务器是否在端口5173上运行
• 验证是否已安装所有依赖项
• 检查浏览器控制台是否有错误

后端连接失败

• 确保后端服务器在端口3001上运行
• 检查工作区目录是否存在
• 验证服务器日志是否有错误

文件操作不起作用

• 检查工作区目录中的文件权限
• 验证是否允许文件扩展名
• 检查服务器日志是否存在验证错误

自然语言命令不起作用

• 检查浏览器控制台是否存在解析错误
• 验证命令语法是否与支持的模式匹配
• 检查API调用失败的网络选项卡

调试模式

通过检查浏览器控制台以获取以下详细信息来启用调试日志记录：

• 指令分析
• API调用
• 文件 操作
• 错误详细信息

📝 配置

环境变量

创建一个 .env 服务器目录中的文件：

# Server Configuration
PORT=3001
WORKSPACE_PATH=../workspace

# Security
ALLOWED_EXTENSIONS=txt,md,json,js,ts,html,css
MAX_FILE_SIZE=10485760

定制

添加文件扩展名

编辑 server/src/server.ts:

private allowedExtensions: Set = new Set([
  'txt', 'md', 'json', 'js', 'ts', 'jsx', 'tsx',
  // Add your extensions here
]);

更改端口

编辑相应 package.json 文件或使用环境变量。

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

• 底层协议的模型上下文协议（MCP）
• 前端框架的React团队
• 后端运行时的Node.js社区
• TypeScript团队致力于类型安全

📞 支持

对于问题和疑问：

1. 检查故障排除部分
2. 查看日志和控制台输出
3. 在存储库中创建问题
4. 联系开发团队

______________________________________________________________________

快乐的文件管理！ 🎉