Agentic Mermaid

Agentic Mermaid を選ぶ理由

図を平易な言葉で説明するだけで、デザインの仕上げ作業なしに公開できるものを作りたいときにお使いください。

欲しいもの	Agentic Mermaid が提供するもの
エージェントによる図の下書き	Mermaid ソースと検証済みのレンダリングパス
美しいデフォルト設定	watercolor、blueprint、hand-drawn、publication-figure などの組み込みスタイル
ブランドへの適合	Style + Palette の組み合わせと、リポジトリに保存できるカスタム JSON パレット
後から安全に編集	parseRegisteredMermaid → family narrower → mutate → verifyMermaid → serializeMermaid
レビュー可能な成果物	同じソースから生成される SVG、PNG、ASCII、Unicode、JSON レイアウト

エージェントのワークフローは、洗練された仕上がりを実現するためのガードレールです。構造化された編集が可能な場合、エージェントはピクセルから推測したり、文字列を連結したり、図全体を再生成したりするべきではありません。

主な特徴

• ディスクリプター登録型の図のファミリー — 組み込み機能と名前空間付き拡張機能で、同じ探索および機能契約を共有します。
• SVG、PNG、ASCII、Unicode、JSON — 明示的なグラフィカル、ターミナル、位置指定レイアウトの各投影を備えた、単一の解決済みリクエストです。
• 同期型、ゼロ DOM の SVG レンダラー — Puppeteer 不要で、ブラウザー表示時のちらつきもありません。
• 組み合わせ可能なスタイル — { style: ['hand-drawn', 'dracula'] } のように、パレットの上に見た目を重ねられます。スケッチ、水彩、設計図、アクセシビリティ、印刷、運用、物理メディア、アーキテクチャ、編集・レポート用途を網羅した、探索可能なフルスタイルを用意しています。カスタムスタイルは、どのエージェントでも作成できる通常の JSON レコードです（docs/style-authoring.md）。seed はインクを再生成しますが、レイアウトは変更しません。
• 探索可能なパレットと Shiki 互換性 — テーマはパレットのみのスタイルです。実行時に正規カタログを探索したり、2 色からテーマを作成したり、VS Code のテーマを変換したりできます。
• エージェントに適した編集機能 — 登録済みのすべてのレンダリング可能なファミリーで型付きミューテーションに対応し、モデル化されていない構文を含む不透明なフォールバックに限り、ソースレベルでのラウンドトリップを行います。
• CLI + MCP + ライブラリ — am、agentic-mermaid-mcp、agentic-mermaid、agentic-mermaid/agent、およびブラウザー／workerd 対応の agentic-mermaid/agent/core を提供します。監査レポートと信頼できるホストリソースのヘルパーは、公開ランタイムのエントリーポイントではなく、リポジトリ内のツールとして提供されます。

インストール

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

リポジトリの開発では、ソースからインストールし、Bun のエントリーポイントを実行してください （Bun 1.4.0 以降が必要です。bun --version が古い場合は bun upgrade を実行してください）。

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

ESM 専用です。 agentic-mermaid は ES モジュールを提供します（CommonJS ビルドはありません）。 require() を使う場合は、代わりに動的な import() を使用してください。Node ≥ 22 が必要です。

以下の am … の例は、公開済みの bin を指しています。プロジェクトローカルに npm でインストールした後は、シェルから npx --no-install agentic-mermaid …（または npm スクリプトから am …）を実行してください。ソースをチェックアウトした場合は、 代わりに bun run bin/am.ts … を使用してください。

出力のクイックスタート

スタイル付きレンダリング、出力形式、構造化編集 API を一つのインポートパスで利用するには、agentic-mermaid/agent を使用してください。

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)

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

エージェントのクイックスタート

コーディングエージェントがリポジトリ内のファイルを読み取れる場合は、次を参照させてください。

• 図の作成・編集については skills/agentic-mermaid-diagram-workflow/SKILL.md。
• エディターの変更については skills/agentic-mermaid-live-editor/SKILL.md。

シェルアクセスしかない場合：

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

コーディングエージェント向けのゼロインストールプロンプト：https://agentic-mermaid.dev/llms.txt を読み、parse → narrow → mutate → verify → serialize のワークフローに従ってください。Agentic Mermaid を別のリポジトリに組み込むには、npx agentic-mermaid init-agent（ソースをチェックアウトした場合は bun run bin/am.ts init-agent）を実行してください。これにより、既存の内容を上書きしない AGENTS.md セクション、ルートの skills/ バンドル、および .mcp.json のサンプルが書き込まれます。

人が確認する場合は厳密な preview を使用し、検証済みの単発またはバッチ編集には mutate --op/--ops を使用してください。

複数ステップの MCP 編集では、agentic-mermaid-mcp に接続し、同じ mermaid.* SDK 名を使用する Code Mode の execute(code) を使ってください。デフォルトのトランスポートは Stdio です。agentic-mermaid-mcp --transport http を実行すると、HTTP/SSE と、管理対象の PNG ファイル／URL アーティファクトが有効になります。コピーして使用できるライブラリ、CLI、MCP のレシピについては、エージェント API クックブックを参照してください。

MCP サーバー

Agentic Mermaid には Model Context Protocol サーバーが付属しており、MCP 対応エージェントがシェルコマンドを実行せずに図をレンダリングし、安全に編集できます。

• セルフホスト可能（デフォルト）。 agentic-mermaid-mcp は、execute（Code Mode サンドボックス）、describe_sdk（必要に応じて、指定されたファミリーの変更スキーマを取得）、render_png、describe、mutate、build を公開する Stdio サーバーを実行します。宣言的な編集を優先し、カスタムロジックには execute を使用してください。パッケージランナーでは npx -y agentic-mermaid mcp を使用できます。mcp 引数を指定すると、パッケージ名のバイナリから同じ Stdio サーバーが起動します。HTTP/SSE と、管理対象の PNG ファイル／URL アーティファクトを有効にするには --transport http を追加してください。docs/mcp-http-transport.md と docs/mcp-code-mode-rationale.md を参照してください。
• ホスト型。 ステートレスな Streamable HTTP エンドポイントを https://agentic-mermaid.dev/mcp で利用できます（ツール：execute、describe_sdk、render_svg、render_ascii、render_png、verify、describe、mutate、build。入力上限は 64 KB）。使い慣れていない ops を作成する前に、簡潔なシグネチャや正確なフィールドを確認するには describe_sdk を呼び出してください。これは MCP JSON-RPC 専用であり、REST レンダリング API ではありません。ホスト型の execute は、Cloudflare Dynamic Worker の分離環境内で、ネットワークアクセスなしに同じ mermaid.* ファサードを実行します。ホスト型の PNG は base64 のみを返します。

デフォルトではローカル優先です。機密情報を扱う場合、オフラインでの利用、ホスト型の上限を超える入力、またはローカル PNG ファイル／URL アーティファクトが必要な場合は、ライブラリ、CLI、またはセルフホスト型 MCP を優先してください。ホスト型エンドポイントは、インストール不要でレンダリング、検証、説明、および上限付きの構造化編集を行うための、認証不要の公開サービスです。

ディレクトリのメンテナーは、標準の MCP 掲載レコードを利用できます。ホスト型サービスにおけるデータの取り扱いについては、MCP プライバシー通知に記載されています。

構造化編集の例

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)

ルール：

• 既存の構造化ダイアグラムを変更する前に、対応するエクスポート済みの as<Family> ナローアーを使用してください。
• 変更操作では type ではなく kind を使用してください。
• コミットする前に、必ず verifyMermaid を実行してください。
• 不透明なフォールバック本文に対して mutate を呼び出さないでください。ナローアーはモデル化されていない構文に対して null を返します。

サポートされているダイアグラムファミリー

ファミリーのサポート状況は FamilyDescriptor レジストリから反映されます。最新の一覧を確認するには、 am capabilities --json を実行してください。（Section A の機能レポートは 現在公開されていません。）構文例と互換性に関する注意事項は、ダイアグラムファミリーを参照してください。

その他のドキュメント

• システムアーキテクチャ — レンダリング済みの解決済みリクエスト、ファミリーディスクリプター、位置指定済みアーティファクト、出力セキュリティの概要については、まずこちらをお読みください（実プロジェクトで使用し、設計との乖離を防止）。
• API リファレンス — レンダラー、エージェント API、オプション、CLI/MCP 関連情報。
• 用語集 — ファミリー、ソースオブジェクト、Scene パーツ、解決済みプリミティブ、型付きファミリーのナローイング。
• エージェント API クックブック — エージェント向けの実用的なレシピ。
• テーマ設定 — 2 色テーマ、組み込みテーマ、Shiki 互換性。
• カスタムスタイルのクックブック — JSON スタイルファイル、スクリーンショット、スキーマの使用方法、CLI コマンド。
• カスタムスタイルのフォント — フォント選択、SVG 宣言、PNG ディレクトリ、フォールバック、ブラウザーでの使用方法。
• React との統合 — ブラウザーセーフで、ファミリーの読み込みに対応したレンダリング。
• ASCII 出力 — ターミナル出力、カラー モード、XY チャート。
• Mermaid 設定 — フロントマター、init ディレクティブ、実行時設定。
• 機能、品質、セキュリティ、フォーク版との違い。
• コントリビューター向けのダイアグラムの種類の追加方法。

ライブエディターと例

• 例 — サポート対象のファミリー、Style + Palette の組み合わせ、充実した共有サンプル集。
• ライブエディター — SVG/PNG のエクスポートと URL 共有。
• examples/agent-loop.ts
• examples/mcp-vs-cli-complex-diagrams.ts
• examples/agent-improve-auth-flow.ts

クレジット

Agentic Mermaid は、Luki Labs の Beautiful Mermaid をフォークしたものです。ASCII レンダリングエンジンは、Alexander Grooff が開発した mermaid-ascii を基盤とし、Agentic Mermaid 向けに拡張しています。

ライセンス

MIT

ネイティブの Event Modeling と ZenUML の作成およびレンダリングについては、機能と実行時の契約が文書化されています。