# SVG 转换器 FastMCP 服务

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.8.0+-green.svg)](https://github.com/jlowin/fastmcp)
[![GitHub](https://img.shields.io/badge/GitHub-svg--converter--tools--mcp-blue.svg)](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)。