Agentic Mermaid MCP Server

Render a Mermaid source string to text. Returns { ok, text }. useAscii true → plain ASCII (+,-,|); false/absent → Unicode box drawing (┌,─,│). targetWidth sets a hard terminal display-cell bound; impossible bounds return a typed error.

Rasterize a Mermaid source string to PNG. Returns { ok, png_base64 }. Hosted rendering uses resvg-wasm with bundled fonts; bytes may differ from the local napi renderer, so hosted PNG is a convenience surface, not part of the byte-determinism contract. For file/URL artifacts use the local stdio server.

Render a Mermaid source string to themeable SVG. Returns { ok, svg }. Layout is deterministic: identical input produces identical geometry. The hosted boundary forces security:'strict' and embedFontImport:false.

Describe a Mermaid diagram. format=text returns { ok, text } with one or two summary sentences; format=json returns { ok, tree } with the AX tree; format=facts returns { ok, facts } with deterministic semantic fact lines for machine checking (for example edge A -> B : label, member Duck +quack()).

Return version-matched mutation operations for one diagram family, or use capability=resolved-scene for painted geometry, runtime limits and typed errors. Use detail=signatures for the compact op menu or detail=fields (default) for exact field types, required flags, enum values, defaults, and constraints. Call this before build, mutate, or execute when the family schema is not already known.

Author a new Mermaid diagram from blank by folding a list of structured ops over an empty diagram of `family`. The declarative counterpart to hand-writing source. Returns the same envelope as `mutate`: { ok, family, source, verify } or { ok:false, family, opIndex, error }. Call `describe_sdk` for the family before authoring unfamiliar ops.

Run JavaScript in an isolated sandbox; return a value. No promises, async/await, dynamic import, or type annotations. SVG/ASCII/layout enforce security:'strict', embedFontImport:false. SDK: type DiagramKind='flowchart'|'state'|'sequence'|'timeline'|'class'|'er'|'journey'|'architecture'|'xychart'|'pie'|'quadrant'|'gantt'|'mindmap'|'gitgraph'|'radar'|'sankey'|'c4'|'packet'|'kanban'|'requirement'|'treemap'|'ishikawa'|'block'|'eventmodeling'|'zenuml' type MutationOp={kind:string;[field:string]:unknown} type Result<T,E={code:string;message:string}>={ok:true;value:T}|{ok:false;error:E} type ExternalFamilyId=`family:${string}`;interface SourceLocation{readonly line:number;readonly col:number;}interface SourceMap{readonly nodes:ReadonlyMap<string,SourceLocation>;readonly edges:ReadonlyMap<string,SourceLocation>;readonly groups:ReadonlyMap<string,SourceLocation>;readonly labels:ReadonlyMap<string,SourceLocation>;readonly spans?:SourceMapSpans;}interface SourceMapSpans{readonly preserved:PreservedSourceSpans;readonly nodes:ReadonlyMap<string,SourceSpan>;readonly edges:ReadonlyMap<string,SourceSpan>;readonly groups:ReadonlyMap<string,SourceSpan>;readonly labels:ReadonlyMap<string,SourceSpan>;readonly metadata?:ReadonlyMap<string,ReadonlyMap<string,{readonly key:SourceSpan;readonly value:SourceSpan;}>>;}interface PreservedSourceSpans{readonly source:SourceSpan;readonly wrapper?:SourceSpan;readonly frontmatter?:SourceSpan;readonly initDirectives?:readonly SourceSpan[];readonly accessibilityDirectives?:readonly SourceSpan[];readonly header:SourceSpan;readonly body:SourceSpan;}interface SourceSpan{readonly start:SourceSpanPoint;readonly end:SourceSpanPoint;}interface SourceSpanPoint{readonly offset:number;readonly line:number;readonly col:number;}interface SourcePreservationReceipt{readonly version:1;readonly classification:'unsupported'|'inventory-only'|'unknown';readonly source:string;readonly header:string;readonly upstreamFamilyId?:string;readonly mermaidVersion:string;readonly spans?:PreservedSourceSpans;}interface ParseError{readonly code:string;readonly message:string;readonly line?:number;readonly col?:number;readonly preservation?:SourcePreservationReceipt;readonly help?:string;}type RenderedRegionKind='node'|'edge'|'label'|'canvas'|'group'|'cluster'|'lane'|'band'|'compartment'|'plot'|'ring';interface RenderedRegion{id:string;kind:RenderedRegionKind;elementId?:string;parentId?:string;bounds:{x:number;y:number;w:number;h:number;};cellSpans?:Array<{row:number;start:number;end:number;}>;occludedCellSpans?:Array<{row:number;start:number;end:number;}>;sourceLine?:number;}type DiagramActionKind='href'|'call'|'callback';type DiagramActionSecurity='safe'|'unsafe'|'source-only'|'unsupported';interface DiagramActionRecord{id?:string;regionId?:string;family:DiagramKind;target:string;action:DiagramActionKind;raw:string;line?:number;href?:string;tooltip?:string;security:DiagramActionSecurity;executable:false;message?:string;}interface LayoutRect{x:number;y:number;w:number;h:number;}interface ExtensionIdentity<Kind extends string=string>{readonly id:`${Kind}:${string}`;readonly kind:Kind;readonly version:string;readonly compatibility:ExtensionCompatibility;readonly provenance:ExtensionProvenance;}interface ExtensionCompatibility{readonly[contract:string]:string|undefined;readonly core?:string;readonly scene?:string;}interface ExtensionProvenance{readonly owner:string;readonly source:string;readonly reference?:string;}type CheckMermaidSpec=readonly string[]|CheckMermaidObjectSpec;interface CheckMermaidObjectSpec{include?:readonly string[];exclude?:readonly string[];exact?:boolean;}interface CheckMermaidResult{ok:boolean;missing:string[];unexpected:string[];facts:string[];}interface CreateMermaidOptions{c4Variant?:C4Variant;direction?:Direction;}type C4Variant='C4Context'|'C4Container'|'C4Component'|'C4Dynamic'|'C4Deployment';type Direction='TD'|'TB'|'LR'|'BT'|'RL'; interface ValidDiagram{readonly kind:DiagramKind;readonly source:SourceMap} interface ExtensionValidDiagram{ readonly kind:ExternalFamilyId readonly descriptorIdentity:ExtensionIdentity<'family'> readonly source:SourceMap } interface PreservedValidDiagram{ readonly kind:ExternalFamilyId readonly source:SourceMap readonly body:{ readonly kind:'preserved' readonly representation:'opaque'|'unknown' readonly source:string readonly preservation:SourcePreservationReceipt readonly spans:PreservedSourceSpans readonly diagnostic:{ readonly code:'UNSUPPORTED_FAMILY'|'UNKNOWN_HEADER'|'FAMILY_DESCRIPTOR_MISMATCH' readonly message:string readonly help:string } } } type ParsedDiagram=ValidDiagram|ExtensionValidDiagram|PreservedValidDiagram type Narrow=(d:ParsedDiagram)=>ValidDiagram|null interface RenderedLayout{version:1;kind:DiagramKind|ExternalFamilyId;nodes:unknown[];edges:unknown[];groups:unknown[];labels?:Array<{id:string;text:string;bounds?:LayoutRect;container?:LayoutRect;visibility?:'visible'|'hidden'|'semantic'}>;regions?:RenderedRegion[];actions?:DiagramActionRecord[];bounds:{w:number;h:number}} interface ResolvedScene{version:2;family:string;width:number;height:number;svg:string} interface VerifyResult{ok:boolean;warnings:unknown[];layout:RenderedLayout;checks?:{renderability:'passed'|'failed'|'not-checked';sourceLoss:'detected'|'not-detected';taskCorrectness:'not-checked'}} type MermaidConfigScalar=string|number|boolean|null type MermaidConfigValue=MermaidConfigScalar|MermaidConfigValue[]|{[key:string]:MermaidConfigValue|undefined} type MermaidRuntimeConfig={[key:string]:MermaidConfigValue|undefined} interface StyleColors{bg?:string;fg?:string;line?:string;accent?:string;muted?:string;surface?:string;border?:string} type SceneStyleRole="node"|"edge"|"edge-label"|"group"|"group-header"|"label"|"actor"|"lifeline"|"activation"|"message"|"block"|"note"|"class-box"|"member"|"entity"|"attribute"|"relationship"|"cardinality"|"pie-slice"|"legend"|"bar"|"series"|"point"|"axis"|"grid"|"plate"|"section"|"task"|"milestone"|"marker-line"|"rail"|"period"|"event"|"score"|"actor-pill"|"service"|"junction"|"icon"|"title"|"defs"|"prelude"|"chrome" type ExactSceneStyleRole="node"|"edge"|"group"|"group-header"|"label"|"actor"|"relationship"|"pie-slice"|"legend"|"bar"|"series"|"point"|"task"|"milestone" type BindableSceneStyleRole="group-header"|"actor"|"relationship"|"pie-slice"|"legend"|"bar"|"series"|"point"|"task"|"milestone" type RoleStyleSpec={"fontFamily"?:string;"fontSize"?:number;"fontWeight"?:number;"letterSpacing"?:number;"textTransform"?:"uppercase"|"lowercase"|"capitalize";"textColor"?:string;"paddingX"?:number;"paddingY"?:number;"cornerRadius"?:number;"lineWidth"?:number;"bendRadius"?:number;"fillColor"?:string;"borderColor"?:string;"strokeColor"?:string;"headerFillColor"?:string;"cue"?:"none"|"outline"|"double-line"|"pattern"} type RoleStyleFor<R extends ExactSceneStyleRole>=R extends"node"|"actor"?Pick<RoleStyleSpec,"borderColor"|"cornerRadius"|"fillColor"|"fontSize"|"fontWeight"|"letterSpacing"|"lineWidth"|"paddingX"|"paddingY"|"textColor"|"textTransform">:R extends"edge"|"relationship"?Pick<RoleStyleSpec,"bendRadius"|"fontSize"|"fontWeight"|"letterSpacing"|"lineWidth"|"strokeColor"|"textColor"|"textTransform">:R extends"group"?Pick<RoleStyleSpec,"borderColor"|"cornerRadius"|"fillColor"|"fontFamily"|"fontSize"|"fontWeight"|"headerFillColor"|"letterSpacing"|"lineWidth"|"paddingX"|"paddingY"|"textColor"|"textTransform">:R extends"group-header"?Pick<RoleStyleSpec,"borderColor"|"cue"|"fillColor"|"fontFamily"|"fontSize"|"fontWeight"|"letterSpacing"|"lineWidth"|"strokeColor"|"textColor"|"textTransform">:R extends"label"?Pick<RoleStyleSpec,"fontSize"|"fontWeight"|"letterSpacing"|"textColor"|"textTransform">:R extends"pie-slice"|"task"|"milestone"?Pick<RoleStyleSpec,"borderColor"|"cue"|"fillColor"|"lineWidth"|"strokeColor">:R extends"legend"?Pick<RoleStyleSpec,"borderColor"|"fillColor"|"lineWidth"|"strokeColor"|"textColor">:R extends"bar"|"point"?Pick<RoleStyleSpec,"borderColor"|"fillColor"|"lineWidth"|"strokeColor">:R extends"series"?Pick<RoleStyleSpec,"borderColor"|"lineWidth"|"strokeColor">:never type RoleStyles={[R in ExactSceneStyleRole]?:Readonly<RoleStyleFor<R>>} type SemanticBindingChannel="category" interface SemanticBinding{channel:SemanticBindingChannel;value:string;slot:string;role?:BindableSceneStyleRole} type BrandConstraint={kind:"contrast";action:'warn'|'error';role?:SceneStyleRole;minimum?:number}|{kind:"accent-area";action:'warn'|'error';maxFraction:number}|{kind:"mono-role";action:'warn'|'error';role:SceneStyleRole} interface StyleSpec{"formatVersion"?:1;"$schema"?:string;"name"?:string;"blurb"?:string;"colors"?:StyleColors;"font"?:string;"roles"?:RoleStyles;"semanticSlots"?:Readonly<Record<string,Readonly<RoleStyleSpec>>>;"bindings"?:readonly SemanticBinding[];"constraints"?:readonly BrandConstraint[];"stroke"?:"crisp"|"jittered"|"freehand";"roughness"?:number;"bowing"?:number;"passes"?:number;"strokeWidth"?:number;"fill"?:"none"|"hachure"|"solid"|"wash";"hachureAngle"?:number;"hachureGap"?:number;"fillWeight"?:number;"washOpacity"?:number;"washEdge"?:number;"backdrop"?:"plain"|"paper-ruled"|"grid";"intent"?:"premium"|"draft"|"lofi";"mono"?:boolean} type StyleInput=string|StyleSpec type ArchitectureVisualOverrides=Readonly<Record<string,unknown>> interface SharedRenderOptions{layoutHints?:{ranks?:Record<string,number>;adjacent?:string[][];shortEdges?:string[]};graphLayout?:{backend:'elk'|'agentic';fallback?:'none'|'elk'};layoutSafety?:'report'|'strict';bg?:string;fg?:string;line?:string;accent?:string;muted?:string;surface?:string;border?:string;font?:string;style?:StyleInput|StyleInput[];padding?:number;nodeSpacing?:number;layerSpacing?:number;wrappingWidth?:number;componentSpacing?:number;transparent?:boolean;interactive?:boolean;shadow?:boolean;class?:{hierarchicalNamespaces?:boolean};kanban?:{maxWidth?:number};pie?:{maxWidth?:number};radar?:{maxWidth?:number};architecture?:{visual?:ArchitectureVisualOverrides};timeline?:{maxWidth?:number};journey?:{experienceCurve?:boolean};gantt?:{dependencyArrows?:boolean;criticalPath?:boolean};mermaidConfig?:MermaidRuntimeConfig;embedFontImport?:boolean;compact?:boolean;idPrefix?:string;security?:'default'|'strict';ganttToday?:string;seed?:number;} interface ConfigDiagnostic{code:'INEFFECTIVE_CONFIG';field:string;message:string} interface TerminalProjectionDiagnostic{code:string;feature:string;message:string;cell?:{column:number;row:number}} interface SvgRenderOptions extends SharedRenderOptions{onConfigDiagnostic?:(diagnostic:ConfigDiagnostic)=>void;} interface AsciiRenderOptions extends SharedRenderOptions{useAscii?:boolean;paddingX?:number;paddingY?:number;boxBorderPadding?:number;colorMode?:'auto'|'none'|'ansi16'|'ansi256'|'truecolor'|'html';theme?:{fg?:string;border?:string;line?:string;arrow?:string;accent?:string;bg?:string;corner?:string;junction?:string};maxWidth?:number;targetWidth?:number;onConfigDiagnostic?:(diagnostic:ConfigDiagnostic)=>void;onProjectionDiagnostic?:(diagnostic:TerminalProjectionDiagnostic)=>void;} interface LayoutRenderOptions extends SharedRenderOptions{debug?:boolean;regions?:boolean;actions?:boolean;onConfigDiagnostic?:(diagnostic:ConfigDiagnostic)=>void;} interface RenderArtifactDiagnostic{code:string;message?:string;reference?:string;feature?:string;input?:string;canonicalId?:string;removal?:{release:string;date:string}} interface CapabilityResolution{readonly id:`${string}:${string}`;readonly range:string;readonly level:'required'|'preferred'|'optional';readonly status:'selected'|'unsupported'|'incompatible';readonly version?:string} type CapabilityDecision=Readonly<{version:1;accepted:boolean;resolutions:readonly CapabilityResolution[]}>;interface RenderExecutionDecision{readonly family:{readonly id:string;readonly version:string};readonly backend:{readonly mode:'scene';readonly requestedId:string;readonly selectedId:string;readonly version:string;readonly hostPolicy:boolean}|{readonly mode:'family-svg'};readonly digest:string;} type GraphLayoutDecision=Readonly<{requested:'elk'|'agentic';fallback:'none'|'elk';selected:'elk'|'agentic';reason?:string;attempts:readonly Readonly<{backend:'elk'|'agentic';outcome:'selected'|'unsupported'|'candidate-rejected';reason?:string}>[];implementation:string;role?:'primary'|'companion'}>;interface RenderRequestReceipt{version:2;output:'svg'|'png'|'ascii'|'unicode'|'html'|'layout';sharedRequestDigest:string;requestDigest:string;appearanceDigest:string;capabilityDecision:CapabilityDecision;diagnostics?:readonly RenderArtifactDiagnostic[];graphicalProjectionDigest?:string;executionDecision?:RenderExecutionDecision;layoutDecisions?:readonly GraphLayoutDecision[]} interface RenderedSvg{svg:string;receipt:RenderRequestReceipt} interface RenderedAscii{text:string;receipt:RenderRequestReceipt;terminalStyle:Record<string,unknown>;outputPolicy:Record<string,unknown>} interface RenderedLayoutArtifact{layout:VerifyResult['layout'];receipt:RenderRequestReceipt} declare const mermaid:Record<'asFlowchart'|'asState'|'asSequence'|'asTimeline'|'asClass'|'asEr'|'asJourney'|'asArchitecture'|'asXyChart'|'asPie'|'asQuadrant'|'asGantt'|'asMindmap'|'asGitGraph'|'asRadar'|'asSankey'|'asC4'|'asPacket'|'asKanban'|'asRequirement'|'asTreemap'|'asIshikawa'|'asBlock'|'asEventModeling'|'asZenUML',Narrow>&{ parseRegisteredMermaid(source:string):Result<ParsedDiagram,ParseError[]> createMermaid(kind:DiagramKind,opts?:CreateMermaidOptions):ValidDiagram buildMermaid(kind:DiagramKind,ops:MutationOp[],opts?:CreateMermaidOptions):Result<ValidDiagram,{code:string;message:string;opIndex:number}> mutate(diagram:ValidDiagram,op:MutationOp):Result<ValidDiagram> //Opaque Class:add_member/remove_member;Flowchart:set_label/rename_node.Save source;warnings remain. mutatePreservingSource(d:ParsedDiagram,op:MutationOp):Result<{source:string;diagram:ParsedDiagram}> verifyMermaid(input:ParsedDiagram|string,opts?:{suppress?:string[];labelCharCap?:number;renderOptions?:SharedRenderOptions}):VerifyResult analyzeMermaid(diagram:ValidDiagram):Record<string,unknown> analyzeMermaidSource(source:string):Result<Record<string,unknown>> describeMermaidFacts(diagram:ValidDiagram):string[] describeMermaidFactsSource(source:string):Result<string[]> checkMermaid(diagram:ValidDiagram,spec:CheckMermaidSpec):CheckMermaidResult checkMermaidSource(source:string,spec:CheckMermaidSpec):Result<CheckMermaidResult> serializeMermaid(diagram:ParsedDiagram):string renderResolvedScene(input:ParsedDiagram|string,opts?:SvgRenderOptions):ResolvedScene renderMermaidSVG(input:ParsedDiagram|string,opts?:SvgRenderOptions):string renderMermaidSVGWithReceipt(input:ParsedDiagram|string,opts?:SvgRenderOptions):RenderedSvg renderMermaidASCII(input:ParsedDiagram|string,opts?:AsciiRenderOptions):string renderMermaidASCIIWithReceipt(input:ParsedDiagram|string,opts?:AsciiRenderOptions):RenderedAscii layoutMermaidWithReceipt(input:ParsedDiagram|string,opts?:LayoutRenderOptions):RenderedLayoutArtifact describeOps(family:DiagramKind):Record<string,{name:string;required:boolean;type:string;note?:string}[]> opSignatures(family:DiagramKind):string[] }

Apply a list of structured edit ops to an existing Mermaid `source` and return the edited diagram. This is the declarative counterpart to `execute`: plain JSON in, plain JSON out, no sandbox. Prefer it for straightforward edits; reserve `execute` for logic the ops don't express. Returns { ok, family, source, verify:{ ok, warnings } } on success, or { ok:false, family, opIndex, error } — where `error` names the offending field and lists the valid ones — when an op is malformed or cannot apply. Ops apply in order and are all-or-nothing: the first failing op stops the batch (its position is `opIndex`) and the input is left untouched. Each op is { "kind": <op>, …fields }. Call `describe_sdk` for the detected family before authoring unfamiliar ops; it returns compact signatures or exact field types, enum values, defaults, and constraints. Set mode to source-preserving for supported edits to opaque Class or Flowchart source. Exact edited bytes and portability warnings are retained; unsupported operations still fail atomically. This mode does not promise portable export.

Parse and verify source, structure, and renderability. This runs the graphical pipeline. Returns { ok, family, summary, warnings, layout: { bounds, nodes, edges } } for valid diagrams and { ok: false, errors } for parse failures. `family` is the detected diagram family and `summary` a one-line description — check them: ok:true only means the diagram is structurally valid, not that it is the kind you intended. Warnings use the layout-rubric codes.