d2-mcp

d2-mcp

Un servidor de Model Context Protocol (MCP) para trabajar con D2: Diagramación Declarativa, que permite la integración fluida de la creación y validación de diagramas en tu flujo de trabajo de desarrollo.

Herramientas:

• Compilar código D2
  • Valida la sintaxis de D2 y detecta errores antes de renderizar
  • Obtén retroalimentación inmediata sobre la estructura y sintaxis del diagrama
  • Acepta código directo o una ruta de archivo al archivo D2
• Renderizar diagramas
  • Genera diagramas para retroalimentación visual y refinamiento
  • Soporta formatos de salida PNG, SVG y ASCII
  • Acepta código directo o una ruta de archivo al archivo D2
• Obtener la hoja de referencia de D2
  • Devuelve una referencia en Markdown que cubre formas, estilos y uso de transporte

Instalación

Opción 1: Instalar la versión binaria

Option 2: Install via go

go install github.com/h0rv/d2-mcp@latest

Opción 3: Compilar localmente

git clone https://github.com/h0rv/d2-mcp.git
cd d2-mcp
go build .

Opción 4: Compilar la imagen localmente

docker build . -t d2-mcp

# Run in stdio mode (default - for MCP clients)
docker run --rm -i d2-mcp

# Run in stdio mode with filesystem access
docker run --rm -i -v $(pwd):/data d2-mcp

# Run in SSE mode (HTTP server)
docker run --rm -e SSE_MODE=true -p 8080:8080 d2-mcp

# Run in SSE mode with filesystem access
docker run --rm -e SSE_MODE=true -p 8080:8080 -v $(pwd):/data d2-mcp

Opción 5: Ejecutar la imagen del contenedor

# Run in stdio mode (default - for MCP clients)
docker run --rm -i ghcr.io/h0rv/d2-mcp:main

# Run in stdio mode with filesystem access
docker run --rm -i -v $(pwd):/data ghcr.io/h0rv/d2-mcp:main

# Run in SSE mode (HTTP server)
docker run --rm -e SSE_MODE=true -p 8080:8080 ghcr.io/h0rv/d2-mcp:main

# Run in SSE mode with filesystem access
docker run --rm -e SSE_MODE=true -p 8080:8080 -v $(pwd):/data ghcr.io/h0rv/d2-mcp:main

Configuración con el cliente MCP

MacOS:

# Claude Desktop
$EDITOR ~/Library/Application\ Support/Claude/claude_desktop_config.json
# OTerm:
$EDITOR ~/Library/Application\ Support/oterm/config.json

Agrega el servidor MCP d2 a la configuración de tu cliente MCP respectivo:

Usando el binario:

{
    "mcpServers": {
        "d2": {
            "command": "/YOUR/ABSOLUTE/PATH/d2-mcp",
            "args": ["--image-type", "png"]
        }
    }
}

Usando el binario con salida de archivo:

{
    "mcpServers": {
        "d2": {
            "command": "/YOUR/ABSOLUTE/PATH/d2-mcp",
            "args": ["--image-type", "png", "--write-files"]
        }
    }
}

Usando Docker:

{
    "mcpServers": {
        "d2": {
            "command": "docker",
            "args": ["run", "--rm", "-i", "ghcr.io/h0rv/d2-mcp:main", "--image-type", "svg"]
        }
    }
}

Usando Docker con acceso al sistema de archivos:

{
    "mcpServers": {
        "d2": {
            "command": "docker",
            "args": [
                "run", "--rm", "-i",
                "-v", "./:/data",
                "ghcr.io/h0rv/d2-mcp:main",
                "--image-type", "ascii",
                "--ascii-mode", "standard",
                "--write-files"
            ]
        }
    }
}

Formatos de renderizado

El servidor devuelve salida PNG por defecto cuando rsvg-convert de librsvg está disponible. Si falta rsvg-convert, el servidor elimina automáticamente png del enum render-d2 de la herramienta format y recurre a SVG. La imagen de Docker instala librsvg más las fuentes de respaldo fontconfig/DejaVu, por lo que PNG funciona de inmediato allí.

Instala librsvg para binarios locales:

# macOS
brew install librsvg

# Debian/Ubuntu
sudo apt-get install librsvg2-bin

# Alpine
apk add librsvg

Anula globalmente al iniciar el binario:

./d2-mcp --image-type svg        # SVG output
./d2-mcp --image-type ascii      # ASCII output with Unicode box drawing characters
./d2-mcp --image-type ascii --ascii-mode standard  # ASCII output restricted to basic ASCII chars

Dentro de las llamadas a herramientas MCP, pasa el argumento opcional format (png, svg, ascii) y, cuando ascii, el argumento ascii_mode (extended, standard) para cambiar de formato por solicitud.

Ejemplos de uso con Docker

Ejecuta el contenedor con salida PNG predeterminada a través de stdio:

docker run --rm -i ghcr.io/h0rv/d2-mcp:main

Cambia a diagramas ASCII Unicode y captura las respuestas como texto plano:

docker run --rm -i ghcr.io/h0rv/d2-mcp:main --image-type ascii

Usa caracteres ASCII básicos y escribe los archivos renderizados de vuelta en tu árbol de trabajo (requiere un montaje de enlace):

docker run --rm -i \
  -v "$(pwd)":/data \
  ghcr.io/h0rv/d2-mcp:main \
  --image-type ascii \
  --ascii-mode standard \
  --write-files

Expón el servidor SSE en el puerto 8080 mientras emites SVG:

docker run --rm -e SSE_MODE=true -p 8080:8080 ghcr.io/h0rv/d2-mcp:main --image-type svg

Expón el transporte HTTP transmisible (endpoint predeterminado /mcp) para usarlo con clientes MCP que esperan el nuevo protocolo:

docker run --rm -p 8080:8080 ghcr.io/h0rv/d2-mcp:main --transport http --image-type svg

Herramienta de hoja de referencia

Recupera la referencia rápida integrada como Markdown:

{
  "tool": "fetch_d2_cheat_sheet"
}

La hoja de referencia destaca formas comunes, consejos de diseño y patrones compatibles con ASCII, lo que la convierte en material de apoyo ideal para indicaciones de LLM posteriores.

Transportes

El servidor usa por defecto el transporte stdio para clientes MCP impulsados por CLI. Cambia de transporte por ejecución:

• --transport stdio: predeterminado para integraciones CLI locales.
• --transport sse: transporte heredado de Server-Sent Events (alias: --sse).
• --transport http: transporte HTTP transmisible en /mcp; combínalo con -p/--port cuando se ejecute en Docker o contenedores.

Anulaciones de entorno:

• MCP_TRANSPORT establece el transporte (stdio, sse, http) cuando no se proporcionan banderas.
• PORT (o el heredado SSE_PORT) establece el puerto de escucha para los transportes SSE/HTTP.
• SSE_MODE=true mantiene la compatibilidad hacia atrás al seleccionar el transporte SSE.

Referencia de herramientas

Herramienta	Descripción	Argumentos clave
compile-d2	Valida el código fuente de D2 y muestra errores de sintaxis.	code (cadena) o file_path (cadena)
render-d2	Renderiza diagramas a PNG, SVG o ASCII (ASCII es amigable para LLM).	code/file_path, format (png, svg, ascii), ascii_mode (extended, standard)
fetch_d2_cheat_sheet	Devuelve una hoja de referencia en Markdown con ejemplos y mejores prácticas.	Ninguno

Consejo: Ejecuta compile-d2 primero para validar, luego llama a render-d2 con la misma carga útil para la salida final.

Desarrollo

Depuración

npx @modelcontextprotocol/inspector /YOUR/ABSOLUTE/PATH/d2-mcp/d2-mcp