aj-geddes/sailor

🧜‍♀️ Sailor - Mermaid Diagram Generator

Get a picture of your Mermaid! 🎨

Sailor combines a beautiful web interface with an MCP (Model Context Protocol) server for generating and rendering Mermaid diagrams. Use the web UI for interactive diagram creation, or integrate with Claude Desktop for AI-powered diagram generation through natural language.

✨ Features

🌐 Web Interface

• 🎨 AI-Powered Generation: Generate diagrams using OpenAI or Anthropic APIs
• 🔄 Live Preview: Real-time rendering with syntax highlighting
• 📋 Copy Functions: Copy both code and rendered images
• 🎯 Style Controls: Theme and appearance customization
• ✅ API Key Validation: Instant feedback on key validity

🤖 MCP Server

• 📐 All Mermaid Diagram Types: Flowcharts, sequence, gantt, class, state, ER, pie, mindmap, journey, timeline
• 🎨 Multiple Themes: Default, dark, forest, neutral
• ✏️ Hand-drawn Look: Optional sketch-style rendering
• 🖼️ Flexible Output: PNG with transparent background support
• 🤖 LLM Integration: Works with Claude Desktop via MCP
• 🐳 Fully Containerized: No dependencies needed except Docker

🚀 Quick Start

Choose your preferred way to use Sailor:

Option A: Web Interface 🌐

1. Clone and Setup:

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

2. Configure Environment (backend folder):

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

3. Run with Docker:

docker-compose up -d

4. Access: Open http://localhost:5000

Option B: Claude Desktop Integration 🤖

Prerequisites: Docker Desktop + Claude Desktop

1. Clone and Build:

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

2. Configure Claude Desktop:

Add the following to your Claude Desktop configuration file:

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"
      ]
    }
  }
}

Note: Replace C:\\Users\\YourName\\Pictures with your desired output directory.

4. Restart Claude Desktop

Completely close and reopen Claude Desktop to load the new configuration.

📖 Usage

🌐 Web Interface

1. Enter API Key: Provide your OpenAI or Anthropic API key
2. Describe Your Diagram: Enter a natural language description
3. Generate: Click "Generate Diagram" to create Mermaid code
4. Customize: Use style controls to adjust appearance
5. Export: Copy the code or image with the copy buttons

🤖 Claude Desktop Integration

Once configured, you can use natural language commands in Claude Desktop:

• "Use sailor-mermaid to create a flowchart showing a login process"
• "Generate a sequence diagram with sailor-mermaid showing API calls"
• "Create a Gantt chart for a project timeline using sailor-mermaid"
• "Show me examples of Mermaid diagrams with sailor-mermaid"

Images are automatically saved to your configured output directory.

🛠️ Available Tools

1. request_mermaid_generation

Request AI to generate Mermaid diagram code based on your description.

2. validate_and_render_mermaid

Validate and render existing Mermaid code as an image.

3. get_mermaid_examples

Get examples of different Mermaid diagram types.

🎨 Styling Options

• Themes: default, dark, forest, neutral
• Look: classic, handDrawn
• Background: transparent, white
• Direction: TB (top-bottom), LR (left-right), BT, RL

📁 Project Structure

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/          # MCP server implementation
│       ├── server.py        # Main MCP server
│       ├── stdio_wrapper.py # Claude Desktop communication
│       ├── renderer.py      # Mermaid rendering engine
│       ├── validators.py    # Syntax validation
│       └── prompts.py       # AI prompt templates
├── tests/                   # Comprehensive test suite
├── Dockerfile.mcp-stdio     # MCP server container
├── docker-compose.yml       # Multi-service setup
├── setup.py                 # Python package setup
└── requirements.txt         # MCP dependencies

🧪 Development

Web UI Development

# 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

MCP Server Development

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

# Install dependencies
pip install -e .

# Install Playwright browsers
playwright install chromium

# Run tests
pytest

# Run MCP server directly
python -m sailor_mcp.stdio_wrapper

Full Stack Development

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

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

🐛 Troubleshooting

Server Not Appearing in Claude Desktop

1. Ensure Docker Desktop is running
2. Check the image exists: docker images | grep sailor-mcp
3. Verify config file location and JSON syntax
4. Restart Claude Desktop completely

Connection Issues

Test the server manually:

docker run -i --rm sailor-mcp

View Logs

Check Docker logs:

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

📝 License

MIT License - see file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🙏 Acknowledgments

• Built with MCP (Model Context Protocol)
• Powered by Mermaid.js for diagram rendering
• Uses Playwright for headless rendering

Made with ❤️ for Claude Desktop users