Servidor MCP de sirena

Un servidor de Protocolo de Contexto de Modelo (MCP) que convierte diagramas de Mermaid en imágenes PNG. Este servidor permite a los asistentes de IA y otras aplicaciones generar diagramas visuales a partir de descripciones textuales utilizando la sintaxis markdown de Mermaid.

Características

• Convierte el código del diagrama de sirena en imágenes PNG.

• Admite múltiples temas de diagrama (predeterminado, bosque, oscuro, neutral)

• Colores de fondo personalizables

• Utiliza Puppeteer para la representación de navegadores sin interfaz gráfica de alta calidad

• Implementa el protocolo MCP para una integración perfecta con asistentes de IA

• Opciones de salida flexibles: devuelve imágenes directamente o guárdalas en el disco

• Manejo de errores con mensajes de error detallados

Related MCP server: Mermaid MCP Server

Cómo funciona

El servidor usa Puppeteer para iniciar un navegador sin interfaz gráfica, renderizar el diagrama de la Sirena a SVG y capturar una captura de pantalla del diagrama renderizado. El proceso implica:

1. Lanzar una instancia de navegador sin cabeza

2. Creando una plantilla HTML con el código Mermaid

3. Cargando la biblioteca Mermaid.js

4. Representación del diagrama en formato SVG

5. Tomar una captura de pantalla del SVG renderizado como PNG

6. Devolviendo la imagen directamente o guardándola en el disco

Construir

npx tsc

Uso

Usar con el escritorio de Claude

"mcpServers": {
  "mermaid": {
    "command": "npx",
    "args": [
      npx @peng-shawn/mermaid-mcp-server
    ]
  }
}

Usar con Cursor y Cline

env CONTENT_IMAGE_SUPPORTED=false npx @peng-shawn/mermaid-mcp-server

Puede encontrar una lista de diagramas de sirena en ./diagrams . Se crean utilizando el agente Cursor con el mensaje: "Genere diagramas de sirena y guárdelos en una carpeta de diagramas separada, explicando cómo funciona renderMermaidPng".

Correr con el inspector

Ejecute el servidor con el inspector para realizar pruebas y depuraciones:

npx @modelcontextprotocol/inspector node dist/index.js

El servidor se iniciará y escuchará en stdio los mensajes del protocolo MCP.

Obtenga más información sobre el inspector aquí .

Instalación mediante herrería

Para instalar Mermaid Diagram Generator para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

Entornos Docker y Smithery

Al ejecutar en contenedores Docker (incluso a través de Smithery), es posible que deba gestionar dependencias de Chrome:

1. El servidor ahora intenta utilizar el navegador incluido de Puppeteer de forma predeterminada

2. Si encuentra errores relacionados con el navegador, tiene dos opciones:

   Opción 1: Durante la compilación de la imagen de Docker:

   • Establezca PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true al instalar Puppeteer

   • Instalar Chrome/Chromium en tu contenedor Docker

   • Establezca PUPPETEER_EXECUTABLE_PATH en tiempo de ejecución para que apunte a la instalación de Chrome

   Opción 2: Utilizar el Chrome incluido de Puppeteer:

   • Asegúrese de que su contenedor Docker tenga las dependencias necesarias para Chrome

   • No es necesario configurar PUPPETEER_SKIP_CHROMIUM_DOWNLOAD

   • El código utilizará automáticamente el navegador incluido.

Para los usuarios de Smithery, la última versión debería funcionar sin configuración adicional.

API

El servidor expone una única herramienta:

• generate : convierte el código del diagrama de sirena en una imagen PNG

  • Parámetros:

    • code : El código del diagrama de la sirena para renderizar

    • theme : (opcional) Tema para el diagrama. Opciones: "predeterminado", "bosque", "oscuro", "neutro".

    • backgroundColor : (opcional) Color de fondo para el diagrama, por ejemplo, 'blanco', 'transparente', '#F0F0F0'

    • name : Nombre del archivo generado (obligatorio cuando CONTENT_IMAGE_SUPPORTED=false)

    • folder : ruta absoluta donde guardar la imagen (obligatorio cuando CONTENT_IMAGE_SUPPORTED=false)

El comportamiento de la herramienta generate depende de la variable de entorno CONTENT_IMAGE_SUPPORTED :

• Cuando CONTENT_IMAGE_SUPPORTED=true (predeterminado): La herramienta devuelve la imagen directamente en la respuesta

• Cuando CONTENT_IMAGE_SUPPORTED=false : La herramienta guarda la imagen en la carpeta especificada y devuelve la ruta del archivo

Variables de entorno

• CONTENT_IMAGE_SUPPORTED : Controla si las imágenes se devuelven directamente en la respuesta o se guardan en el disco

  • true (predeterminado): las imágenes se devuelven directamente en la respuesta

  • false : las imágenes se guardan en el disco, lo que requiere parámetros name y folder

Ejemplos

Uso básico

// Generate a flowchart with default settings
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

Con tema y color de fondo

// Generate a sequence diagram with forest theme and light gray background
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

Guardar en el disco (cuando CONTENT_IMAGE_SUPPORTED=false)

// Generate a class diagram and save it to disk
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

Preguntas frecuentes

¿El escritorio de Claude ya no admite la sirena a través del lienzo?

Sí, pero no es compatible con las opciones de theme y backgroundColor . Además, tener un servidor dedicado facilita la creación de diagramas de sirena con diferentes clientes MCP.

¿Por qué necesito especificar CONTENT_IMAGE_SUPPORTED=false cuando lo uso con Cursor?

Cursor aún no admite imágenes en línea en las respuestas.

Publicación

Este proyecto utiliza GitHub Actions para automatizar el proceso de publicación en npm.

Método 1: Usar el script de lanzamiento (recomendado)

1. Asegúrese de que todos sus cambios estén confirmados y enviados

2. Ejecute el script de lanzamiento con un número de versión específico o un incremento de versión semántico:

   # Using a specific version number
   npm run release 0.1.4
   
   # Using semantic version increments
   npm run release patch  # Increments the patch version (e.g., 0.1.3 → 0.1.4)
   npm run release minor  # Increments the minor version (e.g., 0.1.3 → 0.2.0)
   npm run release major  # Increments the major version (e.g., 0.1.3 → 1.0.0)

3. El guión hará lo siguiente:

   • Validar el formato de la versión o el incremento semántico

   • Comprueba si estás en la rama principal

   • Detectar y advertir sobre desajustes de versiones entre archivos

   • Actualice todas las referencias de versión de manera consistente (package.json, package-lock.json e index.ts)

   • Crear una única confirmación con todos los cambios de versión

   • Crear y enviar una etiqueta git

   • Luego, el flujo de trabajo de GitHub se compilará y publicará automáticamente en npm.

Método 2: Proceso manual

1. Actualice su código y confirme los cambios

2. Crea y envía una nueva etiqueta con el número de versión:

   git tag v0.1.4  # Use the appropriate version number
   git push origin v0.1.4

3. El flujo de trabajo de GitHub realizará automáticamente lo siguiente:

   • Construir el proyecto

   • Publicar en npm con la versión de la etiqueta

Nota: Debes configurar el secreto NPM_TOKEN en la configuración de tu repositorio de GitHub. Para ello:

1. Generar un token de acceso npm con permisos de publicación

2. Vaya a su repositorio de GitHub → Configuración → Secretos y variables → Acciones

3. Cree un nuevo secreto de repositorio llamado NPM_TOKEN con su token npm como valor

Insignias

Licencia

Instituto Tecnológico de Massachusetts (MIT)