RustFS File Management MCP Server

# FS MCP项目结构说明 ## 📁 项目结构 ``` fs-mcp/ ├── .env # 环境变量配置 ├── .gitignore # Git忽略文件 ├── README.md # 项目说明 ├── pyproject.toml # 项目配置和依赖管理 ├── pytest.ini # pytest配置 ├── README_STRUCTURE.md # 项目结构说明 ├── src/ # 源代码目录 │ └── fs_mcp/ # 主包 │ ├── __init__.py # 包初始化 │ ├── __main__.py # 主程序入口 │ ├── server.py # MCP服务器主程序 │ ├── config.py # 配置管理 │ ├── rustfs_client.py # RustFS S3客户端 │ ├── upload_tool.py # 文件上传工具 │ ├── download_tool.py # 文件下载工具 │ ├── utils.py # 工具函数 │ └── exceptions.py # 异常定义 ├── tests/ # 测试包 │ ├── __init__.py │ ├── conftest.py # pytest配置和夹具 │ ├── test_config.py # 配置测试 │ ├── integration/ # 集成测试 │ │ ├── __init__.py │ │ └── test_basic_functionality.py │ └── [其他测试文件] # 旧的测试文件（待修复） ├── docs/ # 文档目录 │ ├── examples/ # 示例代码 │ ├── task.md # 需求文档 │ └── 启动说明.md # 中文启动说明 ├── scripts/ # 脚本目录 ├── requirements/ # 依赖文件目录 │ ├── base.txt # 基础依赖 │ ├── dev.txt # 开发依赖 │ └── test.txt # 测试依赖 └── .venv/ # 虚拟环境（已忽略） ``` ## 🎯 主要变更 ### 1. 包结构变更 - **旧结构**: `src/` 下直接放置 `.py` 文件 - **新结构**: `src/fs_mcp/` 作为标准Python包 - **包名**: 从直接模块改为 `fs_mcp` 包 ### 2. 导入方式变更 ```python # 旧方式 from rustfs_client import RustFSClient from config import config # 新方式 from fs_mcp.rustfs_client import RustFSClient from fs_mcp.config import config ``` ### 3. 测试结构标准化 - **测试目录**: 从根目录移至 `tests/` 包 - **测试夹具**: 在 `conftest.py` 中定义通用夹具 - **测试分类**: 单元测试和集成测试分离 - **pytest配置**: 支持标记和分组测试 ### 4. 依赖管理 - **base.txt**: 基础运行依赖 - **dev.txt**: 开发工具依赖 - **test.txt**: 测试相关依赖 - **pyproject.toml**: 现代Python项目配置 ## 🚀 运行方式 ### 启动MCP服务器 ```bash # 方式1: 使用模块启动 python -m src.fs_mcp # 方式2: 直接运行包 python -m fs_mcp # 方式3: 开发模式运行 python -m src.fs_mcp.server ``` ### 运行测试 ```bash # 运行所有测试 python -m pytest # 运行特定测试文件 python -m pytest tests/test_config.py # 运行集成测试 python -m pytest tests/integration/ -m integration # 跳过慢速测试 python -m pytest -m "not slow" ``` ### 代码质量检查 ```bash # 代码格式化 uv run black src/ tests/ # 代码检查 uv run ruff check src/ tests/ # 类型检查 uv run mypy src/ ``` ## 📋 测试状态 ### ✅ 已验证 - ✅ 主程序启动: `python -m src.fs_mcp` - ✅ 配置测试: `tests/test_config.py` - ✅ URL解析测试: `tests/integration/test_basic_functionality.py` - ✅ pytest配置和夹具 ### 🔧 需要修复 - 🔧 旧测试文件的导入路径需要更新 - 🔧 部分测试类构造函数问题 - 🔧 测试文件路径依赖问题 ### 📝 测试文件状态 - `test_config.py` - ✅ 已更新，正常工作 - `test_basic_functionality.py` - ✅ 新建，正常工作 - `test_boto3_upload.py` - 🔧 导入路径需要修复 - `test_default_bucket.py` - 🔧 导入路径需要修复 - `test_download.py` - 🔧 导入路径需要修复 - `test_final_download.py` - 🔧 导入路径需要修复 - `test_upload.py` - 🔧 测试类构造函数问题 - `test_upload_tool.py` - 🔧 导入路径需要修复 - `test_upload_tool_final.py` - 🔧 导入路径需要修复 ## 🎯 下一步工作 1. **修复测试文件**: 更新剩余测试文件的导入路径 2. **标准化测试**: 将所有测试转换为pytest标准格式 3. **添加CI配置**: 配置GitHub Actions进行持续集成 4. **文档完善**: 添加API文档和使用示例 5. **类型注解**: 为主要函数添加类型注解 ## 📦 安装和部署 ### 开发环境安装 ```bash # 克隆项目 git clone <repository-url> cd fs-mcp # 安装依赖 uv sync # 安装开发依赖 uv sync --group dev ``` ### 生产部署 ```bash # 构建包 uv build # 安装到系统 pip install dist/fs_mcp-*.whl ``` ## 🔧 配置说明 环境变量配置（`.env`文件）： ```env FS_URL=http://your-rustfs-server:port FS_AK=your-access-key FS_SK=your-secret-key FS_DEFAULT_BUCKET=agentfiles TIMEOUT=30 ```