SVG Converter

Converta arquivos SVG para os formatos PNG, ICO e JPG com renderização de alta qualidade usando a biblioteca Cairo C.

Documentação

Serviço FastMCP do SVG Converter

Um pacote de serviço profissional de conversão de arquivos SVG baseado em FastMCP, oferecendo funcionalidades completas de conversão SVG. Suporta conversão de SVG para PNG, ICO, JPG e outros formatos, priorizando o uso da biblioteca C Cairo para renderização de alta qualidade, com otimização especial para exibição de caracteres chineses.

🎨 Formatos de saída suportados

Formato	Extensão	Suporte a transparência	Cenário de uso	Uso recomendado
PNG	`.png`	✅	Ícones, gráficos, elementos de UI	Formato recomendado, melhor qualidade
ICO	`.ico`	✅	Ícones de aplicativos	Arquivo de ícone do Windows
JPG/JPEG	`.jpg`, `.jpeg`	❌	Fotos, imagens complexas	Arquivo menor, sem suporte a transparência

🏗️ Arquitetura do projeto

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

🔄 Fluxo de conversão 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 instalação

Método 1: Instalação pelo 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: Instalação a partir do código-fonte

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

Instalação de dependências opcionais (fortemente 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/

Instruções de instalação da biblioteca C Cairo

Para obter a melhor qualidade de renderização SVG, recomenda-se instalar a biblioteca C Cairo:

Usuários Windows:

Acesse GTK for Windows Runtime Environment
Baixe e instale a versão mais recente do GTK+ Runtime Environment

Em seguida, instale o cairosvg:

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

Usuários 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/

Verificando a instalação

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

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

🔌 Configuração do cliente MCP

Configuração básica

Adicione no arquivo de configuração do seu cliente MCP (como mcp_settings.json):

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

🛠️ Funções de ferramentas disponíveis

Após a instalação, o cliente MCP pode usar as seguintes 6 funções de ferramentas:

1. `convert_svg_file`

Converter SVG a partir do caminho do arquivo

Parâmetros: svg_file_path, output_file_path, output_format, width, height, scale, quality, background, transparent, prefer_engine
Retorno: Informações do resultado da conversão, incluindo caminho de saída, tamanho do arquivo, mecanismo usado, etc.
Uso: Converte arquivos SVG locais para o formato especificado

2. `convert_svg_string`

Converter a partir do conteúdo de string SVG

Parâmetros: svg_content, output_file_path, output_format, width, height, scale, quality, background, transparent, prefer_engine
Retorno: Informações do resultado da conversão
Uso: Converte diretamente do conteúdo SVG em memória, sem precisar salvar como arquivo primeiro

3. `batch_convert_svg_files`

Converter vários arquivos SVG em lote

Parâmetros: svg_files, output_directory, output_format, width, height, quality, background, transparent, prefer_engine
Retorno: Relatório de resultados da conversão em lote, incluindo estatísticas de sucesso/falha
Uso: Processa vários arquivos SVG de uma vez, aumentando a eficiência

4. `get_converter_engine_info`

Obter informações do mecanismo de conversão

Parâmetros: prefer_engine
Retorno: Status atual do mecanismo, lista de mecanismos disponíveis, sugestões de instalação
Uso: Verifica o status dos mecanismos de conversão disponíveis no sistema

5. `get_svg_file_info`

Obter informações detalhadas do arquivo SVG

Parâmetros: svg_file_path
Retorno: Informações do arquivo, análise de dimensões, sugestões de conversão
Uso: Analisa as características e a complexidade do arquivo SVG

6. `get_svg_string_info`

Obter informações da string SVG

Parâmetros: svg_content
Retorno: Análise de conteúdo, detecção de características, sugestões de conversão
Uso: Analisa as características do conteúdo SVG, como se contém caracteres chineses, etc.

⚙️ Explicação dos mecanismos de conversão

🏆 Biblioteca C Cairo (cairosvg) - Recomendado

✅ Qualidade máxima: Suporte completo à especificação SVG
✅ Otimização para chinês: Excelente renderização de fontes chinesas
✅ Funcionalidades completas: Suporta recursos SVG complexos
❌ Requisitos de dependência: Requer instalação adicional da biblioteca Cairo

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

🥈 SVGLib (svglib + reportlab) - Compatível

✅ Python puro: Sem dependências de nível de sistema
✅ Bom suporte: Suporta a maioria dos recursos SVG
⚠️ Limitação para chinês: Suporte limitado a fontes chinesas
✅ Estabilidade: Implementação Python madura

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

🥉 PIL (Pillow) - Reserva

✅ Suporte integrado: Sem dependências adicionais
✅ Leve: Consome poucos recursos
❌ Limitações de funcionalidade: Suporta apenas elementos SVG básicos
❌ Qualidade mediana: Renderização limitada de fontes chinesas

🔧 Opções de configuração

Parâmetros de linha de comando

Parâmetro	Descrição	Valor padrão	Exemplo
`--transport`	Protocolo de transporte	`stdio`	`http`, `sse`
`--host`	Endereço do servidor	`127.0.0.1`	`0.0.0.0`
`--port`	Número da porta	`8000`	`9000`
`--debug`	Modo de depuração	`False`	-
`--version`	Exibir versão	-	-
`--check-deps`	Verificar dependências	-	-

Parâmetros de conversão

Parâmetro	Tipo	Descrição	Faixa/Opções
`output_format`	`str`	Formato de saída	`png`, `ico`, `jpg`, `jpeg`
`width`	`int`	Largura de saída	1-8192 pixels
`height`	`int`	Altura de saída	1-8192 pixels
`scale`	`float`	Fator de escala	0.1-10.0
`quality`	`int`	Qualidade JPG	1-100
`background`	`str`	Cor de fundo	Nome da cor ou hexadecimal
`transparent`	`bool`	Fundo transparente	`true`, `false`
`prefer_engine`	`str`	Mecanismo preferido	`auto`, `cairosvg`, `svglib`, `pil`

🐛 Solução de problemas

Problemas comuns

1. Erro de importação

ImportError: No module named 'svg_converter_mcp'

Solução:

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

2. Biblioteca de dependência ausente

DependencyError: cairosvg 和 svglib 均未安装

Solução:

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

3. Exibição anormal de caracteres chineses

Sintoma: Caracteres chineses exibidos como quadrados ou caracteres ilegíveis

Solução:

Certifique-se de que o cairosvg está instalado: pip install cairosvg
Verifique as fontes chinesas do sistema: certifique-se de que o sistema possui fontes chinesas instaladas
Use a verificação de mecanismo: python -m svg_converter_mcp --check-deps

4. Falha na conexão do cliente MCP

Sintoma: O cliente MCP não consegue se conectar ao serviço

Solução:

Verifique se o caminho do Python está correto
Confirme se o pacote foi instalado corretamente: python -m svg_converter_mcp --version
Valide a sintaxe do arquivo de configuração: certifique-se de que o formato JSON está correto
Verifique a ocupação da porta: se estiver usando o modo HTTP, certifique-se de que a porta não está em uso

5. Qualidade de conversão insatisfatória

Sintoma: A qualidade da imagem de saída não é ideal

Solução:

Priorize o uso do mecanismo cairosvg
Aumente adequadamente as dimensões de saída (width, height)
Para conteúdo de texto, recomenda-se usar o formato PNG
Verifique a qualidade do arquivo SVG original

Recomendações de otimização de desempenho

Instale a biblioteca C Cairo: Obtenha a melhor qualidade e desempenho de conversão
Use conversão em lote: Ao processar vários arquivos, use batch_convert_svg_files
Defina dimensões adequadas: Evite dimensões de saída muito grandes que afetem o desempenho
Escolha o formato adequado: PNG para ícones, JPG para fotos
Armazene resultados em cache: Para conversões repetidas, considere armazenar em cache os resultados de saída

Relação dos componentes principais

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

🙏 Agradecimentos

FastMCP - Excelente framework de serviços MCP
CairoSVG - Biblioteca de renderização SVG de alta qualidade
SVGLib - Biblioteca de processamento SVG em Python puro
Pillow - Biblioteca de processamento de imagens Python

📄 Licença

Este projeto é licenciado sob a Licença MIT.

SVG Converter

Documentação

Serviço FastMCP do SVG Converter

🎨 Formatos de saída suportados

🏗️ Arquitetura do projeto

🔄 Fluxo de conversão SVG

🚀 Métodos de instalação

Método 1: Instalação pelo GitHub (recomendado)

Método 2: Instalação a partir do código-fonte

Instalação de dependências opcionais (fortemente recomendado)

Instruções de instalação da biblioteca C Cairo

Verificando a instalação

🔌 Configuração do cliente MCP

Configuração básica

🛠️ Funções de ferramentas disponíveis

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

⚙️ Explicação dos mecanismos de conversão

🏆 Biblioteca C Cairo (cairosvg) - Recomendado

🥈 SVGLib (svglib + reportlab) - Compatível

🥉 PIL (Pillow) - Reserva

🔧 Opções de configuração

Parâmetros de linha de comando

Parâmetros de conversão

🐛 Solução de problemas

Problemas comuns

1. Erro de importação

2. Biblioteca de dependência ausente

3. Exibição anormal de caracteres chineses

4. Falha na conexão do cliente MCP

5. Qualidade de conversão insatisfatória

Recomendações de otimização de desempenho

Relação dos componentes principais

🙏 Agradecimentos

📄 Licença

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`