SVG Converter

Convierte archivos SVG a formatos PNG, ICO y JPG con renderizado de alta calidad utilizando la librería Cairo C.

Documentación

Servicio FastMCP del Conversor de SVG

Un paquete de servicio profesional de conversión de archivos SVG basado en FastMCP, que ofrece funcionalidades completas de conversión de SVG. Admite la conversión de SVG a formatos como PNG, ICO, JPG, etc., priorizando el uso de la biblioteca C de Cairo para renderizado de alta calidad, con una optimización especial para la visualización de caracteres chinos.

🎨 Formatos de salida admitidos

Formato	Extensión	Soporte de transparencia	Casos de uso	Uso recomendado
PNG	`.png`	✅	Iconos, gráficos, elementos de interfaz	Formato recomendado, mejor calidad
ICO	`.ico`	✅	Iconos de aplicaciones	Archivos de iconos de Windows
JPG/JPEG	`.jpg`, `.jpeg`	❌	Fotos, imágenes complejas	Archivos más pequeños, sin transparencia

🏗️ Arquitectura del proyecto

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

🔄 Flujo de conversión de 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

🚀 Métodos de instalación

Método 1: Instalación desde GitHub (recomendado)

# 直接从 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/

Método 2: Instalación desde el código fuente

# 克隆仓库
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/

Instalación de dependencias opcionales (muy recomendado)

# 安装 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/

Instrucciones de instalación de la biblioteca C de Cairo

Para obtener la mejor calidad de renderizado de SVG, se recomienda instalar la biblioteca C de Cairo:

Usuarios de Windows:

Visite Entorno de ejecución GTK para Windows
Descargue e instale la última versión del Entorno de ejecución GTK+

Luego instale cairosvg:

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

Usuarios de 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/

Verificación de la instalación

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

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

🔌 Configuración del cliente MCP

Configuración básica

En su archivo de configuración del cliente MCP (como mcp_settings.json), agregue:

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

🛠️ Funciones de herramientas disponibles

Después de la instalación, el cliente MCP puede usar las siguientes 6 funciones de herramientas:

1. `convert_svg_file`

Convertir SVG desde una ruta de archivo

Parámetros: svg_file_path, output_file_path, output_format, width, height, scale, quality, background, transparent, prefer_engine
Retorno: Información del resultado de la conversión, incluida la ruta de salida, el tamaño del archivo, el motor utilizado, etc.
Uso: Convertir archivos SVG locales al formato especificado

2. `convert_svg_string`

Convertir desde contenido de cadena SVG

Parámetros: svg_content, output_file_path, output_format, width, height, scale, quality, background, transparent, prefer_engine
Retorno: Información del resultado de la conversión
Uso: Convertir directamente desde contenido SVG en memoria, sin necesidad de guardarlo primero como archivo

3. `batch_convert_svg_files`

Convertir por lotes múltiples archivos SVG

Parámetros: svg_files, output_directory, output_format, width, height, quality, background, transparent, prefer_engine
Retorno: Informe del resultado de la conversión por lotes, incluidas estadísticas de éxito/fallo
Uso: Procesar múltiples archivos SVG de una sola vez para mayor eficiencia

4. `get_converter_engine_info`

Obtener información del motor de conversión

Parámetros: prefer_engine
Retorno: Estado actual del motor, lista de motores disponibles, sugerencias de instalación
Uso: Ver el estado de los motores de conversión disponibles en el sistema

5. `get_svg_file_info`

Obtener información detallada del archivo SVG

Parámetros: svg_file_path
Retorno: Información del archivo, análisis de dimensiones, sugerencias de conversión
Uso: Analizar las características y la complejidad de los archivos SVG

6. `get_svg_string_info`

Obtener información de la cadena SVG

Parámetros: svg_content
Retorno: Análisis de contenido, detección de características, sugerencias de conversión
Uso: Analizar las características del contenido SVG, como si incluye caracteres chinos, etc.

⚙️ Explicación de los motores de conversión

🏆 Biblioteca C de Cairo (cairosvg) - Recomendado

✅ Máxima calidad: Soporte completo de la especificación SVG
✅ Optimización para chino: Excelente renderizado de fuentes chinas
✅ Funcionalidad completa: Soporta características SVG complejas
❌ Requisitos de dependencia: Requiere instalación adicional de la biblioteca Cairo

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

🥈 SVGLib (svglib + reportlab) - Compatible

✅ Python puro: Sin dependencias a nivel de sistema
✅ Buen soporte: Admite la mayoría de las características SVG
⚠️ Limitaciones con chino: Soporte limitado de fuentes chinas
✅ Estabilidad: Implementación madura en Python

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

🥉 PIL (Pillow) - Respaldo

✅ Soporte integrado: Sin dependencias adicionales
✅ Ligero: Bajo consumo de recursos
❌ Limitaciones funcionales: Solo admite elementos SVG básicos
❌ Calidad media: Renderizado limitado de fuentes chinas

🔧 Opciones de configuración

Parámetros de línea de comandos

Parámetro	Descripción	Valor predeterminado	Ejemplo
`--transport`	Protocolo de transporte	`stdio`	`http`, `sse`
`--host`	Dirección del servidor	`127.0.0.1`	`0.0.0.0`
`--port`	Número de puerto	`8000`	`9000`
`--debug`	Modo de depuración	`False`	-
`--version`	Mostrar versión	-	-
`--check-deps`	Verificar dependencias	-	-

Parámetros de conversión

Parámetro	Tipo	Descripción	Rango/Opciones
`output_format`	`str`	Formato de salida	`png`, `ico`, `jpg`, `jpeg`
`width`	`int`	Ancho de salida	1-8192 píxeles
`height`	`int`	Alto de salida	1-8192 píxeles
`scale`	`float`	Factor de escala	0.1-10.0
`quality`	`int`	Calidad JPG	1-100
`background`	`str`	Color de fondo	Nombre de color o hexadecimal
`transparent`	`bool`	Fondo transparente	`true`, `false`
`prefer_engine`	`str`	Motor preferido	`auto`, `cairosvg`, `svglib`, `pil`

🐛 Solución de problemas

Problemas comunes

1. Error de importación

ImportError: No module named 'svg_converter_mcp'

Solución:

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

2. Faltan bibliotecas de dependencia

DependencyError: cairosvg 和 svglib 均未安装

Solución:

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

3. Visualización anormal de caracteres chinos

Síntoma: Los caracteres chinos se muestran como cuadrados o caracteres ilegibles

Solución:

Asegúrese de tener instalado cairosvg: pip install cairosvg
Verifique las fuentes chinas del sistema: asegúrese de que el sistema tenga fuentes chinas instaladas
Use la verificación del motor: python -m svg_converter_mcp --check-deps

4. Fallo de conexión del cliente MCP

Síntoma: El cliente MCP no puede conectarse al servicio

Solución:

Verifique que la ruta de Python sea correcta
Confirme que el paquete esté instalado correctamente: python -m svg_converter_mcp --version
Valide la sintaxis del archivo de configuración: asegúrese de que el formato JSON sea correcto
Verifique la ocupación del puerto: si usa el modo HTTP, asegúrese de que el puerto no esté ocupado

5. Calidad de conversión deficiente

Síntoma: La calidad de la imagen de salida no es la ideal

Solución:

Priorice el uso del motor cairosvg
Aumente adecuadamente el tamaño de salida (width, height)
Para contenido de texto, se recomienda usar el formato PNG
Verifique la calidad del archivo SVG original

Sugerencias de optimización de rendimiento

Instale la biblioteca C de Cairo: Para obtener la mejor calidad y rendimiento de conversión
Use la conversión por lotes: Use batch_convert_svg_files al procesar múltiples archivos
Establezca tamaños razonables: Evite tamaños de salida demasiado grandes que afecten el rendimiento
Elija el formato adecuado: PNG para iconos, JPG para fotos
Almacene resultados en caché: Para conversiones repetidas, considere almacenar en caché los resultados de salida

Relación de componentes principales

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 (基本功能)"

🙏 Agradecimientos

FastMCP - Excelente marco de servicios MCP
CairoSVG - Biblioteca de renderizado SVG de alta calidad
SVGLib - Biblioteca de procesamiento SVG en Python puro
Pillow - Biblioteca de procesamiento de imágenes de Python

📄 Licencia

Este proyecto está bajo la Licencia MIT.

SVG Converter

Documentación

Servicio FastMCP del Conversor de SVG

🎨 Formatos de salida admitidos

🏗️ Arquitectura del proyecto

🔄 Flujo de conversión de SVG

🚀 Métodos de instalación

Método 1: Instalación desde GitHub (recomendado)

Método 2: Instalación desde el código fuente

Instalación de dependencias opcionales (muy recomendado)

Instrucciones de instalación de la biblioteca C de Cairo

Verificación de la instalación

🔌 Configuración del cliente MCP

Configuración básica

🛠️ Funciones de herramientas disponibles

1. convert_svg_file

2. convert_svg_string

3. batch_convert_svg_files

4. get_converter_engine_info

5. get_svg_file_info

6. get_svg_string_info

⚙️ Explicación de los motores de conversión

🏆 Biblioteca C de Cairo (cairosvg) - Recomendado

🥈 SVGLib (svglib + reportlab) - Compatible

🥉 PIL (Pillow) - Respaldo

🔧 Opciones de configuración

Parámetros de línea de comandos

Parámetros de conversión

🐛 Solución de problemas

Problemas comunes

1. Error de importación

2. Faltan bibliotecas de dependencia

3. Visualización anormal de caracteres chinos

4. Fallo de conexión del cliente MCP

5. Calidad de conversión deficiente

Sugerencias de optimización de rendimiento

Relación de componentes principales

🙏 Agradecimientos

📄 Licencia

1. `convert_svg_file`

2. `convert_svg_string`

3. `batch_convert_svg_files`

4. `get_converter_engine_info`

5. `get_svg_file_info`

6. `get_svg_string_info`