Agentic Mermaid

Por que Agentic Mermaid

Use quando quiser descrever um diagrama em linguagem simples e obter algo que você possa publicar sem uma etapa de limpeza de design.

Você quer	Agentic Mermaid oferece
Um agente para rascunhar o diagrama	Fonte Mermaid mais um caminho de renderização verificado
Padrões bonitos	Visualizações integradas como watercolor, blueprint, hand-drawn e publication-figure
Adequação à marca	Pilhas de Style + Palette e paletas JSON personalizadas que você pode manter no seu repositório
Edições seguras depois	parseRegisteredMermaid → família mais restrita → mutate → verifyMermaid → serializeMermaid
Artefatos revisáveis	SVG, PNG, ASCII, Unicode e layout JSON da mesma fonte

O fluxo de trabalho do agente é a proteção por trás do polimento: agentes não devem adivinhar a partir de pixels, concatenar strings ou regenerar diagramas inteiros quando uma edição estruturada está disponível.

Destaques

• Famílias de diagramas registradas por descritor — embutidas e extensões com namespace compartilham um contrato único de descoberta e capacidade.
• SVG, PNG, ASCII, Unicode, JSON — uma solicitação resolvida com projeções gráficas, de terminal e de layout posicionado explícitas.
• Renderizador SVG síncrono, sem DOM — sem Puppeteer, sem flash de navegador.
• Estilos compostos — { style: ['hand-drawn', 'dracula'] } empilha uma aparência sobre uma paleta; aparências completas descobríveis cobrem esboço, aquarela, planta baixa, acessibilidade, impressão, operacional, mídia física, arquitetura e casos de uso editorial/relatório. Estilos personalizados são registros JSON simples que qualquer agente pode criar (docs/style-authoring.md). seed re-rola a tinta, nunca o layout.
• Paletas descobríveis + compatibilidade com Shiki — um tema é um estilo somente de paleta: descubra o catálogo canônico em tempo de execução, crie temas a partir de duas cores ou adapte um tema do VS Code.
• Edição nativa para agentes — mutação tipada para cada família renderizável registrada; round-trip no nível da fonte apenas para fallbacks opacos contendo sintaxe não modelada.
• CLI + MCP + biblioteca — am, agentic-mermaid-mcp, agentic-mermaid, agentic-mermaid/agent e o agentic-mermaid/agent/core seguro para navegador/workerd. Relatórios de auditoria e auxiliares de recursos de host confiáveis permanecem como ferramentas de repositório em vez de pontos de entrada de runtime publicados.

Instalação

npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaid
npx --no-install agentic-mermaid --help
npx --no-install agentic-mermaid mcp

Para desenvolvimento no repositório, instale a partir da fonte e execute os entrypoints Bun:

git clone https://github.com/adewale/agentic-mermaid
cd agentic-mermaid
bun install
bun run build
bun run bin/am.ts --help
bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server

Somente ESM. agentic-mermaid envia módulos ES (não há build CommonJS); consumidores require() devem usar import() dinâmico. Requer Node ≥ 22.

Os exemplos am … abaixo nomeiam o bin publicado. Após uma instalação npm local do projeto, invoque-o a partir de um shell como npx --no-install agentic-mermaid … (ou de um script npm como am …). A partir de um checkout da fonte, use bun run bin/am.ts ….

Inícios rápidos de saída

Use agentic-mermaid/agent quando quiser um único caminho de importação para renderizações estilizadas, formatos de saída e a API de edição estruturada.

SVG

import { renderMermaidSVG } from 'agentic-mermaid/agent'

const svg = renderMermaidSVG(`flowchart TD
  Start --> Done`, { security: 'strict' })

PNG

import { writeFileSync } from 'node:fs'
import { renderMermaidPNG } from 'agentic-mermaid/agent'

const png = renderMermaidPNG(`flowchart TD
  Start --> Done`, {
  fitTo: { width: 1200 },
  background: '#fff',
})

writeFileSync('diagram.png', png)

Equivalente CLI:

am render diagram.mmd --format png --output diagram.png

ASCII / Unicode

import { renderMermaidASCII } from 'agentic-mermaid/agent'

const unicode = renderMermaidASCII(`flowchart LR
  A --> B`)
const ascii = renderMermaidASCII(`flowchart LR
  A --> B`, { useAscii: true })

Início rápido do agente

Se seu agente de codificação pode ler arquivos do repositório, aponte-o para:

• skills/agentic-mermaid-diagram-workflow/SKILL.md para criação/edição de diagramas.
• skills/agentic-mermaid-live-editor/SKILL.md para mudanças no editor.

Se ele tiver apenas acesso ao shell:

am --agent-instructions
am capabilities --json
am preview diagram.mmd --security strict --open
am mutate diagram.mmd --op '{"kind":"add_node","id":"Cache","label":"Cache"}' --json

Prompt de instalação zero para um agente de codificação: leia https://agentic-mermaid.dev/llms.txt e siga o fluxo de trabalho parse → narrow → mutate → verify → serialize. Para conectar Agentic Mermaid a outro repositório, execute npx agentic-mermaid init-agent (ou bun run bin/am.ts init-agent a partir de um checkout da fonte); ele escreve uma seção AGENTS.md não sobrescrevente, bundle skills/ raiz e amostra .mcp.json.

Use preview estrito para inspeção humana e mutate --op/--ops para edições verificadas de uma vez ou em lote.

Para edições MCP de várias etapas, conecte agentic-mermaid-mcp e use Code Mode execute(code) com os mesmos nomes do SDK mermaid.*. Stdio é o transporte padrão; agentic-mermaid-mcp --transport http inicia HTTP/SSE e artefatos gerenciados de PNG file/URL. Veja o livro de receitas da API do agente para receitas copiáveis de biblioteca, CLI e MCP.

Servidor MCP

Agentic Mermaid inclui um servidor Model Context Protocol para que agentes capazes de MCP possam renderizar e editar diagramas com segurança sem chamar o shell.

• Auto-hospedado (padrão). agentic-mermaid-mcp executa um servidor stdio expondo execute (sandbox Code Mode), describe_sdk (esquema de mutação de uma família sob demanda), render_png e describe. Executores de pacotes podem usar npx -y agentic-mermaid mcp; o argumento mcp roteia o binário do nome do pacote para o mesmo servidor stdio. Adicione --transport http para HTTP/SSE com artefatos gerenciados de PNG file/URL. Veja docs/mcp-http-transport.md e docs/mcp-code-mode-rationale.md.
• Hospedado. Um endpoint Streamable HTTP sem estado está disponível em https://agentic-mermaid.dev/mcp (ferramentas: execute, describe_sdk, render_svg, render_ascii, render_png, verify, describe, mutate, build; limites de entrada de 64 KB). Chame describe_sdk para assinaturas compactas ou campos exatos antes de criar operações desconhecidas. É somente MCP JSON-RPC, não uma API REST de renderização. execute hospedado executa a mesma fachada mermaid.* em um isolado Cloudflare Dynamic Worker sem rede; PNG hospedado retorna apenas base64.

Local-first é a postura padrão: prefira a biblioteca, CLI ou um MCP auto-hospedado para qualquer coisa sensível, offline, maior que os limites hospedados ou que precise de artefatos locais de PNG file/URL. O endpoint hospedado é uma conveniência pública, sem autenticação, para render/verify/describe de instalação zero e edições estruturadas limitadas.

Mantenedores de diretório podem usar o registro canônico de listagem MCP. O tratamento de dados hospedados é descrito no aviso de privacidade do MCP.

Exemplo de edição estruturada

import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'

const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')
if (!parsed.ok) throw new Error('parse failed')

const flow = asFlowchart(parsed.value)
if (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)

const next = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })
if (!next.ok) throw new Error(next.error.message)

const verify = verifyMermaid(next.value)
if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))

const source = serializeMermaid(next.value)

Regras:

• Use o as<Family> mais restrito exportado correspondente antes de mutar um diagrama estruturado existente.
• Operações de mutação usam kind, não type.
• Execute verifyMermaid antes de cada ponto de commit.
• Não chame mutate em corpos de fallback opacos; o mais restrito retorna null para sintaxe não modelada.

Famílias de diagramas suportadas

O suporte a famílias e suas evidências executáveis são projetados do registro FamilyDescriptor para o relatório de capacidades da Seção A gerado. Veja famílias de diagramas para exemplos de sintaxe e notas de compatibilidade.

Mais documentação

• Arquitetura do sistema — comece aqui para a visão geral renderizada de solicitação resolvida, descritor de família, artefato posicionado e segurança de saída (dogfooded, à prova de drift).
• Referência da API — renderizadores, API do agente, opções, ponteiros CLI/MCP.
• Livro de receitas da API do agente — receitas práticas para agentes.
• Temas — temas de duas cores, embutidos, compatibilidade com Shiki.
• Livro de receitas de estilos personalizados — arquivos de estilo JSON, capturas de tela, uso de schema e comandos CLI.
• Fontes em estilos personalizados — seleção de fontes, declarações SVG, diretórios PNG, fallbacks e uso no navegador.
• Integração com React — renderização useMemo sem flash.
• Saída ASCII — saída de terminal, modos de cor, gráficos XY.
• Configuração do Mermaid — frontmatter, diretivas init, configuração de runtime.
• Recursos, qualidade, segurança, diferenças do fork.
• Adicionando tipos de diagrama para contribuidores.

Editor ao vivo e exemplos

• Exemplos — famílias suportadas, combinações de Style + Palette e o corpus rico de exemplos compartilhados.
• Editor ao vivo — exportações SVG/PNG e compartilhamento por URL.
• examples/agent-loop.ts
• examples/mcp-vs-cli-complex-diagrams.ts
• examples/agent-improve-auth-flow.ts

Atribuição

Agentic Mermaid é um fork de Beautiful Mermaid por Luki Labs. O mecanismo de renderização ASCII é baseado em mermaid-ascii por Alexander Grooff e estendido para Agentic Mermaid.

Licença

MIT