Sailor

Gere e renderize diagramas Mermaid como imagens usando LLMs.

Documentação

🧜‍♀️ Sailor - Gerador de Diagramas Mermaid

Tenha uma imagem do seu Mermaid! 🎨

O Sailor combina uma bela interface web com um servidor MCP (Model Context Protocol) para gerar e renderizar diagramas Mermaid. Use a interface web para criação interativa de diagramas, ou integre com o Claude Desktop para geração de diagramas com IA por meio de linguagem natural.

🆕 Novidades na v2.0

Arquitetura FastMCP Moderna: 70% menos código boilerplate com padrões baseados em decoradores
Desenvolvimento Simplificado: Sem mais complexidade de stdio_wrapper - o FastMCP cuida de tudo
Inicialização Mais Rápida: ~50% de melhoria no tempo de inicialização do servidor
Melhor Segurança de Tipos: Dicas de tipo Python nativas em todo o código
API Mais Limpa: Decoradores simples @mcp.tool() e @mcp.prompt()
Suporte a Transporte Duplo: Transportes stdio e HTTP/SSE integrados
Retorno Direto de Imagens: Use return_image=true para obter imagens inline sem download de arquivos

🏗️ Arquitetura

Sailor Architecture

O Sailor fornece 11 ferramentas, 11 prompts e uma biblioteca abrangente de recursos para geração de diagramas Mermaid.

✨ Recursos

🌐 Interface Web

🎨 Geração com IA: Gere diagramas usando APIs da OpenAI ou Anthropic
🔄 Pré-visualização ao Vivo: Renderização em tempo real com destaque de sintaxe
📋 Funções de Cópia: Copie tanto o código quanto as imagens renderizadas
🎯 Controles de Estilo: Personalização de tema e aparência
✅ Validação de Chave de API: Feedback instantâneo sobre a validade da chave

🤖 Servidor MCP (Desenvolvido com FastMCP)

📐 Todos os Tipos de Diagramas Mermaid: Fluxogramas, sequência, gantt, classe, estado, ER, pizza, mapa mental, jornada, linha do tempo
🎨 Múltiplos Temas: Padrão, escuro, floresta, neutro
✏️ Aparência Desenhada à Mão: Renderização opcional em estilo esboço
🖼️ Saída Flexível: PNG com suporte a fundo transparente
🤖 Integração com LLM: Funciona com Claude Desktop via MCP
🐳 Totalmente Containerizado: Nenhuma dependência necessária além do Docker
⚡ Arquitetura FastMCP: Código moderno e sustentável com decoradores

Sailor Architecture

🚀 Início Rápido

Escolha sua forma preferida de usar o Sailor:

Opção A: Interface Web 🌐

Clone e Configure:

git clone https://github.com/aj-geddes/sailor.git
cd sailor

Configure o Ambiente (pasta backend):

cd backend
cp .env.example .env
# Edit .env with your API keys

Execute com Docker:

docker-compose up -d

Acesse: Abra http://localhost:5000

Opção B: Integração com Claude Desktop 🤖

Pré-requisitos: Docker Desktop + Claude Desktop

Clone e Compile:

git clone https://github.com/aj-geddes/sailor.git
cd sailor
docker build -f Dockerfile.mcp-stdio -t sailor-mcp .

Configure o Claude Desktop:

Adicione o seguinte ao arquivo de configuração do Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sailor-mermaid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:\\Users\\YourName\\Pictures:/output",
        "sailor-mcp"
      ]
    }
  }
}

Nota: Substitua C:\\Users\\YourName\\Pictures pelo diretório de saída desejado.

4. Reinicie o Claude Desktop

Feche e reabra completamente o Claude Desktop para carregar a nova configuração.

Opção C: Servidor MCP Remoto ☁️

Use o Sailor sem qualquer instalação local conectando-se a um servidor MCP hospedado.

Configure o Claude Desktop para usar uma instância remota do Sailor:

{
  "mcpServers": {
    "sailor-remote": {
      "transport": {
        "type": "streamable-http",
        "url": "https://your-sailor-instance.up.railway.app/mcp"
      }
    }
  }
}

Benefícios do MCP Remoto:

Sem necessidade de Docker ou instalação local
Sempre disponível, funciona 24/7
Atualizações e manutenção automáticas
Funciona de qualquer máquina com Claude Desktop

Implante o Seu Próprio: Veja o Guia de Implantação no Railway para hospedar sua própria instância remota.

📖 Uso

🌐 Interface Web

Insira a Chave de API: Forneça sua chave de API da OpenAI ou Anthropic
Descreva Seu Diagrama: Insira uma descrição em linguagem natural
Gere: Clique em "Gerar Diagrama" para criar o código Mermaid
Personalize: Use os controles de estilo para ajustar a aparência
Exporte: Copie o código ou a imagem com os botões de cópia

🤖 Integração com Claude Desktop

Uma vez configurado, você pode usar comandos em linguagem natural no Claude Desktop:

"Use sailor-mermaid para criar um fluxograma mostrando um processo de login"
"Gere um diagrama de sequência com sailor-mermaid mostrando chamadas de API"
"Crie um gráfico de Gantt para um cronograma de projeto usando sailor-mermaid"
"Mostre-me exemplos de diagramas Mermaid com sailor-mermaid"

As imagens são salvas automaticamente no diretório de saída configurado.

🛠️ Ferramentas Disponíveis

Ferramentas de Renderização

Ferramenta	Descrição
`validate_and_render_mermaid`	Valida e renderiza código Mermaid como imagem. Opções: `return_image=true` para exibição inline, `return_base64_text=true` para base64 salvável
`get_diagram`	Recupera um diagrama renderizado pelo ID do arquivo. Use `as_base64_text=true` para obter base64 salvável
`request_mermaid_generation`	Solicita que a IA gere código de diagrama Mermaid com base na sua descrição

Salvando Imagens Localmente (Servidor Remoto)

Ao usar o Sailor via um servidor MCP remoto (como Railway), o servidor não pode gravar no seu sistema de arquivos local. Use return_base64_text=true para obter a imagem como base64 extraível:

# The response includes base64_data which you can save via:
echo "<base64_data>" | base64 -d > diagram.png

Ferramentas de Ajuda e Exemplos

Ferramenta	Descrição
`get_mermaid_examples`	Obtenha exemplos de diferentes tipos de diagramas Mermaid por categoria ou complexidade
`get_diagram_template`	Obtenha modelos personalizáveis para geração rápida de diagramas
`get_syntax_help`	Obtenha referência de sintaxe e ajuda para tipos específicos de diagramas

Ferramentas de Análise

Ferramenta	Descrição
`analyze_diagram_code`	Analise código Mermaid e forneça sugestões de melhoria
`suggest_diagram_improvements`	Obtenha sugestões direcionadas para melhorar diagramas existentes

Ferramentas de Status

Ferramenta	Descrição
`health_check`	Verifique a saúde do servidor e obtenha informações de status
`server_status`	Obtenha status detalhado do servidor e métricas

💬 Prompts Disponíveis

Assistentes interativos para ajudá-lo a criar diagramas por meio de conversas guiadas:

Diagramas de Fluxo e Processo

Prompt	Descrição
`flowchart_wizard`	Assistente interativo para criar diagramas de fluxograma
`sequence_diagram_wizard`	Guia para criar diagramas de sequência
`state_diagram_wizard`	Crie diagramas de máquina de estados para comportamento de sistemas
`troubleshooting_flowchart`	Crie fluxogramas de diagnóstico e solução de problemas

Diagramas de Dados e Estrutura

Prompt	Descrição
`er_diagram_wizard`	Projete diagramas de entidade-relacionamento para bancos de dados
`class_diagram_wizard`	Crie diagramas de classe para design orientado a objetos
`architecture_diagram`	Crie diagramas de arquitetura de sistemas

Diagramas de Visualização

Prompt	Descrição
`data_visualization`	Crie gráficos e visualizações de dados
`project_timeline`	Crie gráficos de Gantt para planejamento de projetos
`mindmap_wizard`	Crie mapas mentais para brainstorming e organização de conceitos
`user_journey_wizard`	Mapeie jornadas de clientes ou usuários

🎨 Opções de Estilo

Temas: default, dark, forest, neutral
Aparência: classic, handDrawn
Fundo: transparent, white
Direção: TB (de cima para baixo), LR (da esquerda para a direita), BT, RL

📁 Estrutura do Projeto

sailor/
├── backend/                  # Web UI Flask application
│   ├── app.py               # Main Flask server
│   ├── static/              # Frontend files (HTML/CSS/JS)
│   ├── requirements.txt     # Web UI dependencies
│   └── .env.example         # Environment template
├── src/
│   └── sailor_mcp/          # FastMCP server implementation
│       ├── server.py        # Main MCP server with decorators
│       ├── renderer.py      # Mermaid rendering engine
│       ├── validators.py    # Syntax validation
│       ├── prompts.py       # AI prompt templates
│       └── mermaid_resources.py # Examples and templates
├── tests/                   # Comprehensive test suite
├── Dockerfile.mcp-stdio     # MCP server container
├── docker-compose.yml       # Multi-service setup
├── setup.py                 # Python package setup (v2.0.0)
└── requirements.txt         # FastMCP dependencies

📚 Documentação

Documentação abrangente está disponível no diretório docs/:

docs/DOCKER.md - Implantação Docker, configuração de contêineres e melhores práticas
docs/PRODUCTION.md - Implantação em produção, endurecimento de segurança e monitoramento
docs/README.md - Índice completo da documentação
CLAUDE.md - Guia de desenvolvimento para assistentes de IA

Os scripts de desenvolvimento estão localizados no diretório scripts/.

🧪 Desenvolvimento

Desenvolvimento da Interface Web

# Setup environment
cd backend
cp .env.example .env
# Edit .env with your API keys

# Install dependencies
pip install -r requirements.txt

# Run Flask development server
python app.py
# Access at http://localhost:5000

Desenvolvimento do Servidor MCP (FastMCP v2.0)

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install FastMCP and dependencies
pip install fastmcp>=0.5.0
pip install -e .

# Install Playwright browsers
playwright install chromium

# Run tests
pytest

# Run MCP server with stdio (Claude Desktop)
python -m sailor_mcp.server

# Run MCP server with HTTP/SSE (Web clients)
python -m sailor_mcp.server --http --port 8000

Desenvolvimento Full Stack

# Run everything with Docker Compose
docker-compose up --build

# Web UI: http://localhost:5000
# MCP Server: Available for Claude Desktop integration

🐛 Solução de Problemas

Servidor Não Aparece no Claude Desktop

Certifique-se de que o Docker Desktop está em execução
Verifique se a imagem existe: docker images | grep sailor-mcp
Verifique a localização do arquivo de configuração e a sintaxe JSON
Reinicie completamente o Claude Desktop

Problemas de Conexão

Teste o servidor manualmente:

docker run -i --rm sailor-mcp

Ver Logs

Verifique os logs do Docker:

docker logs $(docker ps -a | grep sailor-mcp | awk '{print $1}')

📝 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/AmazingFeature)
Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
Envie para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

🙏 Agradecimentos

Construído com MCP (Model Context Protocol)
Desenvolvido com Mermaid.js para renderização de diagramas
Usa Playwright para renderização headless

Feito com ❤️ para usuários do Claude Desktop