内容
# 文件系统 MCP
## 概述
filesys 是一个轻量级的文件系统 MCP 服务器，使用 Python 和 MCP 库构建，可以安全地公开预配置目录中的文件内容和元数据。该项目利用 FastMCP 提供了一组端点，允许：
- 列出指定目录中的所有文件。
- 读取指定文件的内容和元数据。
**新增功能：** 现在它与Anthropic的Claude AI集成，允许用户通过自然语言对话与文件系统交互，使用 Claude Tools 安全地访问定义的 MCP 资源。
该项目通过验证路径和防止目录遍历攻击，确保安全的文件访问。
## 预览
- 使用 Claude 与 `safe_folder` 中的文件交互：
<img src="https://res.cloudinary.com/diekemzs9/image/upload/v1743439706/screenshot_vxq1ym.jpg" alt="My Image" width="2000"/>
## 工作原理
核心功能分为几个组件：
- **资源：**
在 `src/resources.py` 中，两个函数负责文件操作：
- `list_files()`：扫描基目录（在 `config/config.json` 中配置）以返回可见文件列表。
- `read_file(filename)`：读取指定文件的内容并返回文件内容和元数据（大小和最后修改时间戳），同时确保文件访问安全。
- **服务器：**
在 `src/server.py` 中，初始化了一个 FastMCP 服务器，并注册了两个资源端点：
- `files://list`：调用 `list_files()`。
- `files://read/{filename}`：调用 `read_file(filename)`。
服务器通过 `run.py` 启动，并使用 MCP 库处理资源请求。
- **Claude 工具客户端：**
在 `claude_tool_client.py` 中，定义了与正在运行的 Filesys MCP 服务器交互的函数（`list_files_in_safe_folder`、`read_file_from_safe_folder`）。这些函数作为桥梁，将简单函数调用转换为 MCP 请求并解析响应。它们设计为 Claude Tools 易于使用。
- **Claude 交互脚本：**
`interact_with_claude.py` 脚本设置了一个 Anthropic 客户端，根据 `claude_tool_client.py` 中的函数定义了 Claude Tools，并运行了一个命令行对话循环。用户可以向 Claude 询问诸如“有哪些文件可用？”或“读取 test.txt”之类的问题，Claude 将使用提供的工具（安全调用 MCP 服务器）来满足请求。
- **测试：**
`tests/test_resources.py` 中的单元测试确保文件列出和读取功能按预期工作。
## 安装
1. **克隆仓库：**
```bash
git clone https://github.com/iBz-04/Filesys.git
```
2. **导航到项目目录：**
```bash
cd Filesys
```
3. **创建虚拟环境（可选但推荐）：**
```bash
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
```
4. **安装依赖项：**
确保已安装 Python。然后安装所需的库：
```bash
pip install -r requirements.txt
```
5. **配置 API 密钥：**
- 在项目根目录中创建一个名为 `.env.local` 的文件。
- 将您的 Anthropic API 密钥添加到此文件中：
```env
ANTHROPIC_API_KEY=your_api_key_here
```
- **注意：** `.gitignore` 文件配置为防止此文件被提交到 Git。
## 配置
文件服务器从 `config/config.json` 读取其配置。默认情况下，服务器在以下目录上运行：
```json
{
"directory": "./safe_folder"
}
```
如果需要，可以修改此文件以指向其他目录。
- **Anthropic API 密钥：** Claude 交互脚本从 `.env.local` 文件（参见安装步骤 5）读取 `ANTHROPIC_API_KEY`。
## 使用
1. **启动 MCP 服务器：**
首先，确保 Filesys MCP 服务器在终端中运行：
```bash
python run.py
```
此命令初始化 FastMCP 服务器，并使 `files://list` 和 `files://read/{filename}` 端点可用。
2. **与 Claude 交互：**
在**单独的终端**（当步骤 1 中的服务器仍在运行时），运行 Claude 交互脚本：
```bash
python interact_with_claude.py
```
然后，您可以要求 Claude 与配置的 `safe_folder` 中的文件交互。示例：
- “您可以看到哪些文件？”
- “列出可用的文件。”
- “您可以为我读取 test.txt 吗？”
- “请告诉我名为 test.txt 的文件的内容”
3. **直接 MCP 请求（可选）：**
您还可以使用任何 MCP 兼容的客户端直接与服务器交互：
- **列出文件：** 请求 `files://list`。
- **读取文件：** 请求 `files://read/{filename}`（将 `{filename}` 替换为实际文件名）。
## 测试
- **MCP 客户端函数：** 您可以通过运行以下命令测试与 MCP 服务器通信的函数：
```bash
python claude_tool_client.py
```
这将执行脚本末尾定义的 `test_tool_functions`。确保在此之前运行 MCP 服务器（`python run.py`）。
- **核心资源（如果存在测试）：** 如果在 `tests/` 目录中创建了单元测试（例如 `tests/test_resources.py`），则可以使用以下命令运行它们：
```bash
python -m unittest discover tests
```
## 贡献
欢迎贡献！要贡献：
1. 复刻仓库。
2. 为您的功能或错误修复创建新的分支。
3. 用详细的提交消息提交您的更改。
4. 推送您的分支并打开拉取请求。
## 其他说明
- 根据需要自定义配置（`config/config.json`、`.env.local`）。
- **重要：** Claude 交互脚本（`interact_with_claude.py`）需要 Filesys MCP 服务器（`run.py`）在单独的进程中运行。
- 该项目实现了基本的安全措施，以限制对配置目录的文件访问并防止目录遍历。
- 在添加新功能或进行更改时，请更新此文档。
