文件系统 MCP 项目文档

项目概述

filesys 是一个基于 Python 和 mcp 库构建的轻量级 MCP 服务器，安全地从预配置目录中暴露文件内容和元数据。该项目利用 FastMCP 提供以下功能：

• 列出指定目录中的所有文件。
• 阅读特定文件的内容和元数据。

新增功能： 现在集成了 Anthropic 的 Claude AI，允许用户通过自然语言对话与文件系统交互，使用 Claude Tools 安全地访问定义的 MCP 资源。

项目确保安全的文件访问，通过验证路径并防止目录遍历攻击来实现。

功能预览

• 与 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. 克隆仓库：

   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} 替换为实际文件名）。

测试

• MCP 客户端函数： 运行以下命令以测试与服务器交互的函数：

  python claude_tool_client.py
  

  确保 MCP 服务器 (run.py) 已经在运行。
• 核心资源（如果有）： 如果有单元测试文件（例如 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 服务器在另一个进程中运行。
• 该项目实现了基本的安全措施，以限制对配置目录的访问并防止目录遍历攻击。
• 如果添加新功能或进行更改，请更新此文档。