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 用户：
- 访问 GTK for Windows Runtime Environment
- 下载并安装最新版本的 GTK+ Runtime Environment
- 然后安装 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 文件质量
性能优化建议
- 安装 Cairo C库: 获得最佳转换质量和性能
- 使用批量转换: 处理多个文件时使用
batch_convert_svg_files - 合理设置尺寸: 避免过大的输出尺寸影响性能
- 选择合适格式: PNG 用于图标，JPG 用于照片
- 缓存结果: 对于重复转换，考虑缓存输出结果
核心组件关系
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 (基本功能)"
🙏 致谢
📄 许可证
本项目采用 MIT 许可证。