README.md•4.73 kB
# FS MCP Server
基于FastMCP构建的文件上传/下载MCP服务，集成RustFS SDK实现AI自动调用文件存储和下载功能。
## 功能特性
- **文件上传**: 支持上传本地文件到RustFS存储服务
- **文件下载**: 支持从任意HTTP/HTTPS URL下载文件到本地
- **异步处理**: 基于asyncio的异步文件操作
- **错误处理**: 完善的错误处理和异常管理
- **配置验证**: 启动时验证必需的环境变量配置
## 安装
### 1. 克隆项目
```bash
git clone <repository-url>
cd fs_mcp
```
### 2. 安装依赖
```bash
pip install -e .
```
或安装开发依赖：
```bash
pip install -e ".[dev]"
```
### 3. 配置环境变量
复制环境变量模板并配置：
```bash
cp .env.example .env
```
编辑 `.env` 文件：
```env
# RustFS配置
FS_URL=https://your-rustfs-endpoint.com
FS_AK=your-access-key
FS_SK=your-secret-key
# 可选配置
TIMEOUT=30
```
## 使用方法
### 启动服务
```bash
# 直接运行
python -m src.server
# 或使用模块方式
python -m src
```
### MCP工具
#### 1. upload_file
上传本地文件到RustFS存储服务。
**参数:**
- `file_path` (string): 本地文件的绝对路径
**返回值:**
```json
{
"success": true,
"filename": "example.txt",
"size": 1024,
"content_type": "text/plain",
"access_url": "https://fs.example.com/files/example.txt",
"file_id": "example.txt",
"message": "文件 'example.txt' 上传成功"
}
```
#### 2. download_file
从指定URL下载文件到本地路径。
**参数:**
- `url` (string): 要下载的文件URL
- `download_path` (string): 本地保存路径
**返回值:**
```json
{
"success": true,
"url": "https://example.com/file.pdf",
"file_path": "/path/to/save/file.pdf",
"filename": "file.pdf",
"size": 2048000,
"content_type": "application/pdf",
"message": "文件 'file.pdf' 下载成功"
}
```
## 使用示例
### 文件上传示例
```python
# 通过MCP客户端调用上传工具
result = await mcp_client.call_tool("upload_file", {
"file_path": "/home/user/documents/report.pdf"
})
```
### 文件下载示例
```python
# 下载文件到指定目录
result = await mcp_client.call_tool("download_file", {
"url": "https://example.com/data.csv",
"download_path": "/home/user/downloads/"
})
# 下载文件到指定路径
result = await mcp_client.call_tool("download_file", {
"url": "https://example.com/image.png",
"download_path": "/home/user/downloads/saved_image.png"
})
```
## 错误处理
服务提供详细的错误信息：
### 常见错误类型
- `FileNotFoundError`: 文件不存在
- `ValueError`: 参数无效或URL格式错误
- `RuntimeError`: 上传/下载操作失败
- `ConfigurationError`: 环境变量配置错误
### 错误示例
```python
# 文件不存在
try:
await mcp_client.call_tool("upload_file", {
"file_path": "/nonexistent/file.txt"
})
except FileNotFoundError as e:
print(f"错误: {e}")
# URL无效
try:
await mcp_client.call_tool("download_file", {
"url": "invalid-url",
"download_path": "/tmp/"
})
except ValueError as e:
print(f"错误: {e}")
```
## 开发
### 项目结构
```
fs_mcp/
├── src/
│ ├── __init__.py # 包初始化
│ ├── __main__.py # 命令行入口
│ ├── server.py # MCP服务器主程序
│ ├── config.py # 配置管理
│ ├── rustfs_client.py # RustFS客户端
│ ├── upload_tool.py # 上传工具
│ ├── download_tool.py # 下载工具
│ ├── exceptions.py # 自定义异常
│ └── utils.py # 工具函数
├── pyproject.toml # 项目配置
├── .env.example # 环境变量模板
└── README.md # 项目文档
```
### 运行测试
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest
```
### 代码格式化
```bash
# 使用black格式化代码
black src/
# 使用ruff检查代码质量
ruff check src/
```
## 配置说明
### 必需环境变量
- `FS_URL`: RustFS服务端点URL
- `FS_AK`: RustFS访问密钥
- `FS_SK`: RustFS密钥
### 可选环境变量
- `TIMEOUT`: 请求超时时间（秒），默认30
### RustFS API要求
本服务假设RustFS提供以下API端点：
- `POST /api/upload`: 文件上传
- `GET /api/files/{file_id}`: 获取文件信息
上传请求格式：
- Method: POST
- Content-Type: multipart/form-data
- Headers: Authorization: Bearer {access_key}:{secret_key}
- Files: file (文件内容)
- Data: filename (文件名), size (文件大小)
## 许可证
MIT License
## 贡献
欢迎提交Issue和Pull Request来改进这个项目。