# 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来改进这个项目。