SVG 转换器 FastMCP 服务

一个基于 FastMCP 的专业 SVG 文件转换服务包，提供完整的 SVG 转换功能。支持将 SVG 转换为 PNG、ICO、JPG 等格式，优先使用 Cairo C库 进行高质量渲染，特别优化了中文字符的显示效果。

🎨 支持的输出格式

格式	扩展名	透明支持	适用场景	推荐用途
PNG	.png	✅	图标、图形、UI元素	推荐格式，质量最佳
ICO	.ico	✅	应用程序图标	Windows 图标文件
JPG/JPEG	.jpg, .jpeg	❌	照片、复杂图像	文件较小，不支持透明

🏗️ 项目架构

graph TB
    subgraph "MCP 客户端层"
        A[MCP 客户端<br/>Claude Desktop/其他]
        B[HTTP 客户端<br/>Web 应用]
        C[SSE 客户端<br/>实时应用]
    end

    subgraph "FastMCP 服务层"
        D[FastMCP 框架]
        E[STDIO 传输]
        F[HTTP 传输]
        G[SSE 传输]
    end

    subgraph "工具函数层"
        H[convert_svg_file<br/>文件转换]
        I[convert_svg_string<br/>字符串转换]
        J[batch_convert_svg_files<br/>批量转换]
        K[get_converter_engine_info<br/>引擎信息]
        L[get_svg_file_info<br/>文件信息]
        M[get_svg_string_info<br/>字符串信息]
    end

    subgraph "核心转换层"
        N[SVGConverter 类]
        O[Cairo C库 引擎]
        P[SVGLib 引擎]
        Q[PIL 引擎]
        R[混合渲染引擎]
    end

    A -.->|JSON-RPC| E
    B -.->|HTTP API| F
    C -.->|Server-Sent Events| G

    E --> D
    F --> D
    G --> D

    D --> H
    D --> I
    D --> J
    D --> K
    D --> L
    D --> M

    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    M --> N

    N --> O
    N --> P
    N --> Q
    N --> R

    style A fill:#e3f2fd
    style B fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style N fill:#f3e5f5
    style O fill:#e8f5e8
    style P fill:#e8f5e8
    style Q fill:#e8f5e8
    style R fill:#e8f5e8

� SVG 转换流程

flowchart TD
    A[SVG 输入] --> B{检测内容类型}
    B -->|包含中文字符| C[混合渲染模式]
    B -->|纯英文/图形| D[标准引擎模式]

    C --> C1[Cairo/SVGLib 渲染基础图形]
    C1 --> C2[PIL 覆盖渲染中文文字]
    C2 --> E[图像后处理]

    D --> D1{选择转换引擎}
    D1 -->|优先| D2[Cairo C库]
    D1 -->|备选| D3[SVGLib + ReportLab]
    D1 -->|后备| D4[PIL 直接渲染]

    D2 --> E
    D3 --> E
    D4 --> E

    E --> F{输出格式}
    F -->|PNG| G[PNG 输出<br/>支持透明背景]
    F -->|ICO| H[ICO 输出<br/>图标格式]
    F -->|JPG| I[JPG 输出<br/>照片格式]

    G --> J[转换完成]
    H --> J
    I --> J

    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style C fill:#fff3e0
    style D fill:#f3e5f5

🚀 安装方法

方法一：从 GitHub 安装（推荐）

# 直接从 GitHub 安装最新版本
pip install git+https://github.com/RusianHu/svg-converter-tools-mcp.git -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 安装完整版本（包含所有可选依赖）
pip install "git+https://github.com/RusianHu/svg-converter-tools-mcp.git[full]" -i https://pypi.tuna.tsinghua.edu.cn/simple/

方法二：从源码安装

# 克隆仓库
git clone https://github.com/RusianHu/svg-converter-tools-mcp.git
cd svg_converter_tools_mcp

# 基础安装
pip install . -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 开发模式安装
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple/

安装可选依赖（强烈推荐）

# 安装 Cairo C库 支持（最高质量渲染）
pip install .[cairo] -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 安装 SVGLib 支持（良好兼容性）
pip install .[svglib] -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 安装所有可选依赖（推荐）
pip install .[full] -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 开发环境安装
pip install .[dev] -i https://pypi.tuna.tsinghua.edu.cn/simple/

Cairo C库 安装说明

为了获得最佳的 SVG 渲染质量，建议安装 Cairo C库：

Windows 用户：

1. 访问 GTK for Windows Runtime Environment
2. 下载并安装最新版本的 GTK+ Runtime Environment
3. 然后安装 cairosvg：

   pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/
   

Linux/macOS 用户：

# Ubuntu/Debian
sudo apt-get install libcairo2-dev libgirepository1.0-dev

# CentOS/RHEL
sudo yum install cairo-devel gobject-introspection-devel

# macOS
brew install cairo gobject-introspection

# 然后安装 cairosvg
pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/

验证安装

# 检查版本信息
python -m svg_converter_mcp --version

# 检查依赖项状态
python -m svg_converter_mcp --check-deps

🔌 MCP 客户端配置

基本配置

在您的 MCP 客户端配置文件（如 mcp_settings.json）中添加：

{
  "mcpServers": {
    "svg-converter-mcp": {
      "command": "python",
      "args": ["-m", "svg_converter_mcp"],
      "disabled": false
    }
  }
}

🛠️ 可用工具函数

安装后，MCP 客户端可以使用以下 6 个工具函数：

1. convert_svg_file

从文件路径转换 SVG

• 参数: svg_file_path, output_file_path, output_format, width, height, scale, quality, background, transparent, prefer_engine
• 返回: 转换结果信息，包含输出路径、文件大小、使用的引擎等
• 用途: 转换本地 SVG 文件为指定格式

2. convert_svg_string

从 SVG 字符串内容转换

• 参数: svg_content, output_file_path, output_format, width, height, scale, quality, background, transparent, prefer_engine
• 返回: 转换结果信息
• 用途: 直接从内存中的 SVG 内容转换，无需先保存为文件

3. batch_convert_svg_files

批量转换多个 SVG 文件

• 参数: svg_files, output_directory, output_format, width, height, quality, background, transparent, prefer_engine
• 返回: 批量转换结果报告，包含成功/失败统计
• 用途: 一次性处理多个 SVG 文件，提高效率

4. get_converter_engine_info

获取转换引擎信息

• 参数: prefer_engine
• 返回: 当前引擎状态、可用引擎列表、安装建议
• 用途: 查看系统中可用的转换引擎状态

5. get_svg_file_info

获取 SVG 文件详细信息

• 参数: svg_file_path
• 返回: 文件信息、尺寸分析、转换建议
• 用途: 分析 SVG 文件的特征和复杂度

6. get_svg_string_info

获取 SVG 字符串信息

• 参数: svg_content
• 返回: 内容分析、特征检测、转换建议
• 用途: 分析 SVG 内容特征，如是否包含中文字符等

⚙️ 转换引擎说明

🏆 Cairo C库 (cairosvg) - 推荐

• ✅ 最高质量: 完整的 SVG 规范支持
• ✅ 中文优化: 优秀的中文字体渲染效果
• ✅ 功能完整: 支持复杂的 SVG 特性
• ❌ 依赖要求: 需要额外安装 Cairo 库

pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/

🥈 SVGLib (svglib + reportlab) - 兼容

• ✅ 纯 Python: 无需系统级依赖
• ✅ 良好支持: 支持大部分 SVG 特性
• ⚠️ 中文限制: 中文字体支持有限
• ✅ 稳定性: 成熟的 Python 实现

pip install svglib reportlab -i https://pypi.tuna.tsinghua.edu.cn/simple/

🥉 PIL (Pillow) - 后备

• ✅ 内置支持: 无需额外依赖
• ✅ 轻量级: 占用资源少
• ❌ 功能限制: 仅支持基本 SVG 元素
• ❌ 质量一般: 中文字体渲染效果有限

🔧 配置选项

命令行参数

参数	说明	默认值	示例
--transport	传输协议	stdio	http, sse
--host	服务器地址	127.0.0.1	0.0.0.0
--port	端口号	8000	9000
--debug	调试模式	False	-
--version	显示版本	-	-
--check-deps	检查依赖	-	-

转换参数

参数	类型	说明	范围/选项
output_format	str	输出格式	png, ico, jpg, jpeg
width	int	输出宽度	1-8192 像素
height	int	输出高度	1-8192 像素
scale	float	缩放比例	0.1-10.0
quality	int	JPG 质量	1-100
background	str	背景颜色	颜色名称或十六进制
transparent	bool	透明背景	true, false
prefer_engine	str	首选引擎	auto, cairosvg, svglib, pil

🐛 故障排除

常见问题

1. 导入错误

ImportError: No module named 'svg_converter_mcp'

解决方案:

# 确保包已正确安装
pip install -e .
# 或重新安装
pip uninstall svg-converter-mcp -y && pip install .

2. 依赖库缺失

DependencyError: cairosvg 和 svglib 均未安装

解决方案:

# 安装推荐的依赖库
pip install .[full] -i https://pypi.tuna.tsinghua.edu.cn/simple/

3. 中文字符显示异常

现象: 中文字符显示为方块或乱码

解决方案:

• 确保安装了 cairosvg: pip install cairosvg
• 检查系统中文字体: 确保系统安装了中文字体
• 使用引擎检查: python -m svg_converter_mcp --check-deps

4. MCP 客户端连接失败

现象: MCP 客户端无法连接到服务

解决方案:

• 检查 Python 路径是否正确
• 确认包已正确安装: python -m svg_converter_mcp --version
• 验证配置文件语法: 确保 JSON 格式正确
• 检查端口占用: 如使用 HTTP 模式，确保端口未被占用

5. 转换质量不佳

现象: 输出图像质量不理想

解决方案:

• 优先使用 cairosvg 引擎
• 适当增加输出尺寸 (width, height)
• 对于文本内容，建议使用 PNG 格式
• 检查原始 SVG 文件质量

性能优化建议

1. 安装 Cairo C库: 获得最佳转换质量和性能
2. 使用批量转换: 处理多个文件时使用 batch_convert_svg_files
3. 合理设置尺寸: 避免过大的输出尺寸影响性能
4. 选择合适格式: PNG 用于图标，JPG 用于照片
5. 缓存结果: 对于重复转换，考虑缓存输出结果

核心组件关系

classDiagram
    class SVGConverter {
        +prefer_engine: str
        +engine: str
        +convert_file(svg_path, output_path, ...)
        +convert_string(svg_content, output_path, ...)
        +batch_convert(svg_files, output_dir, ...)
        +get_svg_info(svg_path)
        +get_engine_info()
        -_check_dependencies()
        -_select_engine()
        -_render_svg_with_hybrid_method()
        -_convert_with_cairosvg()
        -_convert_with_svglib()
    }

    class FastMCP {
        +name: str
        +instructions: str
        +run(transport, host, port)
    }

    class ConverterTools {
        +convert_svg_file()
        +convert_svg_string()
        +batch_convert_svg_files()
        +get_converter_engine_info()
        +get_svg_file_info()
        +get_svg_string_info()
    }

    class Engines {
        <<interface>>
        +Cairo C库
        +SVGLib + ReportLab
        +PIL (Pillow)
        +混合渲染引擎
    }

    class Exceptions {
        +SVGConverterError
        +DependencyError
        +ConversionError
    }

    FastMCP --> ConverterTools : 注册工具函数
    ConverterTools --> SVGConverter : 使用
    SVGConverter --> Engines : 调用
    SVGConverter --> Exceptions : 抛出

    note for SVGConverter "核心转换类\n支持多种引擎\n智能中文渲染"
    note for FastMCP "MCP 服务框架\n支持多种传输协议"
    note for Engines "转换引擎优先级:\n1. Cairo (最高质量)\n2. SVGLib (良好兼容)\n3. PIL (基本功能)"

🙏 致谢

• FastMCP - 优秀的 MCP 服务框架
• CairoSVG - 高质量的 SVG 渲染库
• SVGLib - 纯 Python SVG 处理库
• Pillow - Python 图像处理库

📄 许可证

本项目采用 MIT 许可证。