# SVG 转换器 FastMCP 服务
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
[](https://github.com/RusianHu/svg-converter-tools-mcp)
一个基于 FastMCP 的专业 SVG 文件转换服务包，提供完整的 SVG 转换功能。支持将 SVG 转换为 PNG、ICO、JPG 等格式，优先使用 Cairo C库 进行高质量渲染，特别优化了中文字符的显示效果。
## 🎨 支持的输出格式
| 格式 | 扩展名 | 透明支持 | 适用场景 | 推荐用途 |
|------|--------|----------|----------|----------|
| **PNG** | `.png` | ✅ | 图标、图形、UI元素 | 推荐格式，质量最佳 |
| **ICO** | `.ico` | ✅ | 应用程序图标 | Windows 图标文件 |
| **JPG/JPEG** | `.jpg`, `.jpeg` | ❌ | 照片、复杂图像 | 文件较小，不支持透明 |
### 🏗️ 项目架构
```mermaid
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 转换流程
```mermaid
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 安装（推荐）
```bash
# 直接从 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/
```
### 方法二：从源码安装
```bash
# 克隆仓库
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/
```
### 安装可选依赖（强烈推荐）
```bash
# 安装 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](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases)
2. 下载并安装最新版本的 GTK+ Runtime Environment
3. 然后安装 cairosvg：
```bash
pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/
```
**Linux/macOS 用户：**
```bash
# 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/
```
### 验证安装
```bash
# 检查版本信息
python -m svg_converter_mcp --version
# 检查依赖项状态
python -m svg_converter_mcp --check-deps
```
## 🔌 MCP 客户端配置
### 基本配置
在您的 MCP 客户端配置文件（如 `mcp_settings.json`）中添加：
```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 库
```bash
pip install cairosvg -i https://pypi.tuna.tsinghua.edu.cn/simple/
```
### 🥈 SVGLib (svglib + reportlab) - 兼容
- ✅ **纯 Python**: 无需系统级依赖
- ✅ **良好支持**: 支持大部分 SVG 特性
- ⚠️ **中文限制**: 中文字体支持有限
- ✅ **稳定性**: 成熟的 Python 实现
```bash
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'
```
**解决方案**:
```bash
# 确保包已正确安装
pip install -e .
# 或重新安装
pip uninstall svg-converter-mcp -y && pip install .
```
#### 2. 依赖库缺失
```
DependencyError: cairosvg 和 svglib 均未安装
```
**解决方案**:
```bash
# 安装推荐的依赖库
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. **缓存结果**: 对于重复转换，考虑缓存输出结果
## 核心组件关系
```mermaid
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](https://github.com/jlowin/fastmcp) - 优秀的 MCP 服务框架
- [CairoSVG](https://cairosvg.org/) - 高质量的 SVG 渲染库
- [SVGLib](https://github.com/deeplook/svglib) - 纯 Python SVG 处理库
- [Pillow](https://pillow.readthedocs.io/) - Python 图像处理库
## 📄 许可证
本项目采用 [MIT 许可证](LICENSE)。
