File system MCP

这是一个文件系统 MCP 服务器，它允许 LLM 从您本地机器上指定的安全目录中读取和列出文件。

iBz-04

文件系统

README

filesys 是一个轻量级的 MCP 服务器，使用 Python 和 mcp 库构建，可以安全地暴露预配置目录中的文件内容和元数据。该项目利用 FastMCP 提供了一组端点，允许：

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

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

核心功能分为几个组件：

资源: 在 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 Tool 客户端: 在 claude_tool_client.py 中，定义了函数 (list_files_in_safe_folder, read_file_from_safe_folder) 来与运行中的 Filesys MCP 服务器交互。这些函数充当桥梁，将简单的函数调用转换为 MCP 请求并解析响应。它们被设计成可以被 Claude Tools 轻松使用。
Claude 交互脚本: interact_with_claude.py 脚本设置一个 Anthropic 客户端，基于 claude_tool_client.py 中的函数定义 Claude Tools，并运行一个命令行对话循环。用户可以向 Claude 提问，例如“有哪些文件可用？”或“读取 test.txt”，Claude 将使用提供的工具（安全地调用 MCP 服务器）来满足请求。
测试: tests/test_resources.py 中的单元测试确保文件列表和读取功能按预期工作。

克隆仓库:

git clone https://github.com/iBz-04/Filesys.git

创建虚拟环境 (可选但推荐):

python -m venv venv
source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate

安装依赖: 确保您已安装 Python。然后安装所需的库：
```
pip install -r requirements.txt
```
配置 API 密钥:
- 在项目的根目录中创建一个名为 .env.local 的文件。
- 将您的 Anthropic API 密钥添加到此文件：
```
ANTHROPIC_API_KEY=your_api_key_here
```
- 注意: .gitignore 文件已配置为防止此文件被提交到 Git。

文件服务器从 config/config.json 读取其配置。默认情况下，服务器在以下指定的目录上运行：

{
  "directory": "./safe_folder"
}

您可以修改此文件以指向其他目录（如果需要）。

Anthropic API 密钥: Claude 交互脚本从 .env.local 文件读取 ANTHROPIC_API_KEY（参见安装步骤 5）。

启动 MCP 服务器: 首先，确保 Filesys MCP 服务器在终端中运行：
```
python run.py
```
此命令初始化 FastMCP 服务器，并使 files://list 和 files://read/{filename} 端点可用。
与 Claude 交互: 在单独的终端中（当步骤 1 中的服务器仍在运行时），运行 Claude 交互脚本：
```
python interact_with_claude.py
```
然后，您可以要求 Claude 与配置的 safe_folder 中的文件进行交互。例子：
- "你能看到哪些文件？"
- "列出可用的文件。"
- "你能为我读取 test.txt 吗？"
- "告诉我名为 test.txt 的文件的内容"
直接 MCP 请求 (可选): 您还可以使用任何 MCP 兼容的客户端直接与服务器交互：
- 列出文件: 请求 files://list。
- 读取文件: 请求 files://read/{filename}（将 {filename} 替换为实际文件名）。

MCP 客户端函数: 您可以通过运行以下命令来测试与 MCP 服务器通信的函数：
```
python claude_tool_client.py
```
这将执行脚本末尾定义的 test_tool_functions。确保 MCP 服务器 (python run.py) 预先运行。
核心资源 (如果存在测试): 如果在 tests/ 目录中创建了单元测试（例如，tests/test_resources.py），则可以使用以下命令运行它们：
```
python -m unittest discover tests
```

欢迎贡献！要贡献：

根据需要自定义配置 (config/config.json, .env.local)。
重要: Claude 交互脚本 (interact_with_claude.py) 需要 Filesys MCP 服务器 (run.py) 在单独的进程中运行。
该项目实现了基本的安全措施，以将文件访问限制为配置的目录并防止目录遍历。
随着新功能的添加或更改，更新此文档。