Filesys

🚀 文件系统 MCP 项目文档

本项目 filesys 是一个基于 Python 和 mcp 库构建的轻量级 MCP 服务器，能够安全地从预配置目录中暴露文件内容和元数据。它利用 FastMCP 实现文件列表展示和文件内容及元数据读取功能。同时，新增集成了 Anthropic 的 Claude AI，支持用户通过自然语言对话与文件系统交互，安全访问定义的 MCP 资源。

✨ 主要特性

• 可列出指定目录中的所有文件。
• 能读取特定文件的内容和元数据。
• 集成 Anthropic 的 Claude AI，支持通过自然语言对话与文件系统交互，使用 Claude Tools 安全访问 MCP 资源。
• 确保安全的文件访问，通过验证路径防止目录遍历攻击。

📦 安装指南

1. 克隆仓库：

   git clone [仓库地址]
   

2. 创建虚拟环境并安装依赖：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
   pip install mcp
   

3. 配置 API 密钥：
   • 修改 config/config.json 文件，设置服务器的配置（例如端口）。
   • 创建 .env.local 文件并添加 Anthropic 的 API 密钥。

💻 使用示例

基础用法

1. 启动 MCP 服务器：

   python run.py
   

2. 与 Claude 对话：

   python interact_with_claude.py
   

3. 直接发送 MCP 请求（可选）：
   • 列出文件：发送请求 files://list。
   • 读取文件：发送请求 files://read/{filename}（将 {filename} 替换为实际文件名）。

功能预览

• 与 Claude 对话以列出和读取 safe_folder 中的文件：

🔧 技术细节

核心功能分为以下几个部分：

• 资源：
  在 src/resources.py 中，两个函数负责文件操作：

  • list_files(): 扫描指定目录并返回所有文件的列表。
  • read_file(): 根据文件名读取文件内容并返回其内容。

• 服务器：
  在 run.py 中，定义了一个简单的 MCP 服务器，启动后监听端口并处理来自客户端的请求。服务器会调用资源模块中的函数来响应请求。

• Claude 工具客户端：
  在 claude_tool_client.py 中，定义了与 MCP 服务器交互的工具函数。这些函数可以用来测试服务器的功能，并为 Claude 提供接口以发送请求。

• 测试：
  如果在 tests/ 目录中有单元测试文件（例如 tests/test_resources.py），可以通过运行以下命令执行测试：

  python -m unittest discover tests
  

📚 详细文档

贡献指南

欢迎贡献！要参与项目，请按照以下步骤操作：

1. Fork 仓库。
2. 创建一个新的分支用于你的功能或修复。
3. 提交更改并添加详细的提交信息。
4. 推送分支并在 GitHub 上打开 Pull Request。

其他说明

• 根据需要自定义配置文件 (config/config.json 和 .env.local)。

⚠️ 重要提示

interact_with_claude.py 脚本要求 run.py 服务器在另一个进程中运行。

• 该项目实现了基本的安全措施，以限制对配置目录的访问并防止目录遍历攻击。
• 如果添加新功能或进行更改，请更新此文档。