Enhancement: Add Mermaid diagram tool with syntax validation

[jezweb]

Summary

Add a structured Mermaid diagram tool (similar to Timeline/Charts) with syntax validation to complement the existing markdown code block support.

Problem

While Mermaid diagrams work via markdown code blocks, complex diagrams often fail due to syntax errors:

• AI models (GPT-5, Claude) sometimes generate invalid Mermaid syntax
• Errors like <br/> tags in node labels break parsing
• No feedback loop for AI to self-correct

Example failures:

• Complex flowcharts with nested decisions
• Multi-line labels with HTML escaping
• Intricate sequence diagrams

Proposed Solution

Create createMermaidDiagram tool with:

Schema

{
  title: string;
  description?: string;
  diagramType: "flowchart" | "sequence" | "gantt" | "class" | "state" | "erDiagram" | "pie";
  mermaidCode: string;
}

Key Feature: Syntax Validation

execute: async ({ mermaidCode }) => {
  try {
    await mermaid.parse(mermaidCode);
    return "Diagram syntax valid";
  } catch (error) {
    return `Mermaid syntax error: ${error.message}`;
  }
}

This gives AI a feedback loop to retry and fix syntax automatically.

Benefits

1. Self-correcting - AI receives parse errors and can retry
2. Consistency - Matches Timeline/Chart tool patterns
3. Metadata - Can add title/description wrapper
4. Better UX - Fewer broken diagrams shown to users
5. Debugging - JSON popup for inspecting raw code

Implementation Notes

• Reuse existing mermaid-diagram.tsx component (no changes needed)
• Follow Timeline tool pattern (5 files: 2 new, 3 modified)
• Estimated time: ~2 hours
• Does NOT replace markdown blocks - both approaches coexist

Non-Goals

• Not fixing Mermaid syntax issues (that's on the AI models)
• Not removing existing markdown support (keep both)
• Not comprehensive validation (just parse checks)

Priority

Low-Medium - Nice to have but not crucial. Markdown blocks work fine for simple diagrams.

Related

• Existing implementation: src/components/mermaid-diagram.tsx
• Timeline tool pattern: PR feat: Add Timeline visualization component #307

[linear]

MCP-112

[cgoinglove]

I've also seen several models fail when using mermaid.

However, since there are some ambiguous cases when extracting with tools, I'll first check whether it can be sufficiently resolved via the system prompt and whether the error can be recovered through the code.

[brrock]

We could migrate to stream down and put something in the prompt