ArthHub MCP Server

一个用于ArthHub存储系统的MCP (Model Context Protocol) Server，提供文件上传等功能。

功能特性

• 🚀 支持上传文件和目录到ArthHub资产库
• 📥 支持从ArthHub下载文件和目录
• 📁 支持创建、删除和查询目录/文件
• 🔍 支持查询目录下的子节点（递归/非递归）
• 🔐 支持多种认证方式（邮箱密码、公共Token）
• 📊 实时上传/下载进度追踪
• 🏷️ 支持为上传文件添加标签和描述
• 🔄 支持批处理工作流（探索-下载-处理-上传）

安装

从源码安装

Windows

git clone <repository-url>
cd arthub_mcp_server
python -m pip install -e .

Linux / macOS

git clone <repository-url>
cd arthub_mcp_server
pip install -e .

使用pip安装

# Windows
python -m pip install arthub_mcp_server

# Linux / macOS
pip install arthub_mcp_server

配置

环境变量

配置认证信息，选择以下方式之一：

方式一：使用邮箱和密码

export ARTHUB_EMAIL="your-email@example.com"
export ARTHUB_PASSWORD="your-password"
export ARTHUB_PUBLIC_KEY="your-public-key"

方式二：使用公共Token

export ARTHUB_PUBLIC_TOKEN="your-public-token"

可选配置

# API配置名称，默认为 api_config_qq（外网访问）
export ARTHUB_API_CONFIG="api_config_qq"

Cursor配置

在Cursor的MCP设置中添加以下配置（通常在 ~/.cursor/config.json 或项目的 .cursor/mcp.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：

{
  "mcpServers": {
    "arthub": {
      "command": "python",
      "args": ["-m", "arthub_mcp_server"],
      "env": {
        "ARTHUB_PUBLIC_TOKEN": "your-public-token"
      }
    }
  }
}

使用方法

1. 上传文件或目录

使用 upload_file 工具上传文件或整个目录到ArthHub：

# 上传单个文件
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下载文件或目录：

# 下载文件或目录
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 工具创建目录：

create_directory(
    asset_hub="trial",
    remote_dir_path="project/new_folder"
)

4. 删除文件或目录

使用 delete_node 工具删除文件或目录：

delete_node(
    asset_hub="trial",
    remote_node_path="test/upload/old_file.jpg"
)

5. 查询节点信息

使用 get_node_info 工具查询文件或目录信息：

get_node_info(
    asset_hub="trial",
    remote_node_path="test/upload"
)

6. 查询目录下的子节点

使用 get_child_nodes 工具查询某个目录下的所有子节点（文件和子目录）：

# 查询直接子节点（非递归）
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会自动调用相应的工具完成整个流程！

返回结果示例

成功上传后，会返回包含以下信息的字典：

{
  "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"
}

开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest

代码格式化

black arthub_mcp_server/
ruff check arthub_mcp_server/

类型检查

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公钥或其他技术支持，请联系平台管理员。