金大哥 - Filesys MCP 详情

article

README

🚀 文件系统 MCP 项目文档

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

✨ 主要特性

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

📦 安装指南

克隆仓库：
```
git clone [仓库地址]
```

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

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

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

💻 使用示例

基础用法

启动 MCP 服务器：
```
python run.py
```
与 Claude 对话：
```
python interact_with_claude.py
```
直接发送 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
```

📚 详细文档

贡献指南

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

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

其他说明

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

⚠️ 重要提示

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

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

Filesys