# FS MCP Server 启动说明
## 快速启动
### 1. 安装依赖
```bash
# 使用uv安装依赖
uv sync
```
### 2. 配置环境变量
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑.env文件，填入你的RustFS配置
# FS_URL=https://your-rustfs-endpoint.com
# FS_AK=your-access-key
# FS_SK=your-secret-key
# TIMEOUT=30
```
### 3. 启动服务
#### 方式一：直接运行（推荐）
```bash
# 启动MCP服务器（stdio传输）
uv run python -m src
```
#### 方式二：HTTP模式
```bash
# 启动HTTP服务器（默认端口8000）
uv run python -m src --transport http --port 8000
```
#### 方式三：指定配置文件
```bash
# 使用自定义配置文件
uv run python -m src --config config.json
```
### 4. 验证服务
启动成功后，你会看到类似输出：
```
🖥️ Server name: fs-mcp
📦 Transport: STDIO
🏎️ FastMCP version: 2.12.5
🤝 MCP SDK version: 1.16.0
[10/20/25 18:52:36] INFO Starting MCP server 'fs-mcp' with transport 'stdio'
```
## 可用工具
### 1. upload_file_tool
- **功能**: 上传本地文件到RustFS存储服务
- **参数**: `file_path` (string) - 本地文件的绝对路径
- **返回**: 包含上传结果的字典
### 2. download_file_tool
- **功能**: 从指定URL下载文件到本地
- **参数**:
- `url` (string) - 要下载的文件URL
- `download_path` (string) - 本地保存路径
- **返回**: 包含下载结果的字典
## 使用示例
### 在Claude Desktop中使用
1. 在Claude Desktop的MCP配置中添加：
```json
{
"mcpServers": {
"fs-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "src"],
"cwd": "/path/to/fs_mcp"
}
}
}
```
2. 重启Claude Desktop，即可使用文件上传和下载功能
### 在代码中使用
```python
from fastmcp import Client
# 连接到HTTP模式的服务器
client = Client("http://localhost:8000/mcp")
async with client:
# 上传文件
upload_result = await client.call_tool("upload_file_tool", {
"file_path": "/path/to/local/file.txt"
})
# 下载文件
download_result = await client.call_tool("download_file_tool", {
"url": "https://example.com/file.pdf",
"download_path": "/downloads/"
})
```
## 常见问题
### Q: 启动时提示配置验证失败
A: 检查`.env`文件中的环境变量是否正确设置，特别是`FS_URL`、`FS_AK`、`FS_SK`这三个必需变量。
### Q: 文件上传失败
A: 确认：
1. 文件路径存在且可读
2. RustFS服务正常运行
3. 网络连接正常
4. 访问密钥正确
### Q: 文件下载失败
A: 检查：
1. URL格式正确且可访问
2. 下载路径存在且有写入权限
3. 网络连接正常
## 开发和调试
### 查看详细日志
```bash
# 启用详细日志
export LOG_LEVEL=DEBUG
uv run python -m src
```
### 运行测试
```bash
# 运行单元测试
uv run pytest
# 运行测试并显示覆盖率
uv run pytest --cov=src
```
### 代码格式化
```bash
# 格式化代码
uv run black src/
# 检查代码质量
uv run ruff check src/
```
## 高级配置
### 环境变量
- `FS_URL`: RustFS服务端点（必需）
- `FS_AK`: RustFS访问密钥（必需）
- `FS_SK`: RustFS密钥（必需）
- `TIMEOUT`: 请求超时时间，默认30秒（可选）
- `LOG_LEVEL`: 日志级别，默认INFO（可选）
### 支持的传输方式
- **STDIO**: 默认，适用于本地开发
- **HTTP**: 适用于远程访问
- **WebSocket**: 实时通信
### 自定义端口
```bash
# HTTP模式使用自定义端口
uv run python -m src --transport http --port 3000
```
