AIGC 网络硬盘 MCP 服务器

AIGC Network Disk MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，为 AIGC 网络硬盘 API 提供标准化的工具接口，使 AI 模型能够通过统一的接口管理文件。

🚀 功能特性

📋 文件管理工具

• 📂 文件列表查询 - 支持搜索、分类过滤、分页和排序
• 📤 文件上传 - 支持本地文件上传和URL文件上传
• 📥 文件下载 - 支持大文件下载、断点续传和进度显示
• ℹ️ 文件信息查询 - 获取详细的文件元数据和统计信息
• 🗑️ 文件删除 - 安全的单文件删除，带确认机制
• 🗂️ 批量删除 - 高效的批量文件删除，支持最多50个文件

🔧 技术特性

• TypeScript 严格模式 - 完整的类型安全和代码质量保证
• 智能错误处理 - 详细的错误分类和用户友好的提示
• 操作日志记录 - 完整的操作审计和调试信息
• 进度反馈 - 实时的上传/下载进度显示
• 安全确认机制 - 防止误删除的多重确认
• 配置验证 - 启动时的配置检查和错误提示

📦 安装和配置

环境要求

• Node.js >= 18.0.0
• npm 或 yarn
• TypeScript >= 5.0.0

克隆项目

git clone https://github.com/aigchub/aigc-network-disk-mcp.git
cd aigc-network-disk-mcp

安装依赖

npm install

从npm安装

如果你想直接使用已发布的包：

# 全局安装
npm install -g @aigchub/aigc-network-disk-mcp

# 或者项目中安装
npm install @aigchub/aigc-network-disk-mcp

使用命令行启动：

# 使用全局安装的版本
aigc-network-disk-mcp --api-token YOUR_TOKEN --api-base-url YOUR_API_URL

# 或者使用npx
npx @aigchub/aigc-network-disk-mcp --api-token YOUR_TOKEN

环境配置

1. 复制环境配置文件：

cp .env.example .env

2. 编辑 .env 文件，配置你的 API 设置：

# AIGC Network Disk API 配置
API_BASE_URL=http://localhost:65203/api
API_TOKEN=your-api-token-here

# 默认设置
DEFAULT_EXPIRES_IN=300
DEFAULT_PAGE_SIZE=20
MAX_BATCH_SIZE=50

# 可选：超时设置（毫秒）
REQUEST_TIMEOUT=30000
UPLOAD_TIMEOUT=300000
DOWNLOAD_TIMEOUT=300000

构建项目

npm run build

启动服务

# 开发模式（实时编译）
npm run dev

# 生产模式
npm start

🛠️ 可用工具

1. 文件列表查询 (list_files)

获取文件列表，支持搜索、过滤、分页和排序。

参数：

• query (可选): 搜索关键词，支持中文
• category_id (可选): 分类ID (1=图片, 2=文档, 3=视频, 4=音频, 5=压缩包, 6=其他)
• file_type (可选): 文件类型过滤
• sort_by (可选): 排序字段 (upload_time, file_size, access_count, download_count)
• sort_order (可选): 排序方向 (asc, desc)
• page (可选): 页码，从1开始
• size (可选): 每页数量，最大100

示例：

{
  "query": "图片",
  "category_id": 1,
  "sort_by": "upload_time",
  "sort_order": "desc",
  "page": 1,
  "size": 20
}

2. 文件上传 (upload_file)

从本地文件系统上传文件到网络硬盘。

参数：

• file_path (必需): 本地文件的绝对路径
• description (可选): 文件描述
• category_id (可选): 文件分类ID
• tags (可选): 文件标签，逗号分隔
• expires_in (可选): 过期时间（秒），默认300，最大30天

示例：

{
  "file_path": "/path/to/your/file.jpg",
  "description": "示例图片",
  "category_id": 1,
  "tags": "示例,测试",
  "expires_in": 3600
}

3. URL文件上传 (upload_file_by_url)

从网络URL上传文件到网络硬盘。

参数：

• url (必需): 要上传的文件URL
• description (可选): 文件描述
• category_id (可选): 文件分类ID
• tags (可选): 文件标签，逗号分隔
• expires_in (可选): 过期时间（秒）

示例：

{
  "url": "https://example.com/image.jpg",
  "description": "网络图片",
  "category_id": 1,
  "tags": "网络,示例"
}

4. 文件信息查询 (get_file_info)

获取文件的详细信息和元数据。

参数：

• url (必需): 文件的访问URL

示例：

{
  "url": "http://localhost:65203/files/view/abc123"
}

5. 文件下载 (download_file)

从网络硬盘下载文件到本地文件系统。

参数：

• url (必需): 文件的访问URL
• save_path (必需): 本地保存路径（绝对路径）
• overwrite (可选): 是否覆盖已存在的文件，默认false

示例：

{
  "url": "http://localhost:65203/files/view/abc123",
  "save_path": "/path/to/save/file.jpg",
  "overwrite": true
}

6. 文件删除 (delete_file)

删除网络硬盘中的文件。

参数：

• url (必需): 要删除的文件URL
• confirm (可选): 确认删除，默认false（安全机制）

示例：

{
  "url": "http://localhost:65203/files/view/abc123",
  "confirm": true
}

7. 批量删除 (batch_delete_files)

批量删除多个文件，支持最多50个文件。

参数：

• urls (必需): 要删除的文件URL数组
• confirm (可选): 确认删除，默认false（安全机制）

示例：

{
  "urls": [
    "http://localhost:65203/files/view/abc123",
    "http://localhost:65203/files/view/def456"
  ],
  "confirm": true
}

🔧 开发和调试

开发模式

# 启动开发服务器（支持热重载）
npm run dev

# 监听模式编译
npm run watch

构建和清理

# 编译 TypeScript
npm run build

# 清理构建产物
npm run clean

# 完整重建
npm run clean && npm run build

调试配置

启动时服务器会显示详细的配置信息：

🚀 AIGC Network Disk MCP server started successfully
📡 API Base URL: http://localhost:65203/api
🔑 API Token: 已配置
🛠️  Available tools:
   📋 list_files - 获取文件列表
   📤 upload_file - 上传本地文件
   🌐 upload_file_by_url - 从URL上传文件
   ℹ️  get_file_info - 获取文件信息
   📥 download_file - 下载文件
   🗑️  delete_file - 删除文件
   🗂️  batch_delete_files - 批量删除文件

✅ Server is ready to accept requests

📋 环境变量配置

| 变量名 | 默认值 | 说明 | |--------|--------|------| | API_BASE_URL | http://localhost:65203/api | AIGC 网络硬盘 API 基础URL | | API_TOKEN | - | API 访问令牌（可选，使用默认值如不设置） | | DEFAULT_EXPIRES_IN | 300 | 默认文件过期时间（秒） | | DEFAULT_PAGE_SIZE | 20 | 默认分页大小 | | MAX_BATCH_SIZE | 50 | 批量操作最大文件数 | | REQUEST_TIMEOUT | 30000 | 普通请求超时时间（毫秒） | | UPLOAD_TIMEOUT | 300000 | 上传超时时间（毫秒） | | DOWNLOAD_TIMEOUT | 300000 | 下载超时时间（毫秒） |

🔍 故障排除

常见问题

1. 服务器启动失败

错误信息： Configuration validation failed

解决方案：

• 检查 .env 文件是否存在且格式正确
• 确认 API_BASE_URL 格式正确（包含 http:// 或 https://）
• 验证环境变量值是否有效

2. 文件上传失败

错误信息： Network Error 或 File not found

解决方案：

• 检查网络连接和API服务器状态
• 确认文件路径正确且文件存在
• 检查文件权限和大小限制
• 验证 API Token 是否有效

3. 下载失败

错误信息： Permission denied 或 Disk space

解决方案：

• 检查目标目录写权限
• 确认磁盘空间足够
• 验证文件URL是否有效且未过期
• 检查网络连接稳定性

4. 删除操作失败

错误信息： Forbidden 或 Not found

解决方案：

• 确认具有删除权限
• 检查文件是否存在且未过期
• 验证 API Token 权限
• 确认 confirm 参数设置为 true

调试技巧

1. 启用详细日志：开发模式会显示详细的HTTP请求日志
2. 检查配置：服务器启动时会验证并显示配置信息
3. 使用单文件操作：批量操作失败时，先尝试单文件操作定位问题
4. 网络诊断：使用 curl 或浏览器直接测试API接口

联系支持

如果遇到无法解决的问题：

1. 收集错误日志和配置信息
2. 描述重现步骤
3. 提供系统环境信息
4. 在 GitHub Issues 提交问题

📄 许可证

本项目使用 MIT 许可证。详见 LICENSE 文件。

🤝 贡献

欢迎提交 Pull Request 和 Issue！

📚 相关链接

• Model Context Protocol (MCP) 官方文档
• AIGC Hub
• 项目 GitHub 仓库