Agentic Mermaid

Por qué Agentic Mermaid

Úsalo cuando quieras describir un diagrama en lenguaje natural y obtener algo que puedas publicar sin una pasada de limpieza de diseño.

Quieres	Agentic Mermaid te da
Un agente que redacte el diagrama	Código fuente Mermaid más una ruta de renderizado verificada
Valores predeterminados hermosos	Aspectos integrados como watercolor, blueprint, hand-drawn y publication-figure
Ajuste a la marca	Pilas de Estilo + Paleta y paletas JSON personalizadas que puedes mantener en tu repositorio
Ediciones seguras más tarde	parseRegisteredMermaid → familia más estrecha → mutate → verifyMermaid → serializeMermaid
Artefactos revisables	SVG, PNG, ASCII, Unicode y diseño JSON desde la misma fuente

El flujo de trabajo del agente es la salvaguarda detrás del pulido: los agentes no deben adivinar a partir de píxeles, concatenar cadenas o regenerar diagramas completos cuando hay una edición estructurada disponible.

Destacados

• Familias de diagramas registradas por descriptor — los integrados y las extensiones con espacio de nombres comparten un contrato único de descubrimiento y capacidad.
• SVG, PNG, ASCII, Unicode, JSON — una solicitud resuelta con proyecciones explícitas gráficas, de terminal y de diseño posicionado.
• Renderizador SVG síncrono, sin DOM — sin Puppeteer, sin parpadeo del navegador.
• Estilos componibles — { style: ['hand-drawn', 'dracula'] } apila un aspecto sobre una paleta; los aspectos completos descubribles cubren boceto, acuarela, plano, accesibilidad, impresión, operativo, medios físicos, arquitectura y casos de uso editorial/informe. Los estilos personalizados son registros JSON simples que cualquier agente puede crear (docs/style-authoring.md). seed vuelve a lanzar la tinta, nunca el diseño.
• Paletas descubribles + compatibilidad con Shiki — un tema es un estilo solo de paleta: descubre el catálogo canónico en tiempo de ejecución, crea temas desde dos colores o adapta un tema de VS Code.
• Edición nativa para agentes — mutación tipada para cada familia renderizable registrada; ida y vuelta a nivel de fuente solo para respaldos opacos que contienen sintaxis no modelada.
• CLI + MCP + biblioteca — am, agentic-mermaid-mcp, agentic-mermaid, agentic-mermaid/agent y el agentic-mermaid/agent/core seguro para navegador/workerd. Los informes de auditoría y los ayudantes de recursos de host confiables siguen siendo herramientas de repositorio en lugar de puntos de entrada de tiempo de ejecución publicados.

Instalación

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 el desarrollo del repositorio, instala desde la fuente y ejecuta los puntos de entrada de Bun (Bun 1.4.0 o posterior; bun upgrade si bun --version es más antiguo):

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

Solo ESM. agentic-mermaid incluye módulos ES (no hay compilación CommonJS); los consumidores de require() deben usar import() dinámico en su lugar. Requiere Node ≥ 22.

Los ejemplos de am … a continuación nombran el binario publicado. Después de una instalación local de npm en el proyecto, invócalo desde un shell como npx --no-install agentic-mermaid … (o desde un script npm como am …). Desde un checkout de la fuente, usa bun run bin/am.ts … en su lugar.

Inicios rápidos de salida

Usa agentic-mermaid/agent cuando quieras una ruta de importación para renders con estilo, formatos de salida y la API de edición estructurada.

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 en 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 })

Inicio rápido para agentes

Si tu agente de codificación puede leer archivos del repositorio, apúntalo a:

• skills/agentic-mermaid-diagram-workflow/SKILL.md para la creación/edición de diagramas.
• skills/agentic-mermaid-live-editor/SKILL.md para cambios en el editor.

Si solo tiene acceso a 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

Indicación de instalación cero para un agente de codificación: lee https://agentic-mermaid.dev/llms.txt y sigue el flujo de trabajo analizar → estrechar → mutar → verificar → serializar. Para conectar Agentic Mermaid a otro repositorio, ejecuta npx agentic-mermaid init-agent (o bun run bin/am.ts init-agent desde un checkout de la fuente); escribe una sección AGENTS.md que no sobrescribe, un bundle raíz skills/ y una muestra .mcp.json.

Usa preview estricto para inspección humana y mutate --op/--ops para ediciones verificadas de una sola vez o por lotes.

Para ediciones MCP de varios pasos, conecta agentic-mermaid-mcp y usa el Modo Código execute(code) con los mismos nombres de SDK de mermaid.*. Stdio es el transporte predeterminado; agentic-mermaid-mcp --transport http inicia HTTP/SSE y artefactos administrados de archivos/URL PNG. Consulta el recetario de API para agentes para recetas de biblioteca, CLI y MCP copiables y pegables.

Servidor MCP

Agentic Mermaid incluye un servidor de Protocolo de Contexto de Modelo para que los agentes compatibles con MCP puedan renderizar y editar diagramas de forma segura sin recurrir a shell.

• Autohospedado (predeterminado). agentic-mermaid-mcp ejecuta un servidor stdio que expone execute (sandbox de Modo Código), describe_sdk (el esquema de mutación de una familia bajo demanda), render_png y describe. Los ejecutores de paquetes pueden usar npx -y agentic-mermaid mcp; el argumento mcp enruta el binario del nombre del paquete al mismo servidor stdio. Agrega --transport http para HTTP/SSE con artefactos administrados de archivos/URL PNG. Consulta docs/mcp-http-transport.md y docs/mcp-code-mode-rationale.md.
• Hospedado. Un endpoint HTTP Streamable sin estado está disponible en https://agentic-mermaid.dev/mcp (herramientas: execute, describe_sdk, render_svg, render_ascii, render_png, verify, describe, mutate y build; límites de entrada de 64 KB). Llama a describe_sdk para firmas compactas o campos exactos antes de crear operaciones desconocidas. Es solo MCP JSON-RPC, no una API de render REST. El execute hospedado ejecuta la misma fachada mermaid.* en un aislado de Cloudflare Dynamic Worker sin red; el PNG hospedado devuelve solo base64.

La postura local primero es la predeterminada: prefiere la biblioteca, la CLI o un MCP autohospedado para cualquier cosa sensible, sin conexión, más grande que los límites hospedados o que necesite artefactos locales de archivos/URL PNG. El endpoint hospedado es una conveniencia pública sin autenticación para render/verificar/describir sin instalación y ediciones estructuradas acotadas.

Los mantenedores de directorios pueden usar el registro de listado MCP canónico. El manejo de datos hospedados se describe en el aviso de privacidad de MCP.

Ejemplo de edición estructurada

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)

Reglas:

• Usa el as<Family> exportado correspondiente antes de mutar un diagrama estructurado existente.
• Las operaciones de mutación usan kind, no type.
• Ejecuta verifyMermaid antes de cada punto de confirmación.
• No llames a mutate en cuerpos de respaldo opacos; el estrechador devuelve null para sintaxis no modelada.

Familias de diagramas compatibles

El soporte de familias se proyecta desde el registro FamilyDescriptor; ejecuta am capabilities --json para la lista en vivo. (El informe de capacidades de la Sección A ya no se publica). Consulta familias de diagramas para ejemplos de sintaxis y notas de compatibilidad.

Más documentación

• Arquitectura del sistema — comienza aquí para la descripción general de solicitud resuelta renderizada, descriptor de familia, artefacto posicionado y seguridad de salida (dogfooded, a prueba de deriva).
• Referencia de API — renderizadores, API de agentes, opciones, punteros CLI/MCP.
• Recetario de API para agentes — recetas prácticas para agentes.
• Temas — temas de dos colores, integrados, compatibilidad con Shiki.
• Recetario de estilos personalizados — archivos de estilo JSON, capturas de pantalla, uso de esquemas y comandos CLI.
• Fuentes en estilos personalizados — selección de fuentes, declaraciones SVG, directorios PNG, respaldos y uso en navegador.
• Integración con React — renderizado seguro para navegador, con carga de familias.
• Salida ASCII — salida de terminal, modos de color, gráficos XY.
• Configuración de Mermaid — frontmatter, directivas init, configuración en tiempo de ejecución.
• Características, calidad, seguridad, diferencias del fork.
• Agregar tipos de diagramas para colaboradores.

Editor en vivo y ejemplos

• Ejemplos — familias compatibles, combinaciones de Estilo + Paleta y el corpus rico de ejemplos compartidos.
• Editor en vivo — exportaciones SVG/PNG y uso compartido de URL.
• examples/agent-loop.ts
• examples/mcp-vs-cli-complex-diagrams.ts
• examples/agent-improve-auth-flow.ts

Atribución

Agentic Mermaid es un fork de Beautiful Mermaid por Luki Labs. El motor de renderizado ASCII se basa en mermaid-ascii por Alexander Grooff y se extendió para Agentic Mermaid.

Licencia

MIT