dsltopngmcp (Bencan1a)

DSL到PNG MCP服务器

🎨 一个强大的模型上下文协议（MCP）服务器，使用Playwright浏览器自动化将领域特定语言（DSL）定义转换为高质量的PNG图像。

](https://docker.com)   

🚀 快速开始

开发环境

# 1. Clone the repository
git clone 
cd dslToPngMCP

# 2. Setup development environment
make setup-dev

# 3. Start all services
make dev

# 4. Access the application
open http://localhost

生产部署

# 1. Configure production environment
cp .env.production .env
# Edit .env with your production settings

# 2. Generate production secrets
./scripts/generate-secrets.sh

# 3. Deploy to production
make deploy-prod

📋 目录

• 特性
• 建筑
• 需求
• 安装
• 配置
• 用法
• API文档
• 发展
• 部署
• 监控
• 故障排除
• 贡献

✨ 特性

核心功能

• DSL到PNG转换：将JSON/YAML DSL定义转换为高质量的PNG图像
• MCP协议支持：全面实施AI集成的模型上下文协议
• 异步处理：使用Celery进行后台任务处理，以应对繁重的渲染工作负载
• 浏览器池：管理Playwright浏览器实例以获得最佳性能
• 智能缓存：基于Redis的缓存可缩短响应时间

生产就绪

• 多容器架构：具有适当隔离的6服务架构
• 负载平衡：具有轮转负载平衡的Nginx反向代理
• 自动缩放：对高需求场景的横向扩展支持
• 健康监测：全面的健康检查和监测
• 零停机部署：蓝绿色部署战略
• SSL/TLS支持：具有Let’s Encrypt集成的生产就绪HTTPS

开发者体验

• 热重新加载：具有实时代码重新加载功能的开发环境
• 交互式API文档：内置Swagger/OpenAPI文档
• 综合录井：跨所有服务的结构化日志记录
• 发出命令：所有操作的简单make命令
• 健康检查：内置健康监测和诊断

🏗️ 建筑

服务体系结构

graph TB
    Client[Client] --> Nginx[Nginx Proxy]
    Nginx --> FastAPI1[FastAPI Server 1]
    Nginx --> FastAPI2[FastAPI Server 2]
    FastAPI1 --> MCP[MCP Server]
    FastAPI2 --> MCP
    FastAPI1 --> Redis[(Redis)]
    FastAPI2 --> Redis
    Redis --> Celery1[Celery Worker 1]
    Redis --> Celery2[Celery Worker 2]
    Redis --> Celery3[Celery Worker 3]
    Redis --> Celery4[Celery Worker 4]
    Celery1 --> Playwright[Playwright Browsers]
    Celery2 --> Playwright
    Celery3 --> Playwright
    Celery4 --> Playwright
    Playwright --> Storage[(PNG Storage)]

网络体系结构

• 前端网络：Nginx代理和外部访问
• 后端网络：内部API通信（隔离）
• 浏览器网络：剧作家浏览器池（隔离）

资源分配

📋 需求

系统要求

• 码头工人：版本20.10或更高版本
• Docker Compose：2.0或更高版本
• 系统记忆体：最低8GB RAM（建议生产使用16GB）
• 磁盘空间：最小10GB可用空间
• 操作系统：Linux（Ubuntu 20.04+）、macOS（10.15+）或带WSL2的Windows

开发要求

• Git：用于版本控制
• 制造：便于执行命令
• 卷曲：用于API测试
• Node.js：版本18+（用于开发工具）

🔧 安装

开发设置

1. 克隆存储库

   git clone 
   cd dslToPngMCP

1. 运行开发设置

   make setup-dev

这将：

- 创建必要的目录 - 生成开发秘密 - 构建Docker镜像 - 设置SSL证书 - 配置环境文件

1. 启动开发环境

   make dev

1. 验证安装

   make health

生产设置

1. 准备生产环境

   # Copy production environment template
   cp .env.production .env

   # Edit configuration (IMPORTANT!)
   nano .env  # Update DOMAIN_NAME, passwords, etc.

1. 生成生产秘密

   # Generate strong passwords and keys
   openssl rand -base64 32 > secrets/app_secret_key.txt
   openssl rand -base64 16 > secrets/redis_password.txt
   openssl rand -base64 16 > secrets/grafana_password.txt
   chmod 600 secrets/*

1. 部署到生产

   make deploy-prod

⚙️ 配置

环境变量

核心应用程序设置

DSL_PNG_ENVIRONMENT=production          # Environment: development|production
DSL_PNG_DEBUG=false                     # Debug mode
DSL_PNG_LOG_LEVEL=INFO                  # Logging level
DSL_PNG_DOMAIN_NAME=yourdomain.com      # Your domain

数据库和缓存

DSL_PNG_REDIS_URL=redis://redis:6379/0  # Redis connection
DSL_PNG_CELERY_BROKER_URL=redis://redis:6379/1  # Celery broker

安全

DSL_PNG_SECRET_KEY_FILE=/run/secrets/app_secret_key  # App secret
DSL_PNG_ALLOWED_HOSTS=["yourdomain.com"]             # Allowed hosts
DSL_PNG_CORS_ORIGINS=["https://yourdomain.com"]      # CORS origins

演出

DSL_PNG_WORKERS=4                       # FastAPI workers
DSL_PNG_BROWSER_POOL_SIZE=5             # Browser instances
DSL_PNG_RATE_LIMIT_REQUESTS=50          # Rate limit

卷配置

永久存储

• PNG存储: /opt/dsl-png/storage/png -生成的PNG文件
• Redis数据: /opt/dsl-png/data/redis -Redis持久性
• 日志: /opt/dsl-png/logs -应用程序日志

临时存储

• HTML临时文件：浏览器生成的HTML文件
• 浏览器缓存：Playwright浏览器缓存

🎯 用法

REST API

同步渲染

curl -X POST "http://localhost/render" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl_content": "{\"width\": 400, \"height\": 300, \"elements\": [{\"type\": \"button\", \"layout\": {\"x\": 100, \"y\": 100, \"width\": 200, \"height\": 50}, \"label\": \"Click Me\", \"style\": {\"background\": \"#007bff\", \"color\": \"white\"}}]}",
    "options": {
      "width": 800,
      "height": 600
    }
  }'

异步渲染

# Submit rendering task
curl -X POST "http://localhost/render/async" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl_content": "...",
    "options": {"width": 800, "height": 600}
  }'

# Check task status
curl "http://localhost/status/{task_id}"

DSL验证

curl -X POST "http://localhost/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl_content": "{\"width\": 400, \"height\": 300, \"elements\": []}"
  }'

MCP协议

服务器实现了三个核心MCP工具：

1. 渲染_实物模型：将DSL转换为PNG
2. validate_dsl：验证DSL语法
3. get_nder_status：检查异步任务状态

可用端点

📚 文档

完整的文档套件

该项目包括全面的生产准备文件：

核心文件

• 📖 用户指南 -完整的用户指南，包括教程和最佳实践
• 🔧 安装指南 -开发和生产的详细安装
• 🎯 DSL参考 -完整的DSL语法和元素参考
• 🏗️ 架构指南 -系统架构和设计决策
• 📋 API文档 -完整的REST API和MCP协议参考

运营与维护

• ⚙️ 操作指南 -生产部署和维护程序
• 🔍 故障排除指南 -全面的诊断和问题解决指南
• 🤝 贡献指南 -开发人员贡献指南和工作流程

示例和教程

• 📝 示例和教程 -实践示例和集成模式
• 🎓 教程集 -常见用例的分步教程

交互式文档

• Swagger用户界面: http://localhost/docs -交互式API测试
• ReDoc: http://localhost/redoc -API综合参考

性能指标和能力

渲染性能

• 吞吐量：100+并发渲染操作
• 响应时间：典型UI模型\<2秒
• 图像质量：高分辨率PNG输出（最高4K）
• 浏览器池：5个并发剧作家实例
• 缓存命中率：85%以上使用Redis缓存

系统能力

• 并发用户：支持1000+个并发用户
• 每日效果图：每天100000多次渲染操作
• 运行时间：99.9%的可用性，具有健康监测功能
• 可扩展性：横向扩展与负载平衡
• 安全：生产级SSL/TLS和速率限制

DSL支持

• 元素类型：支持15+个UI元素
• 布局系统：绝对灵敏的定位
• 样式：完整的CSS样式支持
• 验证：实时DSL语法验证
• 格式支持：JSON和YAML输入格式

快速DSL示例

{
  "width": 800,
  "height": 600,
  "elements": [
    {
      "type": "button",
      "layout": {
        "x": 100,
        "y": 100,
        "width": 200,
        "height": 50
      },
      "label": "Click Me",
      "style": {
        "background": "#007bff",
        "color": "white",
        "border_radius": "5px"
      }
    }
  ]
}

📖 有关完整的DSL语法和示例，请参阅 DSL参考

🛠️ 发展

可用命令

# Development
make setup-dev      # Setup development environment
make dev           # Start development environment
make dev-logs      # Show development logs
make dev-stop      # Stop development environment

# Production
make deploy-prod   # Deploy to production
make prod          # Start production environment
make prod-logs     # Show production logs

# Testing
make test          # Run all tests
make test-unit     # Run unit tests
make health        # Run health checks

# Utilities
make shell-fastapi # Access FastAPI container
make redis-cli     # Access Redis CLI
make logs          # Show all logs
make clean         # Clean Docker resources

开发工作流程

1. 启动开发环境

   make dev

1. 进行代码更改

- 代码更改会自动重新加载 - 访问日志： make dev-logs

1. 运行测试

   make test

1. 检查健康状况

   make health

1. 停止环境

   make dev-stop

添加新功能

1. 创建特征分支

   git checkout -b feature/new-feature

1. 开发和测试

   make dev
   # Make changes
   make test
   make health

1. 更新文档

- 更新API文档 - 添加配置选项 - 必要时更新README

🚀 部署

生产部署检查表

• \[\]更新 DOMAIN_NAME 在……里面 .env.production
• \[\]在中生成强烈的秘密 secrets/ 目录
• \[\]配置SSL证书（Let's Encrypt）
• \[\]设置监控和警报
• \[\]配置备份过程
• \[\]检查安全设置
• \[\]在暂存环境中进行测试部署

部署程序

1. 预部署

   # Backup current system
   make backup

   # Validate configuration
   make validate

1. 部署

   # Zero-downtime deployment
   make deploy-prod

1. 部署后

   # Verify deployment
   make health-prod

   # Monitor logs
   make prod-logs

回滚程序

如果部署失败：

# Automatic rollback during deployment failure
# Or manual rollback:
./scripts/rollback.sh

📊 监控

健康检查

# Check all services
make health

# Check production
make health-prod

# Service status
make status

度量和监控

• 普罗米修斯指标: http://localhost:9090 （如果启用）
• Grafana仪表板: http://localhost:3000 （如果启用）
• Nginx状态: http://localhost/nginx-status
• 应用程序指标: http://localhost/metrics

日志管理

# View all logs
make logs

# Follow logs
make logs-follow

# Service-specific logs
make logs-service SERVICE=nginx-proxy

🔧 故障排除

常见问题

服务无法启动

# Check Docker daemon
docker info

# Check compose file
make validate

# View error logs
make logs

内存使用率高

# Check resource usage
make status

# Monitor containers
docker stats

SSL证书问题

# Regenerate development certificates
rm -rf docker/nginx/ssl/*
make setup-dev

# For production, check Let's Encrypt
docker compose -f docker compose.prod.yaml logs nginx-proxy

Redis连接问题

# Check Redis health
make redis-info

# Access Redis CLI
make redis-cli

调试模式

启用开发调试模式：

# In .env file
DSL_PNG_DEBUG=true
DSL_PNG_LOG_LEVEL=DEBUG

性能问题

1. 检查资源使用情况

   docker stats

1. 规模服务

   docker compose up -d --scale celery-worker=6

1. 监控瓶颈

   make health

🤝 贡献

开发设置

1. 分叉存储库
2. 创建特征分支
3. 设置开发环境： make setup-dev
4. 进行更改和测试： make test
5. 提交拉取请求

代码的风格

• Python代码遵循PEP 8
• 使用类型提示
• 为函数添加文档字符串
• 为新功能编写测试

提交变化

1. 测试您的更改

   make test
   make health

1. 更新文档

- API文档 - 配置更改 - README更新

1. 创建pull请求

- 清晰的描述 - 问题链接 - 包括测试结果

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

• 文档：参见 docs/ 目录
• 问题：GitHub问题
• 讨论：GitHub讨论

🔗 链接

• 模型上下文协议
• FastAPI文档
• 剧作家文档
• Nginx文档

______________________________________________________________________

由以下材料制成❤️ 对于MCP社区