Sailor

Genera y renderiza diagramas Mermaid como imágenes usando LLMs.

Documentación

🧜‍♀️ Sailor - Generador de Diagramas Mermaid

¡Obtén una imagen de tu Mermaid! 🎨

Sailor combina una hermosa interfaz web con un servidor MCP (Protocolo de Contexto de Modelo) para generar y renderizar diagramas Mermaid. Usa la interfaz web para la creación interactiva de diagramas, o intégralo con Claude Desktop para la generación de diagramas impulsada por IA mediante lenguaje natural.

🆕 Novedades en v2.0

Arquitectura FastMCP Moderna: 70% menos código repetitivo con patrones basados en decoradores
Desarrollo Simplificado: Sin complejidad de stdio_wrapper - FastMCP lo maneja todo
Inicio Más Rápido: ~50% de mejora en el tiempo de inicialización del servidor
Mejor Seguridad de Tipos: Sugerencias de tipos nativas de Python en todo el código
API Más Limpia: Decoradores simples @mcp.tool() y @mcp.prompt()
Soporte de Transporte Dual: Transportes stdio y HTTP/SSE integrados
Devolución Directa de Imágenes: Usa return_image=true para obtener imágenes en línea sin descargar archivos

🏗️ Arquitectura

Sailor Architecture

Sailor proporciona 11 herramientas, 11 indicaciones y una biblioteca integral de recursos para la generación de diagramas Mermaid.

✨ Características

🌐 Interfaz Web

🎨 Generación Impulsada por IA: Genera diagramas usando APIs de OpenAI o Anthropic
🔄 Vista Previa en Vivo: Renderizado en tiempo real con resaltado de sintaxis
📋 Funciones de Copiado: Copia tanto el código como las imágenes renderizadas
🎯 Controles de Estilo: Personalización de tema y apariencia
✅ Validación de Clave API: Retroalimentación instantánea sobre la validez de la clave

🤖 Servidor MCP (Impulsado por FastMCP)

📐 Todos los Tipos de Diagramas Mermaid: Diagramas de flujo, secuencia, gantt, clase, estado, ER, circular, mapa mental, viaje, línea de tiempo
🎨 Múltiples Temas: Predeterminado, oscuro, bosque, neutro
✏️ Apariencia de Mano Alzada: Renderizado opcional con estilo de boceto
🖼️ Salida Flexible: PNG con soporte de fondo transparente
🤖 Integración con LLM: Funciona con Claude Desktop a través de MCP
🐳 Totalmente Contenerizado: Sin dependencias necesarias excepto Docker
⚡ Arquitectura FastMCP: Código moderno y mantenible con decoradores

Sailor Architecture

🚀 Inicio Rápido

Elige tu forma preferida de usar Sailor:

Opción A: Interfaz Web 🌐

Clonar y Configurar:

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

Configurar el Entorno (carpeta backend):

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

Ejecutar con Docker:

docker-compose up -d

Acceso: Abre http://localhost:5000

Opción B: Integración con Claude Desktop 🤖

Requisitos previos: Docker Desktop + Claude Desktop

Clonar y Construir:

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

Configurar Claude Desktop:

Agrega lo siguiente a tu archivo de configuración de 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: Reemplaza C:\\Users\\YourName\\Pictures con el directorio de salida que desees.

4. Reiniciar Claude Desktop

Cierra y vuelve a abrir completamente Claude Desktop para cargar la nueva configuración.

Opción C: Servidor MCP Remoto ☁️

Usa Sailor sin ninguna instalación local conectándote a un servidor MCP alojado.

Configura Claude Desktop para usar una instancia remota de Sailor:

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

Beneficios del MCP Remoto:

No se requiere Docker ni instalación local
Siempre disponible, funciona 24/7
Actualizaciones y mantenimiento automáticos
Funciona desde cualquier máquina con Claude Desktop

Implementa el Tuyo: Consulta la Guía de Implementación en Railway para alojar tu propia instancia remota.

📖 Uso

🌐 Interfaz Web

Ingresa la Clave API: Proporciona tu clave API de OpenAI o Anthropic
Describe tu Diagrama: Ingresa una descripción en lenguaje natural
Generar: Haz clic en "Generar Diagrama" para crear código Mermaid
Personalizar: Usa los controles de estilo para ajustar la apariencia
Exportar: Copia el código o la imagen con los botones de copiado

🤖 Integración con Claude Desktop

Una vez configurado, puedes usar comandos en lenguaje natural en Claude Desktop:

"Usa sailor-mermaid para crear un diagrama de flujo que muestre un proceso de inicio de sesión"
"Genera un diagrama de secuencia con sailor-mermaid que muestre llamadas API"
"Crea un diagrama de Gantt para una línea de tiempo de proyecto usando sailor-mermaid"
"Muéstrame ejemplos de diagramas Mermaid con sailor-mermaid"

Las imágenes se guardan automáticamente en tu directorio de salida configurado.

🛠️ Herramientas Disponibles

Herramientas de Renderizado

Herramienta	Descripción
`validate_and_render_mermaid`	Valida y renderiza código Mermaid como imagen. Opciones: `return_image=true` para visualización en línea, `return_base64_text=true` para base64 guardable
`get_diagram`	Recupera un diagrama renderizado por ID de archivo. Usa `as_base64_text=true` para obtener base64 guardable
`request_mermaid_generation`	Solicita a la IA generar código de diagrama Mermaid basado en tu descripción

Guardar Imágenes Localmente (Servidor Remoto)

Cuando usas Sailor a través de un servidor MCP remoto (como Railway), el servidor no puede escribir en tu sistema de archivos local. Usa return_base64_text=true para obtener la imagen como base64 extraíble:

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

Herramientas de Ayuda y Ejemplos

Herramienta	Descripción
`get_mermaid_examples`	Obtén ejemplos de diferentes tipos de diagramas Mermaid por categoría o complejidad
`get_diagram_template`	Obtén plantillas personalizables para generación rápida de diagramas
`get_syntax_help`	Obtén referencia de sintaxis y ayuda para tipos específicos de diagramas

Herramientas de Análisis

Herramienta	Descripción
`analyze_diagram_code`	Analiza código Mermaid y proporciona sugerencias de mejora
`suggest_diagram_improvements`	Obtén sugerencias específicas para mejorar diagramas existentes

Herramientas de Estado

Herramienta	Descripción
`health_check`	Verifica la salud del servidor y obtén información de estado
`server_status`	Obtén estado detallado del servidor y métricas

💬 Indicaciones Disponibles

Asistentes interactivos para ayudarte a crear diagramas a través de conversaciones guiadas:

Diagramas de Flujo y Procesos

Indicación	Descripción
`flowchart_wizard`	Asistente interactivo para crear diagramas de flujo
`sequence_diagram_wizard`	Guía para crear diagramas de secuencia
`state_diagram_wizard`	Crea diagramas de máquina de estados para comportamiento de sistemas
`troubleshooting_flowchart`	Crea diagramas de flujo de diagnóstico y solución de problemas

Diagramas de Datos y Estructura

Indicación	Descripción
`er_diagram_wizard`	Diseña diagramas de entidad-relación para bases de datos
`class_diagram_wizard`	Crea diagramas de clases para diseño orientado a objetos
`architecture_diagram`	Crea diagramas de arquitectura de sistemas

Diagramas de Visualización

Indicación	Descripción
`data_visualization`	Crea gráficos y visualizaciones de datos
`project_timeline`	Crea diagramas de Gantt para planificación de proyectos
`mindmap_wizard`	Crea mapas mentales para lluvia de ideas y organización de conceptos
`user_journey_wizard`	Mapea recorridos de clientes o usuarios

🎨 Opciones de Estilo

Temas: default, dark, forest, neutral
Apariencia: classic, handDrawn
Fondo: transparent, white
Dirección: TB (arriba-abajo), LR (izquierda-derecha), BT, RL

📁 Estructura del Proyecto

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

📚 Documentación

Documentación completa disponible en el directorio docs/:

docs/DOCKER.md - Implementación con Docker, configuración de contenedores y mejores prácticas
docs/PRODUCTION.md - Implementación en producción, endurecimiento de seguridad y monitoreo
docs/README.md - Índice completo de documentación
CLAUDE.md - Guía de desarrollo para asistentes de IA

Los scripts de desarrollo se encuentran en el directorio scripts/.

🧪 Desarrollo

Desarrollo de la Interfaz 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

Desarrollo del 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

Desarrollo Full Stack

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

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

🐛 Solución de Problemas

El Servidor No Aparece en Claude Desktop

Asegúrate de que Docker Desktop esté ejecutándose
Verifica que la imagen exista: docker images | grep sailor-mcp
Verifica la ubicación del archivo de configuración y la sintaxis JSON
Reinicia Claude Desktop completamente

Problemas de Conexión

Prueba el servidor manualmente:

docker run -i --rm sailor-mcp

Ver Registros

Revisa los registros de Docker:

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

📝 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/AmazingFeature)
Realiza tus cambios (git commit -m 'Add some AmazingFeature')
Envía a la rama (git push origin feature/AmazingFeature)
Abre una Solicitud de Extracción

🙏 Agradecimientos

Construido con MCP (Protocolo de Contexto de Modelo)
Impulsado por Mermaid.js para el renderizado de diagramas
Usa Playwright para renderizado sin interfaz gráfica

Hecho con ❤️ para usuarios de Claude Desktop