d2-mcp

d2-mcp

Um servidor Model Context Protocol (MCP) para trabalhar com D2: Declarative Diagramming, permitindo integração perfeita da criação e validação de diagramas no seu fluxo de trabalho de desenvolvimento.

Ferramentas:

• Compilar código D2
  • Validar a sintaxe D2 e detectar erros antes da renderização
  • Obter feedback imediato sobre a estrutura e sintaxe do diagrama
  • Aceita código direto ou caminho de arquivo para arquivo D2
• Renderizar diagramas
  • Gerar diagramas para feedback visual e refinamento
  • Suporta formatos de saída PNG, SVG e ASCII
  • Aceita código direto ou caminho de arquivo para arquivo D2
• Buscar folha de referência D2
  • Retorna uma referência em Markdown cobrindo formas, estilos e uso de transporte

Instalação

Opção 1: Instalar versão binária

Option 2: Install via go

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

Opção 3: Compilar localmente

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

Opção 4: Compilar imagem 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

Opção 5: Executar imagem de contêiner

# 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

Configuração com cliente MCP

MacOS:

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

Adicione o servidor MCP d2 à configuração dos seus respectivos clientes MCP:

Usando binário:

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

Usando binário com saída de arquivo:

{
    "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 com acesso ao sistema de arquivos:

{
    "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 renderização

O servidor retorna saída PNG por padrão quando rsvg-convert do librsvg está disponível. Se rsvg-convert estiver ausente, o servidor remove automaticamente png do enum format da ferramenta render-d2 e volta para SVG. A imagem Docker instala librsvg além das fontes de fallback fontconfig/DejaVu, então PNG funciona imediatamente lá.

Instale librsvg para binários locais:

# macOS
brew install librsvg

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

# Alpine
apk add librsvg

Substitua globalmente ao iniciar o binário:

./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

Em chamadas de ferramentas MCP, passe o argumento opcional format (png, svg, ascii) e, quando ascii, o argumento ascii_mode (extended, standard) para alternar formatos por solicitação.

Exemplos de uso com Docker

Execute o contêiner com saída PNG padrão via stdio:

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

Alterne para diagramas ASCII Unicode e capture respostas como texto simples:

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

Use caracteres ASCII básicos e grave os arquivos renderizados de volta na sua árvore de trabalho (requer um bind mount):

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

Exponha o servidor SSE na porta 8080 enquanto emite SVG:

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

Exponha o transporte HTTP transmissível (endpoint padrão /mcp) para uso com clientes MCP que esperam o novo protocolo:

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

Ferramenta de folha de referência

Recupere a referência rápida integrada como Markdown:

{
  "tool": "fetch_d2_cheat_sheet"
}

A folha de referência destaca formas comuns, dicas de layout e padrões compatíveis com ASCII, tornando-a um material de suporte ideal para prompts de LLM a jusante.

Transportes

O servidor usa por padrão o transporte stdio para clientes MCP orientados por CLI. Alterne os transportes por execução:

• --transport stdio: padrão para integrações CLI locais.
• --transport sse: transporte legado Server-Sent Events (alias: --sse).
• --transport http: transporte HTTP transmissível em /mcp; combine com -p/--port ao executar em Docker ou contêineres.

Substituições de ambiente:

• MCP_TRANSPORT define o transporte (stdio, sse, http) quando as flags não são fornecidas.
• PORT (ou o legado SSE_PORT) define a porta de escuta para transportes SSE/HTTP.
• SSE_MODE=true mantém compatibilidade retroativa selecionando o transporte SSE.

Referência de ferramentas

Ferramenta	Descrição	Argumentos-chave
compile-d2	Valida o código-fonte D2 e exibe erros de sintaxe.	code (string) ou file_path (string)
render-d2	Renderiza diagramas em PNG, SVG ou ASCII (ASCII é amigável para LLM).	code/file_path, format (png, svg, ascii), ascii_mode (extended, standard)
fetch_d2_cheat_sheet	Retorna uma folha de referência em Markdown com exemplos e melhores práticas.	Nenhum

Dica: Execute compile-d2 primeiro para validar, depois chame render-d2 com o mesmo payload para a saída final.

Desenvolvimento

Depuração

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