Universal File Converter MCP Server - 专业级多格式文件转换服务

Posted on

Universal File Converter MCP Server

Platform: Hugging Face Space (Gradio MCP)
License: Apache 2.0
Author: Agents-MCP-Hackathon
Published: 2025-06-05
Stars/Likes: 24
Quality Score: 3.85/5.0

概述 | Overview

中文

Universal File Converter 是一个基于 Gradio MCP 框架的通用文件格式转换服务器，支持 30+ 种文件格式之间的自由转换。该服务集成了专业的 ConvertAPI，为 AI 助手提供了强大的文件处理能力，涵盖文档、图片、表格、演示文稿和多媒体文件的全方位转换需求。

作为 Agents MCP Hackathon 的参赛项目，该服务器通过 Hugging Face Space 托管，支持即开即用的远程访问模式，同时也支持本地部署和 Space 复制以突破免费额度限制。其核心优势在于：

  1. 广泛的格式支持：覆盖 30 多种常见文件格式，包括 PDF、Office 文档、图片、音视频等
  2. 专业级转换质量：基于 ConvertAPI 提供工业级转换质量保证
  3. 灵活的使用方式：支持本地文件和远程 URL 两种输入模式
  4. 零配置快速启动：通过 SSE 协议直接连接远程服务，无需本地安装
  5. 可扩展的额度管理：通过 Duplicate Space 轻松扩展转换额度

English

Universal File Converter is a comprehensive file format conversion server built on the Gradio MCP framework, supporting free conversion between 30+ file formats. The service integrates the professional ConvertAPI to provide AI assistants with powerful file processing capabilities, covering the full range of document, image, spreadsheet, presentation, and multimedia file conversion needs.

As a project from the Agents MCP Hackathon, this server is hosted on Hugging Face Space, supporting ready-to-use remote access mode, as well as local deployment and Space duplication to bypass free tier limitations. Its core advantages include:

  1. Extensive Format Support: Covers 30+ common file formats including PDF, Office documents, images, audio/video, etc.
  2. Professional Conversion Quality: Based on ConvertAPI for industrial-grade conversion quality assurance
  3. Flexible Usage Modes: Supports both local file and remote URL input modes
  4. Zero-Config Quick Start: Direct connection to remote service via SSE protocol without local installation
  5. Scalable Quota Management: Easily extend conversion quota through Duplicate Space

核心特性 | Key Features

中文

🗂️ 全面的格式支持

文档格式 (Documents)

  • 输入支持: PDF, DOCX, DOC, RTF, ODT, TXT, HTML, EPUB, XPS
  • 输出支持: PDF, DOCX, TXT, HTML, EPUB, RTF
  • 典型转换:
    • DOCX ↔ PDF（保持格式完整性）
    • HTML → PDF（网页转文档）
    • EPUB ↔ PDF（电子书格式）
    • DOC → DOCX（格式升级）

图片格式 (Images)

  • 输入支持: PNG, JPG, JPEG, GIF, BMP, TIFF, TIF, WebP, SVG, ICO, HEIC
  • 输出支持: PNG, JPG, JPEG, GIF, BMP, TIFF, WebP, SVG, ICO
  • 典型转换:
    • PNG ↔ JPG（压缩优化）
    • SVG → PNG（矢量转位图）
    • HEIC → JPG（iOS 图片转换）
    • WebP ↔ PNG（现代格式转换）

表格格式 (Spreadsheets)

  • 输入支持: XLSX, XLS, CSV, ODS, TSV
  • 输出支持: XLSX, CSV, PDF
  • 典型转换:
    • XLSX → CSV（数据导出）
    • XLS → XLSX（格式升级）
    • CSV → PDF（数据报表）

演示文稿 (Presentations)

  • 输入支持: PPTX, PPT, ODP
  • 输出支持: PPTX, PDF
  • 典型转换:
    • PPTX → PDF（演示文档化）
    • PPT → PPTX（格式升级）

视频格式 (Videos)

  • 输入支持: MP4, AVI, MOV, WMV, FLV, MKV, WebM, M4V
  • 输出支持: MP4, AVI, MOV, WebM
  • 典型转换:
    • AVI → MP4（压缩优化）
    • MOV → MP4（跨平台兼容）
    • FLV → WebM（Web 视频）

音频格式 (Audio)

  • 输入支持: MP3, WAV, FLAC, AAC, OGG, WMA, M4A
  • 输出支持: MP3, WAV, FLAC, AAC, OGG
  • 典型转换:
    • WAV → MP3（音频压缩）
    • FLAC → MP3（无损转有损）
    • M4A → MP3（格式标准化）

🔄 双模式转换能力

本地文件转换

  • 支持直接读取本地文件系统中的文件
  • 适用于批量处理和离线转换场景
  • 支持相对路径和绝对路径
  • 自动检测文件格式并选择最佳转换策略

URL 远程转换

  • 支持从任意 HTTP/HTTPS URL 获取文件
  • 无需下载即可直接转换远程文档
  • 适用于 Web 内容抓取和在线文档处理
  • 支持带认证的私有资源访问

⚡ ConvertAPI 专业引擎

  • 高质量转换: 工业级转换引擎，保持格式完整性
  • 快速处理: 优化的转换算法，平均响应时间 < 5 秒
  • 稳定可靠: 99.9% 可用性保证
  • 持续更新: 定期更新支持最新文件格式标准

🎯 免费额度与扩展方案

免费额度

  • 默认提供 250 次转换请求
  • 适用于轻量级使用和测试场景
  • 无需注册即可使用公共 Space

扩展方案

  1. Duplicate Space（推荐）

    • 一键复制到个人账户
    • 添加自己的 ConvertAPI Key
    • 根据 ConvertAPI 套餐获得更多额度
    • 完全独立的服务实例

  2. ConvertAPI 付费计划

    • Starter: $9.99/月（1,500 次转换）
    • Professional: $24.99/月（5,000 次转换）
    • Business: $99.99/月（25,000 次转换）
    • Enterprise: 定制方案

English

🗂️ Comprehensive Format Support

Document Formats

  • Input Support: PDF, DOCX, DOC, RTF, ODT, TXT, HTML, EPUB, XPS
  • Output Support: PDF, DOCX, TXT, HTML, EPUB, RTF
  • Typical Conversions:
    • DOCX ↔ PDF (maintain format integrity)
    • HTML → PDF (web to document)
    • EPUB ↔ PDF (e-book formats)
    • DOC → DOCX (format upgrade)

Image Formats

  • Input Support: PNG, JPG, JPEG, GIF, BMP, TIFF, TIF, WebP, SVG, ICO, HEIC
  • Output Support: PNG, JPG, JPEG, GIF, BMP, TIFF, WebP, SVG, ICO
  • Typical Conversions:
    • PNG ↔ JPG (compression optimization)
    • SVG → PNG (vector to raster)
    • HEIC → JPG (iOS image conversion)
    • WebP ↔ PNG (modern format conversion)

Spreadsheet Formats

  • Input Support: XLSX, XLS, CSV, ODS, TSV
  • Output Support: XLSX, CSV, PDF
  • Typical Conversions:
    • XLSX → CSV (data export)
    • XLS → XLSX (format upgrade)
    • CSV → PDF (data reporting)

Presentation Formats

  • Input Support: PPTX, PPT, ODP
  • Output Support: PPTX, PDF
  • Typical Conversions:
    • PPTX → PDF (presentation documentation)
    • PPT → PPTX (format upgrade)

Video Formats

  • Input Support: MP4, AVI, MOV, WMV, FLV, MKV, WebM, M4V
  • Output Support: MP4, AVI, MOV, WebM
  • Typical Conversions:
    • AVI → MP4 (compression optimization)
    • MOV → MP4 (cross-platform compatibility)
    • FLV → WebM (web video)

Audio Formats

  • Input Support: MP3, WAV, FLAC, AAC, OGG, WMA, M4A
  • Output Support: MP3, WAV, FLAC, AAC, OGG
  • Typical Conversions:
    • WAV → MP3 (audio compression)
    • FLAC → MP3 (lossless to lossy)
    • M4A → MP3 (format standardization)

🔄 Dual-Mode Conversion Capability

Local File Conversion

  • Direct access to files in the local file system
  • Suitable for batch processing and offline conversion scenarios
  • Supports relative and absolute paths
  • Automatic format detection and optimal conversion strategy selection

URL Remote Conversion

  • Fetch files from any HTTP/HTTPS URL
  • Direct conversion without downloading remote documents
  • Suitable for web content scraping and online document processing
  • Supports authenticated private resource access

⚡ ConvertAPI Professional Engine

  • High-Quality Conversion: Industrial-grade conversion engine maintaining format integrity
  • Fast Processing: Optimized conversion algorithms with average response time < 5 seconds
  • Stable & Reliable: 99.9% availability guarantee
  • Continuous Updates: Regular updates supporting the latest file format standards

🎯 Free Tier & Extension Plans

Free Tier

  • Default 250 conversion requests
  • Suitable for lightweight usage and testing scenarios
  • No registration required for public Space

Extension Plans

  1. Duplicate Space (Recommended)

    • One-click copy to personal account
    • Add your own ConvertAPI Key
    • Get more quota based on ConvertAPI plan
    • Fully independent service instance

  2. ConvertAPI Paid Plans

    • Starter: $9.99/month (1,500 conversions)
    • Professional: $24.99/month (5,000 conversions)
    • Business: $99.99/month (25,000 conversions)
    • Enterprise: Custom plans

工具详解 | Tool Documentation

中文

Tool 1: convert_local_file

功能说明
转换本地文件系统中的文件到指定格式。

工具名称

1
universal_file_converter_convert_local_file

参数详解

参数名 类型 必需 默认值 说明
local_file_path string 是 - 要转换的本地文件路径（支持相对路径和绝对路径）
output_format string 否 pdf 目标输出格式（如 pdf, docx, png, mp4 等）

返回值

  • 成功: 返回转换后文件的路径或 Base64 编码内容
  • 失败: 返回错误信息和原因

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// 示例 1: 转换 Word 文档为 PDF
{
  "local_file_path": "/path/to/document.docx",
  "output_format": "pdf"
}

// 示例 2: 转换图片格式（PNG 转 JPG）
{
  "local_file_path": "./images/screenshot.png",
  "output_format": "jpg"
}

// 示例 3: 转换 Excel 为 CSV
{
  "local_file_path": "~/reports/data.xlsx",
  "output_format": "csv"
}

// 示例 4: 使用默认输出格式（PDF）
{
  "local_file_path": "/documents/report.docx"
}

注意事项

  1. 文件路径必须可访问，确保有读取权限
  2. 支持的输入格式取决于文件扩展名自动检测
  3. 大文件转换可能需要较长时间，建议设置合理的超时
  4. 转换后的文件默认存储在临时目录

错误处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 文件不存在
{
  "error": "FileNotFoundError",
  "message": "指定的文件路径不存在: /path/to/file.docx"
}

// 不支持的格式
{
  "error": "UnsupportedFormatError",
  "message": "不支持从 .xyz 格式转换到 pdf"
}

// 转换失败
{
  "error": "ConversionError",
  "message": "文件转换过程中发生错误，请检查文件是否损坏"
}

Tool 2: convert_from_url

功能说明
从远程 URL 获取文件并转换到指定格式。

工具名称

1
universal_file_converter_convert_from_url

参数详解

参数名 类型 必需 默认值 说明
document_url string 是 - 远程文档的 HTTP/HTTPS URL
output_format string 否 pdf 目标输出格式

返回值

  • 成功: 返回转换后文件的下载链接或 Base64 内容
  • 失败: 返回错误信息和原因

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// 示例 1: 转换在线 Word 文档为 PDF
{
  "document_url": "https://example.com/documents/report.docx",
  "output_format": "pdf"
}

// 示例 2: 转换网页为 PDF
{
  "document_url": "https://example.com/article.html",
  "output_format": "pdf"
}

// 示例 3: 转换在线图片格式
{
  "document_url": "https://cdn.example.com/image.png",
  "output_format": "jpg"
}

// 示例 4: 转换云存储文档
{
  "document_url": "https://drive.google.com/uc?export=download&id=FILE_ID",
  "output_format": "pdf"
}

支持的 URL 类型

  • 直接文件链接（Direct file URLs）
  • 云存储分享链接（Cloud storage share links）
  • 带认证的私有资源（Authenticated URLs）
  • API 返回的文档链接（API document endpoints）

注意事项

  1. URL 必须可公开访问或提供正确的认证信息
  2. 远程服务器必须支持文件下载
  3. 大文件下载和转换耗时较长
  4. 某些网站可能有防盗链机制，需要特殊处理

错误处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// URL 无法访问
{
  "error": "URLAccessError",
  "message": "无法访问指定的 URL: 404 Not Found"
}

// 下载超时
{
  "error": "TimeoutError",
  "message": "下载文件超时，请检查网络连接或文件大小"
}

// 格式不支持
{
  "error": "UnsupportedFormatError",
  "message": "无法从 URL 检测到有效的文件格式"
}

English

Tool 1: convert_local_file

Function Description
Convert files in the local file system to a specified format.

Tool Name

1
universal_file_converter_convert_local_file

Parameter Details

Parameter Type Required Default Description
local_file_path string Yes - Local file path to convert (supports relative and absolute paths)
output_format string No pdf Target output format (e.g., pdf, docx, png, mp4, etc.)

Return Value

  • Success: Returns the path or Base64-encoded content of the converted file
  • Failure: Returns error information and reason

Usage Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Example 1: Convert Word document to PDF
{
  "local_file_path": "/path/to/document.docx",
  "output_format": "pdf"
}

// Example 2: Convert image format (PNG to JPG)
{
  "local_file_path": "./images/screenshot.png",
  "output_format": "jpg"
}

// Example 3: Convert Excel to CSV
{
  "local_file_path": "~/reports/data.xlsx",
  "output_format": "csv"
}

// Example 4: Use default output format (PDF)
{
  "local_file_path": "/documents/report.docx"
}

Important Notes

  1. File path must be accessible with read permissions
  2. Supported input formats depend on automatic file extension detection
  3. Large file conversions may take longer; recommend setting reasonable timeouts
  4. Converted files are stored in temporary directory by default

Error Handling

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// File not found
{
  "error": "FileNotFoundError",
  "message": "Specified file path does not exist: /path/to/file.docx"
}

// Unsupported format
{
  "error": "UnsupportedFormatError",
  "message": "Conversion from .xyz format to pdf is not supported"
}

// Conversion failed
{
  "error": "ConversionError",
  "message": "Error occurred during file conversion, please check if file is corrupted"
}

Tool 2: convert_from_url

Function Description
Fetch a file from a remote URL and convert it to a specified format.

Tool Name

1
universal_file_converter_convert_from_url

Parameter Details

Parameter Type Required Default Description
document_url string Yes - HTTP/HTTPS URL of the remote document
output_format string No pdf Target output format

Return Value

  • Success: Returns download link or Base64 content of the converted file
  • Failure: Returns error information and reason

Usage Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example 1: Convert online Word document to PDF
{
  "document_url": "https://example.com/documents/report.docx",
  "output_format": "pdf"
}

// Example 2: Convert web page to PDF
{
  "document_url": "https://example.com/article.html",
  "output_format": "pdf"
}

// Example 3: Convert online image format
{
  "document_url": "https://cdn.example.com/image.png",
  "output_format": "jpg"
}

// Example 4: Convert cloud storage document
{
  "document_url": "https://drive.google.com/uc?export=download&id=FILE_ID",
  "output_format": "pdf"
}

Supported URL Types

  • Direct file URLs
  • Cloud storage share links
  • Authenticated URLs
  • API document endpoints

Important Notes

  1. URL must be publicly accessible or provide correct authentication
  2. Remote server must support file downloads
  3. Large file downloads and conversions take longer
  4. Some websites may have hotlink protection requiring special handling

Error Handling

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// URL inaccessible
{
  "error": "URLAccessError",
  "message": "Cannot access specified URL: 404 Not Found"
}

// Download timeout
{
  "error": "TimeoutError",
  "message": "File download timeout, please check network connection or file size"
}

// Format not supported
{
  "error": "UnsupportedFormatError",
  "message": "Cannot detect valid file format from URL"
}

安装配置 | Installation & Configuration

中文

方式 1: 使用远程 HF Space（推荐）

这是最简单的使用方式，无需本地安装任何依赖。

步骤 1: 配置 Claude Desktop

编辑配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "type": "sse",
      "url": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

步骤 2: 重启 Claude Desktop

配置完成后重启 Claude Desktop 应用，服务器将自动连接。

步骤 3: 验证安装

在 Claude Desktop 中输入：

1
请列出可用的文件转换工具

应该能看到两个工具：

  • universal_file_converter_convert_local_file
  • universal_file_converter_convert_from_url

方式 2: Duplicate Space 扩展额度

当免费额度不够用时，可以复制 Space 到自己的账户。

步骤 1: 访问原始 Space

打开浏览器访问：

1
https://huggingface.co/spaces/Agents-MCP-Hackathon/universal-file-converter

步骤 2: Duplicate Space

  1. 点击页面右上角的 “⋮” 菜单
  2. 选择 “Duplicate this Space”
  3. 选择目标账户和 Space 名称
  4. 点击 “Duplicate Space”

步骤 3: 配置 ConvertAPI Key

  1. 访问 ConvertAPI 注册账户
  2. 获取 API Secret Key
  3. 在你的 Space 设置中添加 Secret：
    • Name: CONVERTAPI_SECRET
    • Value: 你的 API Key
  4. 重启 Space

步骤 4: 更新 MCP 配置

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "type": "sse",
      "url": "https://YOUR-USERNAME-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

将 YOUR-USERNAME 替换为你的 Hugging Face 用户名。

方式 3: 本地部署

适用于需要完全控制服务或处理敏感文件的场景。

系统要求

  • Python 3.8 或更高版本
  • pip 包管理器
  • 至少 500MB 可用磁盘空间
  • 稳定的网络连接（用于 ConvertAPI 调用）

步骤 1: 克隆仓库

1
2
3
# 克隆 Hugging Face Space 仓库
git clone https://huggingface.co/spaces/Agents-MCP-Hackathon/universal-file-converter
cd universal-file-converter

步骤 2: 安装依赖

1
2
3
4
5
6
7
# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

步骤 3: 配置环境变量

1
2
3
4
5
# 设置 ConvertAPI Key（可选，用于扩展额度）
export CONVERTAPI_SECRET='your-api-key-here'

# 设置服务端口（可选，默认 7860）
export PORT=7860

步骤 4: 启动服务

1
2
# 启动 Gradio 应用
python app.py

服务将在 http://localhost:7860 启动。

步骤 5: 配置 MCP 连接

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

在其他 MCP 客户端中使用

VS Code (MCP Extension)

在 .vscode/mcp.json 中配置：

1
2
3
4
5
6
7
8
{
  "servers": {
    "file-converter": {
      "type": "sse",
      "url": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

Cursor

在 Cursor 设置中添加 MCP 服务器：

1
2
3
4
5
6
7
8
9
10
{
  "mcp": {
    "servers": {
      "file-converter": {
        "type": "sse",
        "url": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
      }
    }
  }
}

Cline

在 Cline 配置文件中添加：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "transport": "sse",
      "endpoint": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

English

This is the simplest method without requiring any local installation.

Step 1: Configure Claude Desktop

Edit the configuration file ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "type": "sse",
      "url": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

Step 2: Restart Claude Desktop

After configuration, restart the Claude Desktop application and the server will connect automatically.

Step 3: Verify Installation

In Claude Desktop, enter:

1
Please list available file conversion tools

You should see two tools:

  • universal_file_converter_convert_local_file
  • universal_file_converter_convert_from_url

Method 2: Duplicate Space to Extend Quota

When the free tier is insufficient, you can copy the Space to your own account.

Step 1: Visit Original Space

Open your browser and visit:

1
https://huggingface.co/spaces/Agents-MCP-Hackathon/universal-file-converter

Step 2: Duplicate Space

  1. Click the “⋮” menu in the top right corner
  2. Select “Duplicate this Space”
  3. Choose target account and Space name
  4. Click “Duplicate Space”

Step 3: Configure ConvertAPI Key

  1. Visit ConvertAPI to register an account
  2. Get your API Secret Key
  3. Add Secret in your Space settings:
    • Name: CONVERTAPI_SECRET
    • Value: Your API Key
  4. Restart Space

Step 4: Update MCP Configuration

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "type": "sse",
      "url": "https://YOUR-USERNAME-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

Replace YOUR-USERNAME with your Hugging Face username.

Method 3: Local Deployment

Suitable for scenarios requiring full control or handling sensitive files.

System Requirements

  • Python 3.8 or higher
  • pip package manager
  • At least 500MB available disk space
  • Stable network connection (for ConvertAPI calls)

Step 1: Clone Repository

1
2
3
# Clone Hugging Face Space repository
git clone https://huggingface.co/spaces/Agents-MCP-Hackathon/universal-file-converter
cd universal-file-converter

Step 2: Install Dependencies

1
2
3
4
5
6
7
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

Step 3: Configure Environment Variables

1
2
3
4
5
# Set ConvertAPI Key (optional, for extending quota)
export CONVERTAPI_SECRET='your-api-key-here'

# Set service port (optional, default 7860)
export PORT=7860

Step 4: Start Service

1
2
# Start Gradio application
python app.py

Service will start at http://localhost:7860.

Step 5: Configure MCP Connection

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Using in Other MCP Clients

VS Code (MCP Extension)

Configure in .vscode/mcp.json:

1
2
3
4
5
6
7
8
{
  "servers": {
    "file-converter": {
      "type": "sse",
      "url": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

Cursor

Add MCP server in Cursor settings:

1
2
3
4
5
6
7
8
9
10
{
  "mcp": {
    "servers": {
      "file-converter": {
        "type": "sse",
        "url": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
      }
    }
  }
}

Cline

Add in Cline configuration file:

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "file-converter": {
      "transport": "sse",
      "endpoint": "https://agents-mcp-hackathon-universal-file-converter.hf.space/gradio_api/mcp/sse"
    }
  }
}

应用场景 | Use Cases

中文

1. 文档格式标准化

场景描述
企业内部文档格式不统一，需要批量转换为标准 PDF 格式以便归档和分享。

解决方案

1
2
3
用户: 请将 /documents/reports/ 目录下的所有 Word 文档转换为 PDF
AI: 我会帮你批量转换这些文档...
[使用 convert_local_file 工具依次转换每个文件]

适用场景

  • 公司文档归档
  • 合同文件标准化
  • 报告统一格式
  • 多语言文档处理

2. 图片格式优化

场景描述
网站需要优化图片加载速度，将所有 PNG 图片转换为压缩后的 JPG 格式。

解决方案

1
2
3
用户: 将网站 images 文件夹中的所有 PNG 图片转换为 JPG 格式
AI: 开始转换图片...
[批量处理，自动优化文件大小]

适用场景

  • 网站性能优化
  • 移动应用资源压缩
  • 云存储空间节省
  • 图片批量处理

3. 数据导出与报表生成

场景描述
从 Excel 数据表生成 PDF 报表，或将数据导出为 CSV 用于数据分析。

解决方案

1
2
3
用户: 将这个销售数据表 sales_2024.xlsx 转换为 PDF 报表
AI: 正在生成 PDF 报表...
[转换为格式化的 PDF 文档]

适用场景

  • 数据可视化报表
  • 财务报表生成
  • 数据分析导出
  • 跨系统数据传输

4. 媒体文件转换

场景描述
视频平台需要支持多种格式，将用户上传的各种视频格式统一转换为 MP4。

解决方案

1
2
3
用户: 将这个 AVI 格式的视频转换为 MP4
AI: 开始视频转换，这可能需要几分钟...
[高质量转码，保持视频质量]

适用场景

  • 视频平台格式统一
  • 音频格式转换
  • 媒体文件压缩
  • 跨平台兼容性

5. Web 内容转换

场景描述
将在线文章、网页内容保存为 PDF 格式以便离线阅读。

解决方案

1
2
3
用户: 将这个网页 https://example.com/article 转换为 PDF
AI: 正在抓取并转换网页...
[使用 convert_from_url 工具]

适用场景

  • 网页内容归档
  • 在线文档保存
  • 知识库建设
  • 研究资料收集

6. AI 数据预处理

场景描述
AI 模型训练需要特定格式的数据，批量转换原始数据文件。

解决方案

1
2
3
用户: 将训练数据集中的所有 DOCX 文件转换为纯文本
AI: 开始批量转换文本数据...
[提取纯文本内容，去除格式]

适用场景

  • NLP 模型训练数据准备
  • 图像识别数据集处理
  • 机器学习数据清洗
  • 数据集格式统一

English

1. Document Format Standardization

Scenario Description
Internal company documents are in various formats and need to be batch converted to standard PDF format for archiving and sharing.

Solution

1
2
3
User: Please convert all Word documents in /documents/reports/ to PDF
AI: I'll help you batch convert these documents...
[Using convert_local_file tool to convert each file sequentially]

Applicable Scenarios

  • Company document archiving
  • Contract file standardization
  • Report format unification
  • Multilingual document processing

2. Image Format Optimization

Scenario Description
Website needs to optimize image loading speed by converting all PNG images to compressed JPG format.

Solution

1
2
3
User: Convert all PNG images in the website images folder to JPG format
AI: Starting image conversion...
[Batch processing with automatic file size optimization]

Applicable Scenarios

  • Website performance optimization
  • Mobile app resource compression
  • Cloud storage space saving
  • Batch image processing

3. Data Export & Report Generation

Scenario Description
Generate PDF reports from Excel data tables or export data as CSV for data analysis.

Solution

1
2
3
User: Convert this sales data table sales_2024.xlsx to a PDF report
AI: Generating PDF report...
[Converting to formatted PDF document]

Applicable Scenarios

  • Data visualization reports
  • Financial report generation
  • Data analysis export
  • Cross-system data transfer

4. Media File Conversion

Scenario Description
Video platform needs to support multiple formats, uniformly converting various user-uploaded video formats to MP4.

Solution

1
2
3
User: Convert this AVI format video to MP4
AI: Starting video conversion, this may take a few minutes...
[High-quality transcoding, maintaining video quality]

Applicable Scenarios

  • Video platform format unification
  • Audio format conversion
  • Media file compression
  • Cross-platform compatibility

5. Web Content Conversion

Scenario Description
Save online articles and web content as PDF format for offline reading.

Solution

1
2
3
User: Convert this webpage https://example.com/article to PDF
AI: Fetching and converting webpage...
[Using convert_from_url tool]

Applicable Scenarios

  • Web content archiving
  • Online document saving
  • Knowledge base building
  • Research material collection

6. AI Data Preprocessing

Scenario Description
AI model training requires data in specific formats, batch converting raw data files.

Solution

1
2
3
User: Convert all DOCX files in the training dataset to plain text
AI: Starting batch text data conversion...
[Extracting plain text content, removing formatting]

Applicable Scenarios

  • NLP model training data preparation
  • Image recognition dataset processing
  • Machine learning data cleaning
  • Dataset format unification

常见问题 | FAQ

中文

Q1: 免费额度用完了怎么办？

A: 有三种解决方案：

  1. Duplicate Space（推荐）

    • 访问原始 Space 并点击 “Duplicate”
    • 添加自己的 ConvertAPI Key
    • 享受独立的转换额度

  2. 购买 ConvertAPI 套餐

    • Starter: $9.99/月（1,500 次）
    • Professional: $24.99/月（5,000 次）
    • Business: $99.99/月（25,000 次）

  3. 本地部署

    • 克隆仓库到本地
    • 使用自己的 API Key
    • 完全控制使用量

Q2: 支持哪些文件格式转换？

A: 支持 30+ 种格式，包括：

  • 文档: PDF, DOCX, DOC, TXT, RTF, ODT, HTML, EPUB
  • 图片: PNG, JPG, GIF, BMP, TIFF, WebP, SVG, HEIC
  • 表格: XLSX, XLS, CSV, ODS
  • 演示: PPTX, PPT, ODP
  • 视频: MP4, AVI, MOV, WMV, FLV, WebM
  • 音频: MP3, WAV, FLAC, AAC, OGG

具体支持的转换路径取决于 ConvertAPI 的能力。

Q3: 转换速度如何？

A: 转换速度取决于多个因素：

  • 小文件（< 1MB）: 通常 2-5 秒
  • 中等文件（1-10MB）: 5-15 秒
  • 大文件（> 10MB）: 15-60 秒或更长

影响因素：

  • 文件大小和复杂度
  • 网络连接速度
  • ConvertAPI 服务器负载
  • 转换类型复杂度

Q4: 转换后的文件存储在哪里？

A: 根据使用方式不同：

  • 远程 HF Space: 文件临时存储在 Hugging Face 服务器，转换完成后返回下载链接或 Base64 内容
  • 本地部署: 文件存储在系统临时目录，默认路径为 /tmp/converted_files/
  • 建议: 转换完成后及时下载或移动文件，临时文件会定期清理

Q5: 转换质量如何保证？

A: 使用 ConvertAPI 专业引擎：

  • 工业级转换: 与 Adobe、Microsoft 等企业级工具相当
  • 格式保真: 保持原始文档的布局、字体、图片等元素
  • OCR 支持: 自动识别扫描文档中的文本
  • 批量处理: 支持大规模文件转换而不降低质量

Q6: 是否支持批量转换？

A: 支持批量转换：

1
2
3
用户: 请将 /documents/ 目录下的所有 Word 文档转换为 PDF
AI: 我会依次转换这些文件...
[循环调用 convert_local_file 工具]

注意:

  • 批量转换会消耗多次转换额度
  • 建议控制单次批量数量（< 50 个文件）
  • 大批量转换建议使用本地部署方式

Q7: 转换失败了怎么办？

A: 常见问题和解决方案：

  1. 文件损坏

    • 检查源文件是否能正常打开
    • 尝试用原生应用程序修复文件

  2. 格式不支持

    • 确认转换路径是否在支持列表中
    • 尝试先转换为中间格式（如先转 PDF 再转其他格式）

  3. 文件过大

    • ConvertAPI 有文件大小限制（通常 100MB）
    • 尝试压缩或分割文件

  4. 网络超时

    • 检查网络连接
    • 增加超时时间设置
    • 尝试使用本地部署方式

Q8: 转换的文件安全吗？

A: 安全性说明：

  • 传输加密: 所有数据通过 HTTPS 加密传输
  • 临时存储: 转换后的文件仅临时存储，定期自动删除
  • ConvertAPI 隐私: ConvertAPI 承诺不存储用户文件超过 24 小时
  • 敏感文件: 建议使用本地部署方式处理敏感文档

最佳实践:

  • 不要转换包含机密信息的文件到公共 Space
  • 使用 Duplicate Space 或本地部署处理私密文件
  • 转换完成后立即删除临时文件

Q9: 如何获取 ConvertAPI Key？

A: 获取步骤：

  1. 访问 ConvertAPI 官网
  2. 点击 “Sign Up” 注册账户
  3. 验证邮箱后登录
  4. 在 Dashboard 中找到 “API Secret”
  5. 复制密钥并添加到环境变量或 Space Secret

注意:

  • 免费账户有 250 次转换限制
  • API Key 请勿公开分享
  • 定期检查使用量避免超额

Q10: 与其他文件转换工具相比有什么优势？

A: 核心优势：

  1. MCP 协议原生支持

    • 与 Claude 等 AI 助手深度集成
    • 自然语言交互，无需记忆命令
    • 自动化工作流程

  2. 广泛的格式支持

    • 30+ 种文件格式
    • 覆盖文档、图片、音视频全场景
    • 持续更新支持新格式

  3. 灵活的部署方式

    • 远程 HF Space（即开即用）
    • Duplicate Space（独立额度）
    • 本地部署（完全控制）

  4. 专业的转换质量

    • 基于 ConvertAPI 工业级引擎
    • 保持格式完整性
    • 支持复杂文档转换

  5. 零学习成本

    • 自然语言交互
    • 无需学习命令行工具
    • AI 自动处理错误和重试

English

Q1: What to do when free quota is exhausted?

A: Three solutions:

  1. Duplicate Space (Recommended)

    • Visit original Space and click “Duplicate”
    • Add your own ConvertAPI Key
    • Enjoy independent conversion quota

  2. Purchase ConvertAPI Plan

    • Starter: $9.99/month (1,500 conversions)
    • Professional: $24.99/month (5,000 conversions)
    • Business: $99.99/month (25,000 conversions)

  3. Local Deployment

    • Clone repository locally
    • Use your own API Key
    • Full control over usage

Q2: Which file format conversions are supported?

A: Supports 30+ formats including:

  • Documents: PDF, DOCX, DOC, TXT, RTF, ODT, HTML, EPUB
  • Images: PNG, JPG, GIF, BMP, TIFF, WebP, SVG, HEIC
  • Spreadsheets: XLSX, XLS, CSV, ODS
  • Presentations: PPTX, PPT, ODP
  • Videos: MP4, AVI, MOV, WMV, FLV, WebM
  • Audio: MP3, WAV, FLAC, AAC, OGG

Specific conversion paths depend on ConvertAPI capabilities.

Q3: How fast is the conversion?

A: Conversion speed depends on multiple factors:

  • Small files (< 1MB): Usually 2-5 seconds
  • Medium files (1-10MB): 5-15 seconds
  • Large files (> 10MB): 15-60 seconds or longer

Influencing factors:

  • File size and complexity
  • Network connection speed
  • ConvertAPI server load
  • Conversion type complexity

Q4: Where are converted files stored?

A: Depends on usage method:

  • Remote HF Space: Files temporarily stored on Hugging Face servers, download link or Base64 content returned after conversion
  • Local Deployment: Files stored in system temp directory, default path /tmp/converted_files/
  • Recommendation: Download or move files promptly after conversion, temporary files are periodically cleaned

Q5: How is conversion quality guaranteed?

A: Uses ConvertAPI professional engine:

  • Industrial-Grade Conversion: Comparable to enterprise tools like Adobe, Microsoft
  • Format Fidelity: Maintains original document layout, fonts, images, etc.
  • OCR Support: Automatically recognizes text in scanned documents
  • Batch Processing: Supports large-scale file conversion without quality degradation

Q6: Does it support batch conversion?

A: Supports batch conversion:

1
2
3
User: Please convert all Word documents in /documents/ directory to PDF
AI: I'll convert these files sequentially...
[Loop calling convert_local_file tool]

Notes:

  • Batch conversion consumes multiple conversion credits
  • Recommend controlling single batch quantity (< 50 files)
  • Large batch conversion recommended via local deployment

Q7: What if conversion fails?

A: Common issues and solutions:

  1. File Corrupted

    • Check if source file can be opened normally
    • Try repairing file with native application

  2. Format Not Supported

    • Confirm conversion path is in support list
    • Try converting to intermediate format first (e.g., to PDF then to other formats)

  3. File Too Large

    • ConvertAPI has file size limits (typically 100MB)
    • Try compressing or splitting file

  4. Network Timeout

    • Check network connection
    • Increase timeout settings
    • Try using local deployment method

Q8: Are converted files secure?

A: Security explanation:

  • Transmission Encryption: All data transmitted via HTTPS encryption
  • Temporary Storage: Converted files only temporarily stored, automatically deleted periodically
  • ConvertAPI Privacy: ConvertAPI commits to not storing user files beyond 24 hours
  • Sensitive Files: Recommend using local deployment for sensitive documents

Best Practices:

  • Don’t convert files with confidential information to public Space
  • Use Duplicate Space or local deployment for private files
  • Delete temporary files immediately after conversion

Q9: How to obtain ConvertAPI Key?

A: Steps to obtain:

  1. Visit ConvertAPI Official Site
  2. Click “Sign Up” to register account
  3. Login after email verification
  4. Find “API Secret” in Dashboard
  5. Copy key and add to environment variables or Space Secret

Notes:

  • Free account has 250 conversion limit
  • Don’t publicly share API Key
  • Regularly check usage to avoid overages

Q10: What advantages compared to other file conversion tools?

A: Core advantages:

  1. Native MCP Protocol Support

    • Deep integration with AI assistants like Claude
    • Natural language interaction, no command memorization
    • Automated workflows

  2. Extensive Format Support

    • 30+ file formats
    • Covers documents, images, audio/video full scenarios
    • Continuous updates for new format support

  3. Flexible Deployment Methods

    • Remote HF Space (ready-to-use)
    • Duplicate Space (independent quota)
    • Local deployment (full control)

  4. Professional Conversion Quality

    • Based on ConvertAPI industrial-grade engine
    • Maintains format integrity
    • Supports complex document conversion

  5. Zero Learning Cost

    • Natural language interaction
    • No need to learn command-line tools
    • AI automatically handles errors and retries

技术架构 | Technical Architecture

中文

系统架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
┌─────────────────────────────────────────────────────────┐
│                     MCP Client                          │
│            (Claude Desktop / VS Code / etc.)            │
└────────────────────┬────────────────────────────────────┘
                     │ SSE Connection
                     │ (MCP Protocol)
                     ↓
┌─────────────────────────────────────────────────────────┐
│              Gradio MCP Server                          │
│           (Hugging Face Space / Local)                  │
│                                                          │
│  ┌───────────────────────────────────────────────┐     │
│  │         MCP Protocol Handler                   │     │
│  │  - Tool Registration                           │     │
│  │  - Request Routing                             │     │
│  │  - Response Formatting                         │     │
│  └────────────┬──────────────────────────────────┘     │
│               │                                          │
│  ┌────────────▼──────────────────────────────────┐     │
│  │      File Conversion Service                   │     │
│  │  - Local File Handler                          │     │
│  │  - URL File Fetcher                            │     │
│  │  - Format Detector                             │     │
│  │  - Conversion Orchestrator                     │     │
│  └────────────┬──────────────────────────────────┘     │
│               │                                          │
└───────────────┼──────────────────────────────────────────┘
                │ HTTPS API
                ↓
┌─────────────────────────────────────────────────────────┐
│                  ConvertAPI Service                      │
│              (External Conversion Engine)                │
│                                                          │
│  - Document Conversion Engine                           │
│  - Image Processing Engine                              │
│  - Media Transcoding Engine                             │
│  - OCR Engine                                           │
└─────────────────────────────────────────────────────────┘

核心组件

1. MCP Protocol Handler

  • 职责：处理 MCP 协议通信
  • 功能：
    • 工具注册和发现
    • 请求参数验证
    • 错误处理和重试
    • 响应格式化

2. File Conversion Service

  • 职责：文件转换业务逻辑
  • 功能：
    • 文件格式自动检测
    • 转换路径选择
    • 临时文件管理
    • 进度跟踪

3. ConvertAPI Client

  • 职责：与 ConvertAPI 服务交互
  • 功能：
    • API 认证管理
    • 请求限流控制
    • 文件上传和下载
    • 错误重试机制

数据流

本地文件转换流程:

1
2
3
4
5
6
7
8
9
1. 用户请求 → MCP Client
2. MCP Client → Gradio Server (SSE)
3. Gradio Server → 读取本地文件
4. 检测文件格式和大小
5. 上传到 ConvertAPI
6. ConvertAPI 执行转换
7. 下载转换结果
8. 返回文件路径/内容 → MCP Client
9. 展示给用户

URL 文件转换流程:

1
2
3
4
5
6
7
8
9
1. 用户提供 URL → MCP Client
2. MCP Client → Gradio Server (SSE)
3. Gradio Server → 下载远程文件
4. 检测文件格式
5. 直接提交 URL 到 ConvertAPI
6. ConvertAPI 自动抓取并转换
7. 获取转换结果
8. 返回文件链接 → MCP Client
9. 展示给用户

技术栈

服务端

  • 框架: Gradio (Python Web Framework)
  • MCP 实现: Gradio MCP Extension
  • HTTP 服务: Uvicorn (ASGI Server)
  • 文件处理: python-magic, requests
  • API 客户端: convertapi-python

传输协议

  • MCP 协议: JSON-RPC over SSE
  • SSE: Server-Sent Events for real-time communication
  • HTTP/HTTPS: RESTful API calls

部署环境

  • Hugging Face Space: Docker container with Gradio SDK
  • Python Runtime: Python 3.9+
  • Resource Limits: 16GB RAM, 8 vCPU (HF Space)

English

System Architecture

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
┌─────────────────────────────────────────────────────────┐
│                     MCP Client                          │
│            (Claude Desktop / VS Code / etc.)            │
└────────────────────┬────────────────────────────────────┘
                     │ SSE Connection
                     │ (MCP Protocol)
                     ↓
┌─────────────────────────────────────────────────────────┐
│              Gradio MCP Server                          │
│           (Hugging Face Space / Local)                  │
│                                                          │
│  ┌───────────────────────────────────────────────┐     │
│  │         MCP Protocol Handler                   │     │
│  │  - Tool Registration                           │     │
│  │  - Request Routing                             │     │
│  │  - Response Formatting                         │     │
│  └────────────┬──────────────────────────────────┘     │
│               │                                          │
│  ┌────────────▼──────────────────────────────────┐     │
│  │      File Conversion Service                   │     │
│  │  - Local File Handler                          │     │
│  │  - URL File Fetcher                            │     │
│  │  - Format Detector                             │     │
│  │  - Conversion Orchestrator                     │     │
│  └────────────┬──────────────────────────────────┘     │
│               │                                          │
└───────────────┼──────────────────────────────────────────┘
                │ HTTPS API
                ↓
┌─────────────────────────────────────────────────────────┐
│                  ConvertAPI Service                      │
│              (External Conversion Engine)                │
│                                                          │
│  - Document Conversion Engine                           │
│  - Image Processing Engine                              │
│  - Media Transcoding Engine                             │
│  - OCR Engine                                           │
└─────────────────────────────────────────────────────────┘

Core Components

1. MCP Protocol Handler

  • Responsibility: Handle MCP protocol communication
  • Functions:
    • Tool registration and discovery
    • Request parameter validation
    • Error handling and retry
    • Response formatting

2. File Conversion Service

  • Responsibility: File conversion business logic
  • Functions:
    • Automatic file format detection
    • Conversion path selection
    • Temporary file management
    • Progress tracking

3. ConvertAPI Client

  • Responsibility: Interact with ConvertAPI service
  • Functions:
    • API authentication management
    • Request rate limiting control
    • File upload and download
    • Error retry mechanism

Data Flow

Local File Conversion Flow:

1
2
3
4
5
6
7
8
9
1. User request → MCP Client
2. MCP Client → Gradio Server (SSE)
3. Gradio Server → Read local file
4. Detect file format and size
5. Upload to ConvertAPI
6. ConvertAPI executes conversion
7. Download conversion result
8. Return file path/content → MCP Client
9. Display to user

URL File Conversion Flow:

1
2
3
4
5
6
7
8
9
1. User provides URL → MCP Client
2. MCP Client → Gradio Server (SSE)
3. Gradio Server → Download remote file
4. Detect file format
5. Submit URL directly to ConvertAPI
6. ConvertAPI automatically fetches and converts
7. Get conversion result
8. Return file link → MCP Client
9. Display to user

Technology Stack

Server-Side

  • Framework: Gradio (Python Web Framework)
  • MCP Implementation: Gradio MCP Extension
  • HTTP Server: Uvicorn (ASGI Server)
  • File Processing: python-magic, requests
  • API Client: convertapi-python

Transport Protocol

  • MCP Protocol: JSON-RPC over SSE
  • SSE: Server-Sent Events for real-time communication
  • HTTP/HTTPS: RESTful API calls

Deployment Environment

  • Hugging Face Space: Docker container with Gradio SDK
  • Python Runtime: Python 3.9+
  • Resource Limits: 16GB RAM, 8 vCPU (HF Space)

最佳实践 | Best Practices

中文

1. 选择合适的部署方式

远程 HF Space - 适用于：

  • 快速测试和原型开发
  • 轻量级使用（< 250 次/月）
  • 不涉及敏感数据
  • 无本地部署能力

Duplicate Space - 适用于：

  • 中等频率使用（> 250 次/月）
  • 需要独立控制
  • 希望定制配置
  • 有 ConvertAPI 付费计划

本地部署 - 适用于：

  • 高频率使用
  • 处理敏感文档
  • 需要完全控制
  • 有内网部署需求

2. 优化转换性能

文件大小控制

1
2
3
4
5
6
# 大文件建议先压缩
if file_size > 10MB:
    # 对于图片
    compress_image(input_path, quality=85)
    # 对于 PDF
    compress_pdf(input_path, optimization_level=2)

批量转换策略

1
2
3
4
5
6
# 使用并发转换提高效率
from concurrent.futures import ThreadPoolExecutor

files = [f1, f2, f3, ...]
with ThreadPoolExecutor(max_workers=5) as executor:
    results = executor.map(convert_file, files)

缓存机制

  • 对于相同文件的重复转换，使用缓存结果
  • 基于文件哈希值判断文件是否已转换
  • 设置合理的缓存过期时间

3. 错误处理和重试

实现智能重试

1
2
3
4
5
6
7
8
9
import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def convert_with_retry(file_path, output_format):
    return convert_file(file_path, output_format)

错误分类处理

  • 临时错误（网络超时）→ 自动重试
  • 永久错误（格式不支持）→ 立即返回错误
  • 配额错误（额度用尽）→ 提示用户升级

4. 安全性最佳实践

敏感文件处理

1
2
3
# 使用本地部署处理敏感文件
export CONVERTAPI_SECRET='your-key'
python app.py --local-only

文件验证

1
2
3
4
5
6
7
# 转换前验证文件类型
import magic

def validate_file_type(file_path, allowed_types):
    mime = magic.from_file(file_path, mime=True)
    if mime not in allowed_types:
        raise ValueError(f"Unsupported file type: {mime}")

临时文件清理

1
2
3
4
5
import atexit
import shutil

temp_dir = "/tmp/converted_files"
atexit.register(lambda: shutil.rmtree(temp_dir, ignore_errors=True))

5. 成本优化

额度监控

1
2
3
4
5
6
# 定期检查 ConvertAPI 使用量
def check_quota():
    api = convertapi.api.Api(os.environ['CONVERTAPI_SECRET'])
    usage = api.user()
    if usage['SecondsLeft'] < 100:
        send_alert("ConvertAPI quota running low")

智能格式选择

1
2
3
4
5
6
7
8
# 根据用途选择合适的输出格式
def choose_output_format(use_case):
    if use_case == "archiving":
        return "pdf"  # 长期保存
    elif use_case == "editing":
        return "docx"  # 继续编辑
    elif use_case == "web":
        return "html"  # Web 展示

English

1. Choose Appropriate Deployment Method

Remote HF Space - Suitable for:

  • Quick testing and prototyping
  • Lightweight usage (< 250 times/month)
  • No sensitive data involved
  • No local deployment capability

Duplicate Space - Suitable for:

  • Medium frequency usage (> 250 times/month)
  • Need independent control
  • Want to customize configuration
  • Have ConvertAPI paid plan

Local Deployment - Suitable for:

  • High frequency usage
  • Processing sensitive documents
  • Need full control
  • Have intranet deployment requirements

2. Optimize Conversion Performance

File Size Control

1
2
3
4
5
6
# Compress large files first
if file_size > 10MB:
    # For images
    compress_image(input_path, quality=85)
    # For PDF
    compress_pdf(input_path, optimization_level=2)

Batch Conversion Strategy

1
2
3
4
5
6
# Use concurrent conversion to improve efficiency
from concurrent.futures import ThreadPoolExecutor

files = [f1, f2, f3, ...]
with ThreadPoolExecutor(max_workers=5) as executor:
    results = executor.map(convert_file, files)

Caching Mechanism

  • For repeated conversions of the same file, use cached results
  • Determine if file has been converted based on file hash
  • Set reasonable cache expiration time

3. Error Handling and Retry

Implement Smart Retry

1
2
3
4
5
6
7
8
9
import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def convert_with_retry(file_path, output_format):
    return convert_file(file_path, output_format)

Error Classification Handling

  • Temporary errors (network timeout) → Auto retry
  • Permanent errors (format not supported) → Return error immediately
  • Quota errors (quota exhausted) → Prompt user to upgrade

4. Security Best Practices

Sensitive File Processing

1
2
3
# Use local deployment for sensitive files
export CONVERTAPI_SECRET='your-key'
python app.py --local-only

File Validation

1
2
3
4
5
6
7
# Validate file type before conversion
import magic

def validate_file_type(file_path, allowed_types):
    mime = magic.from_file(file_path, mime=True)
    if mime not in allowed_types:
        raise ValueError(f"Unsupported file type: {mime}")

Temporary File Cleanup

1
2
3
4
5
import atexit
import shutil

temp_dir = "/tmp/converted_files"
atexit.register(lambda: shutil.rmtree(temp_dir, ignore_errors=True))

5. Cost Optimization

Quota Monitoring

1
2
3
4
5
6
# Regularly check ConvertAPI usage
def check_quota():
    api = convertapi.api.Api(os.environ['CONVERTAPI_SECRET'])
    usage = api.user()
    if usage['SecondsLeft'] < 100:
        send_alert("ConvertAPI quota running low")

Smart Format Selection

1
2
3
4
5
6
7
8
# Choose appropriate output format based on use case
def choose_output_format(use_case):
    if use_case == "archiving":
        return "pdf"  # Long-term storage
    elif use_case == "editing":
        return "docx"  # Continue editing
    elif use_case == "web":
        return "html"  # Web display

中文

官方链接

相关项目

学习资源

社区支持

English

Learning Resources

Community Support

更新日志 | Changelog

2025-06-05

  • Initial release on Hugging Face Space
  • Support for 30+ file format conversions
  • ConvertAPI integration
  • Dual conversion modes (local file & URL)
  • Free tier with 250 conversion credits
  • Gradio MCP framework implementation
  • SSE protocol support for MCP clients

许可证 | License

Apache License 2.0

致谢 | Acknowledgments

中文

感谢以下项目和服务：

  • Anthropic - MCP 协议的创建者
  • Hugging Face - 提供免费的 Space 托管服务
  • ConvertAPI - 提供专业的文件转换 API
  • Gradio - 提供优秀的 Python Web 框架和 MCP 支持
  • Agents-MCP-Hackathon - 组织社区 Hackathon 活动

English

Thanks to the following projects and services:

  • Anthropic - Creator of MCP protocol
  • Hugging Face - Providing free Space hosting service
  • ConvertAPI - Providing professional file conversion API
  • Gradio - Providing excellent Python Web framework and MCP support
  • Agents-MCP-Hackathon - Organizing community Hackathon events

Quality Score: ⭐⭐⭐⭐ (3.85/5.0)

  • Functionality: 0.95/1.0
  • Documentation: 0.75/1.0
  • Activity: 0.65/1.0
  • Popularity: 0.70/1.0
  • Code Quality: 0.80/1.0

Community Stats: 24 Likes | Hackathon Project | Apache 2.0 License

Last Updated: 2025-10-14
Document Version: 2.0
Total Lines: 1300+

© 2025 Generative AI Discovery All Rights Reserved.
Theme by hiero