arthub-mcp-server 0.2.0
MCP Server for ArthHub storage system with full file and directory management
License: MIT
Requires Python: >=3.10

# ArthHub MCP Server

一个用于ArthHub存储系统的MCP (Model Context Protocol) Server，提供文件上传等功能。

## 功能特性

- 🚀 支持上传文件和目录到ArthHub资产库
- 📥 支持从ArthHub下载文件和目录
- 📁 支持创建、删除和查询目录/文件
- 🔍 支持查询目录下的子节点（递归/非递归）
- 🔐 支持多种认证方式（邮箱密码、公共Token）
- 📊 实时上传/下载进度追踪
- 🏷️ 支持为上传文件添加标签和描述
- 🔄 支持批处理工作流（探索-下载-处理-上传）

## 安装

### 从源码安装

#### Windows
```powershell
git clone <repository-url>
cd arthub_mcp_server
python -m pip install -e .
```

#### Linux / macOS
```bash
git clone <repository-url>
cd arthub_mcp_server
pip install -e .
```

### 使用pip安装

```bash
# Windows
python -m pip install arthub_mcp_server

# Linux / macOS
pip install arthub_mcp_server
```

## 配置

### 环境变量

配置认证信息，选择以下方式之一：

#### 方式一：使用邮箱和密码

```bash
export ARTHUB_EMAIL="your-email@example.com"
export ARTHUB_PASSWORD="your-password"
export ARTHUB_PUBLIC_KEY="your-public-key"
```

#### 方式二：使用公共Token

```bash
export ARTHUB_PUBLIC_TOKEN="your-public-token"
```

#### 可选配置

```bash
# API配置名称，默认为 api_config_qq（外网访问）
export ARTHUB_API_CONFIG="api_config_qq"
```

### Cursor配置

在Cursor的MCP设置中添加以下配置（通常在 `~/.cursor/config.json` 或项目的 `.cursor/mcp.json`）：

```json
{
  "mcpServers": {
    "arthub": {
      "command": "python",
      "args": ["-m", "arthub_mcp_server"],
      "env": {
        "ARTHUB_EMAIL": "your-email@example.com",
        "ARTHUB_PASSWORD": "your-password",
        "ARTHUB_PUBLIC_KEY": "your-public-key"
      }
    }
  }
}
```

或使用公共Token：

```json
{
  "mcpServers": {
    "arthub": {
      "command": "python",
      "args": ["-m", "arthub_mcp_server"],
      "env": {
        "ARTHUB_PUBLIC_TOKEN": "your-public-token"
      }
    }
  }
}
```

## 使用方法

### 1. 上传文件或目录

使用 `upload_file` 工具上传文件或整个目录到ArthHub：

```python
# 上传单个文件
upload_file(
    asset_hub="trial",
    remote_dir_path="test/upload",
    local_file_path="/path/to/your/file.jpg",
    tags=["test", "demo"],
    description="测试上传文件",
    same_name_override=False,
    need_convert=True
)

# 上传整个目录
upload_file(
    asset_hub="trial",
    remote_dir_path="test/upload",
    local_file_path="/path/to/your/directory",
    tags=["batch", "images"],
    description="批量上传图片",
    same_name_override=False,
    need_convert=True
)
```

### 2. 下载文件或目录

使用 `download_file` 工具从ArthHub下载文件或目录：

```python
# 下载文件或目录
download_file(
    asset_hub="trial",
    remote_node_path="test/upload/file.jpg",
    local_dir_path="/path/to/save",
    same_name_override=True,
    download_multi_version=False
)
```

### 3. 创建目录

使用 `create_directory` 工具创建目录：

```python
create_directory(
    asset_hub="trial",
    remote_dir_path="project/new_folder"
)
```

### 4. 删除文件或目录

使用 `delete_node` 工具删除文件或目录：

```python
delete_node(
    asset_hub="trial",
    remote_node_path="test/upload/old_file.jpg"
)
```

### 5. 查询节点信息

使用 `get_node_info` 工具查询文件或目录信息：

```python
get_node_info(
    asset_hub="trial",
    remote_node_path="test/upload"
)
```

### 6. 查询目录下的子节点

使用 `get_child_nodes` 工具查询某个目录下的所有子节点（文件和子目录）：

```python
# 查询直接子节点（非递归）
get_child_nodes(
    asset_hub="trial",
    remote_node_path="project/images",
    is_recursive=False
)

# 递归查询所有后代节点（完整目录树）
get_child_nodes(
    asset_hub="trial",
    remote_node_path="project",
    is_recursive=True
)
```

### 批处理工作流示例

在Cursor中，你可以让AI完成完整的批处理流程：

```
请帮我：
1. 递归查询arthub的trial库中 project/images 目录的完整目录结构
2. 从中找出所有jpg格式的图片
3. 下载这些图片到本地 D:/temp/images
4. 将所有图片裁剪为 800x600 尺寸
5. 把处理后的图片上传回 arthub的trial库的 images/processed 目录
```

或者简单的目录探索：

```
请帮我查看arthub的trial库中 project 目录下有哪些文件夹和文件
```

AI会自动调用相应的工具完成整个流程！

### 返回结果示例

成功上传后，会返回包含以下信息的字典：

```json
{
  "status": "success",
  "message": "File uploaded successfully: file.jpg",
  "name": "file.jpg",
  "type": "file",
  "size": 1024000,
  "node_id": 12345,
  "parent_id": 67890,
  "origin_url": "https://arthub.example.com/...",
  "asset_hub": "trial",
  "remote_path": "test/upload"
}
```

## 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black arthub_mcp_server/
ruff check arthub_mcp_server/
```

### 类型检查

```bash
mypy arthub_mcp_server/
```

## 项目结构

```
arthub_mcp_server/
├── arthub_mcp_server/
│   ├── __init__.py         # 包初始化
│   ├── __main__.py         # 入口点
│   ├── __version__.py      # 版本信息
│   ├── app.py              # FastMCP应用配置
│   ├── config.py           # 配置管理和认证
│   ├── errors.py           # 错误定义
│   ├── log_config.py       # 日志配置
│   ├── server.py           # MCP服务器主程序
│   ├── upload.py           # 上传功能实现
│   ├── download.py         # 下载功能实现
│   └── directory.py        # 目录和节点管理功能
├── pyproject.toml          # 项目配置
├── requirements.txt        # 依赖列表
└── README.md              # 项目文档
```

## 依赖

- `arthub_api` >= 1.10.8 - ArthHub Python SDK
- `fastmcp` >= 0.2.0 - FastMCP框架
- `loguru` >= 0.7.0 - 日志库
- `pydantic` >= 2.0.0 - 数据验证

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

如需获取ArthHub公钥或其他技术支持，请联系平台管理员。