sailor (Aj Geddes)

🧜‍♀️ 水手-美人鱼图生成器

](https://www.docker.com/)   ](https://github.com/aj-geddes/sailor)  

给你的美人鱼拍张照！ 🎨

Sailor将漂亮的web界面与MCP（模型上下文协议）服务器相结合，用于生成和渲染美人鱼图。使用web UI创建交互式图表，或与Claude Desktop集成，通过自然语言生成AI驱动的图表。

🆕 v2.0中的新增功能

• 现代FastMCP架构：使用基于装饰器的模式，样板代码减少70%
• 简化开发：不再有stdio_wrapper复杂性-FastMCP处理所有问题
• 更快的启动：服务器初始化时间缩短了约50%
• 更好的类型安全性：贯穿始终的原生Python类型提示
• 清洁剂API：简单 @mcp.tool() 和 @mcp.prompt() 装饰器
• 双重运输支持：内置stdio和HTTP/SSE传输
• 直接图像返回：使用 return_image=true 在不下载文件的情况下内联图像

🏗️ 建筑

Sailor Architecture

Sailor提供 11工具, 11个提示，以及用于生成Mermaid图的综合资源库。

✨ 特性

🌐 web界面

• 🎨 人工智能发电：使用OpenAI或Anthropic API生成图表
• 🔄 实时显示：实时渲染，语法高亮显示
• 📋 复制功能：复制代码和渲染图像
• 🎯 样式控制：主题和外观定制
• ✅ API密钥验证：密钥有效性即时反馈

🤖 MCP服务器（由FastMCP提供支持）

• 📐 所有美人鱼图类型：流程图、序列、甘特图、类别、状态、ER、饼图、思维导图、旅程、时间线
• 🎨 多个主题：默认值、深色、林色、中性
• ✏️ 手绘外观：可选草图样式渲染
• 🖼️ 灵活的输出：支持透明背景的PNG
• 🤖 LLM集成：通过MCP与Claude Desktop配合使用
• 🐳 完全集装箱化：除了Docker之外不需要依赖项
• ⚡ FastMCP架构：带有装饰器的现代、可维护的代码库

Sailor Architecture

🚀 快速开始

选择您喜欢的使用Sailor的方式：

选项A：Web界面🌐

1. 克隆和设置:

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

1. 配置环境 （后端文件夹）：

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

1. 使用Docker运行:

docker-compose up -d

1. 访问：打开http://localhost:5000

选项B:Claude桌面集成🤖

先决条件：Docker桌面+克劳德桌面

1. 克隆和构建:

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

1. 配置Claude桌面:

将以下内容添加到您的Claude Desktop配置文件中：

视窗: %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"
      ]
    }
  }
}

备注：替换 C:\\Users\\YourName\\Pictures 使用您想要的输出目录。

4.重新启动克劳德桌面

完全关闭并重新打开Claude Desktop以加载新配置。

选项C：远程MCP服务器☁️

通过连接到托管的MCP服务器，无需任何本地安装即可使用Sailor。

配置Claude桌面 要使用远程Sailor实例：

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

远程MCP的好处：

• 无需Docker或本地安装
• 始终可用，全天候运行
• 自动更新和维护
• 适用于任何配备Claude Desktop的机器

部署您自己的： 看 铁路部署指南 托管您自己的远程实例。

📖 用法

🌐 web界面

1. 输入API密钥：提供您的OpenAI或Anthropic API密钥
2. 描述你的图表：输入自然语言描述
3. 生成：点击“生成图表”创建Mermaid代码
4. 定制：使用样式控件调整外观
5. 出口：使用复制按钮复制代码或图像

🤖 Claude桌面集成

配置后，您可以在Claude Desktop中使用自然语言命令：

• “使用水手美人鱼创建显示登录过程的流程图”
• “生成一个显示API调用的带有sailor-mermaid的序列图”
• “使用水手美人鱼为项目时间表创建甘特图”
• “给我看美人鱼图和水手美人鱼的例子”

图像会自动保存到您配置的输出目录中。

🛠️ 可用工具

渲染工具

在本地保存图像（远程服务器）

当通过远程MCP服务器（如Railway）使用Sailor时，服务器无法写入您的本地文件系统。使用 return_base64_text=true 要获取可提取的base64格式的图像：

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

帮助和示例工具

分析工具

状态工具

💬 可用提示

交互式向导，通过引导对话帮助您创建图表：

流程图和工艺图

数据和结构图

可视化图表

🎨 造型选项

• 主题: default, dark, forest, neutral
• 看: classic, handDrawn
• 背景: transparent, white
• 方向: TB （上下）， LR （左右）， BT, RL

📁 项目结构

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

📚 文档

综合文档可在 docs/ 目录：

• **** -Docker部署、容器配置和最佳实践
• docs/PRODUCTION.md -生产部署、安全强化和监控
• docs/README.md -完整的文档索引
• CLAUDE.md -AI助手开发指南

开发脚本位于 scripts/ 目录。

🧪 发展

Web UI开发

# 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服务器开发（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

全栈开发

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

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

🐛 故障排除

服务器未出现在Claude桌面中

1. 确保Docker桌面正在运行
2. 检查图像是否存在： docker images | grep sailor-mcp
3. 验证配置文件位置和JSON语法
4. 完全重新启动克劳德桌面

连接问题

手动测试服务器：

docker run -i --rm sailor-mcp

查看日志

检查Docker日志：

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

📝 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🤝 贡献

欢迎投稿！请随时提交拉取请求。

1. 复刻仓库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

🙏 致谢

• 内置于 主控程序 （模型上下文协议）
• 由...驱动 Mermaid.js 用于图表渲染
• 用途 剧作家 用于无头渲染

______________________________________________________________________

由...制作❤️ 适用于Claude Desktop用户