MCP Filesystem Assistant

🗂️ MCP文件系统助手

一个漂亮的AI驱动的文件管理器 模型上下文协议（MCP），具有现代web界面、OpenAI集成和安全的文件系统操作。

______________________________________________________________________

🎯 这是什么？

一个可以通过自然语言读取、写入和管理文件的AI助手。基于模型上下文协议（MCP），它演示了如何：

• 🤖 将人工智能模型与真实工具连接起来
• 🔒 在沙盒环境中安全管理文件
• 🎨 使用Streamlit构建美观的界面
• 🛠️ 创建生产就绪的MCP服务器

非常适合学习MCP或构建自己的AI工具！

______________________________________________________________________

✨ 特性

💬 自然语言接口

让AI用简单的英语管理文件：

• “列出工作区中的所有文件”
• “阅读notes.txt并对其进行总结”
• “创建备份文件夹并组织我的文件”
• “显示data.json的详细信息”

🎨 漂亮的Web界面

• 聊天选项卡 -与AI助手交谈
• 文件浏览器 -可视化工作空间资源管理器
• 快捷操作 -无需人工智能的直接文件操作

🛠️ 8强大的工具

🔒 安全第一

• 所有操作都已沙盒化 workspace/ 文件夹
• 路径遍历保护
• 对每个操作进行输入验证

______________________________________________________________________

📁 项目结构

filesystem-mcp-project/
├── host/                      # Streamlit web app
│   ├── app.py                 # Main interface
│   ├── mcp_connector.py       # Connects to MCP server
│   └── ui_components.py       # UI styling
│
├── server/                    # MCP server
│   ├── filesystem_mcp_server.py  # 8 filesystem tools
│   └── config.py              # Settings
│
├── workspace/                 # Your files live here
│   ├── notes.txt             
│   └── data.json             
│
├── requirements.txt           # Python packages
├── .env.example              # Config template
└── README.md                 # You are here!

______________________________________________________________________

🚀 快速开始

1.安装

# Clone or download the project
cd filesystem-mcp-project

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # Mac/Linux
# OR
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

2.配置

创建一个 .env 文件：

OPENAI_API_KEY=sk-your-key-here

从以下位置获取您的OpenAI API密钥：https://platform.openai.com/api-keys

3.跑步

终端1-启动MCP服务器：

python server/filesystem_mcp_server.py

您应该看到：

🚀 MCP Server starting...
📁 Workspace directory: /path/to/workspace
🌐 Server running on http://127.0.0.1:8000
✅ Available tools: 8

终端2-启动Web界面：

streamlit run host/app.py

浏览器在以下位置打开 http://localhost:8501 🎉

______________________________________________________________________

💡 使用示例

示例1：列出文件

你： “工作区中有哪些文件？”

人工智能： *用途 list_directory 工具*

📁 Directory: .

  📄 notes.txt (1.2 KB)
  📄 data.json (856 bytes)

示例2：创建文件

你： “用‘hello World！’创建一个名为hello.txt的文件”

人工智能： *用途 write_file 工具*

✅ File written successfully: hello.txt (12 characters)

示例3：组织文件

你： “创建备份文件夹并将旧文件移动到其中”

人工智能： *用途 create_directory 和 move_file 工具*

✅ Directory created: backup
✅ File moved: old_data.txt → backup/old_data.txt

______________________________________________________________________

🏗️ 运作原理

┌─────────────────┐
│   You (User)    │
│  Ask questions  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Streamlit App  │
│  localhost:8501 │  ← Beautiful web interface
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   OpenAI API    │
│     GPT-4       │  ← AI decides which tools to use
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   MCP Server    │
│  localhost:8000 │  ← Executes file operations
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   workspace/    │
│   Your Files    │  ← Safe sandbox folder
└─────────────────┘

______________________________________________________________________

🔧 配置

基本设置(.env)

# Required
OPENAI_API_KEY=sk-your-key-here

# Optional (defaults shown)
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000

高级设置(server/config.py)

# Change workspace location
WORKSPACE_DIR = Path("my_custom_folder")

# Change server port
MCP_SERVER_PORT = 9000

______________________________________________________________________

🐛 故障排除

“服务器未连接”

1. 检查MCP服务器是否正在运行（终端1）
2. 点击侧边栏中的“检查连接”按钮
3. 重新启动服务器和Streamlit

“OpenAI API密钥错误”

1. 确保 .env 文件存在
2. 检查您的API密钥是否正确
3. 更新后重新启动Streamlit .env

“端口已在使用中”

# Kill process on port 8000
lsof -i :8000
kill -9 

# Or change port in .env
MCP_SERVER_PORT=8001

“找不到文件”

记住：所有路径都是相对于 workspace/

✅ Correct:   read_file("notes.txt")
❌ Wrong:     read_file("workspace/notes.txt")
❌ Wrong:     read_file("/absolute/path/file.txt")

______________________________________________________________________

🛠️ 发展

添加新工具

编辑 server/filesystem_mcp_server.py:

@mcp.tool()
def search_files(query: str) -> str:
    """
    Search for files containing text.
    
    Args:
        query: Text to search for
    
    Returns:
        List of matching files
    """
    # Your implementation here
    return "Found 3 files matching 'query'"

重新启动服务器-就是这样！该工具自动可用。

🤝 贡献

欢迎投稿！方法如下：

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing)
3. 进行更改
4. 测试一切正常
5. 提交拉取请求

______________________________________________________________________

🎓 车间准备就绪

本项目旨在学习和教学：

• ✅ 清晰、有注释的代码
• ✅ 逐步设置
• ✅ 现实世界的例子
• ✅ 生产模式
• ✅ 安全最佳实践

非常适合：

• 学习MCP架构
• 构建人工智能工具
• 现代Python教学
• 原型设计理念

______________________________________________________________________

快乐建筑！ 🎉