Fast Mermaid Validator MCP

# Claude Code Usage Example - Mermaid Validator MCP This document demonstrates how to use the Mermaid Validator MCP with Claude Code and provides fixes for common diagram validation errors. ## Validation Results Summary **Total Files Processed:** 9 **Total Diagrams Found:** 43 **Valid Diagrams:** 32 **Invalid Diagrams:** 11 ## Using with Claude Code ### 1. Initial Validation Command ```bash # Ask Claude Code to validate all diagrams in examples folder claude validate all diagrams in the examples folder ``` ### 2. MCP Integration The validation uses the `mcp__mermaid-validator__validate-files` tool which: - Processes multiple markdown files simultaneously - Extracts Mermaid code blocks automatically - Uses both Jison and Langium grammar parsers - Provides detailed error messages with line numbers - Reports processing time and validation methods ## Common Validation Errors and Fixes ### 1. Quoted Text in Node Labels (2 files affected) **Files:** `dad_child3.md`, `dad_child3_original.md` **Error:** ``` Parse error on line 3: ...o --> F[Log Error: "No COMMAREA Received" Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', got 'STR' ``` **Problem:** Double quotes inside node labels confuse the parser. **Original (Invalid):** ```mermaid flowchart TD A[Start User Security Data Process] --> B{Transaction Data Received?} B -- No --> F[Log Error: "No COMMAREA Received"] B -- Yes --> C{Transaction Request ID='02ACUS'?} ``` **Fixed Version:** ```mermaid flowchart TD A[Start User Security Data Process] --> B{Transaction Data Received?} B -- No --> F[Log Error: No COMMAREA Received] B -- Yes --> C{Transaction Request ID=02ACUS?} ``` ### 2. Quadrant Chart Syntax Error **File:** `all_26_diagram_types.md` **Error:** ``` Parse error on line 1: quadrant title R Expecting 'SPACE', 'QUADRANT', 'NEWLINE', got 'ALPHA' ``` **Original (Invalid):** ```mermaid quadrant title Reach and influence x-axis Low Reach --> High Reach ``` **Fixed Version:** ```mermaid quadrantChart title Reach and influence x-axis Low Reach --> High Reach y-axis Low Influence --> High Influence quadrant-1 We should expand quadrant-2 Need to promote quadrant-3 Re-evaluate quadrant-4 May be improved ``` ### 3. C4 Context Diagram Error **File:** `all_26_diagram_types.md` **Error:** ``` Lexical error on line 1. Unrecognized text. c4Context title ``` **Original (Invalid):** ```mermaid c4Context title System Context diagram for Internet Banking System ``` **Fixed Version:** ```mermaid C4Context title System Context diagram for Internet Banking System Enterprise_Boundary(eb, "Banking Enterprise") { Person(customer, "Banking Customer", "A customer") System(banking_system, "Internet Banking System", "Allows customers to view information") } ``` ### 4. Treemap Syntax Error **File:** `all_26_diagram_types.md` **Error:** ``` Treemap diagram must start with "treemap-beta" ``` **Original (Invalid):** ```mermaid treemap title "Sales by Region" ``` **Fixed Version:** ```mermaid treemap-beta title "Sales by Region" "North America" 40 "Europe" 30 "Asia" 20 "Others" 10 ``` ### 5. Intentional Invalid Syntax Examples **Files:** `test_invalid_syntax.md`, `comprehensive_test.md`, `invalid_sequence.md` These files contain intentionally invalid syntax for testing purposes: **Invalid Flowchart:** ```mermaid flowchart TD A --> --> B invalid syntax here ``` **Invalid Sequence:** ```mermaid sequenceDiagram participant A->->->B: invalid arrows random text ``` ## Claude Code Workflow Example ### Step 1: Discovery and Analysis ```bash # Claude Code automatically: # 1. Found all .md files in examples/ using Glob tool # 2. Read file contents using Read tool # 3. Used TodoWrite to track validation progress ``` ### Step 2: Batch Validation ```bash # Claude Code processed all files through MCP validator: # - Extracted 43 Mermaid diagrams from 9 files # - Validated using appropriate grammar parsers # - Generated detailed error reports with line numbers ``` ### Step 3: Error Analysis and Fixes ```bash # Claude Code can automatically: # 1. Analyze validation errors # 2. Suggest fixes based on error messages # 3. Apply fixes using Edit/MultiEdit tools # 4. Re-validate to confirm fixes ``` ## Grammar Parser Coverage ### Jison Grammar Parsers (18 types) - Mostly Working - ✅ flowchart, sequence, class, state, ER, gantt - ✅ journey, requirement, sankey, xychart, kanban - ✅ mindmap, timeline, block - ❌ quadrant (syntax issue) - ❌ c4Context (case sensitivity) ### Langium Grammar Parsers (8 types) - Working Well - ✅ pie, gitgraph, info, architecture, radar, packet - ❌ treemap (requires -beta suffix) ## Performance Metrics - **Total Processing Time:** 46ms for 43 diagrams - **Average per Diagram:** ~1ms - **Parser Distribution:** - Jison: 35 diagrams - Langium: 8 diagrams - **Success Rate:** 74% (32/43 valid) ## Best Practices for Claude Code Integration ### 1. Batch Processing Use the file validation tool for multiple documents: ```javascript mcp__mermaid-validator__validate-files([ {fileName: "doc1.md", content: "...", encoding: "utf8"}, {fileName: "doc2.md", content: "...", encoding: "utf8"} ]) ``` ### 2. Error Handling Check validation results and apply fixes: ```bash # Claude Code can automatically: # - Identify files with invalid diagrams # - Parse error messages to understand issues # - Apply systematic fixes across multiple files # - Re-validate to ensure corrections work ``` ### 3. Documentation Updates After fixes, update documentation: ```bash # Claude Code can: # - Generate validation summary reports # - Update README files with parser status # - Create examples of valid diagram syntax # - Document known limitations and workarounds ``` ## Integration with Development Workflow ### Pre-commit Validation ```bash # Add to pre-commit hooks: claude validate-mermaid-diagrams docs/ ``` ### CI/CD Pipeline ```bash # Automated validation in GitHub Actions: - name: Validate Mermaid Diagrams run: | claude mcp validate-diagrams --path ./docs if [ $? -ne 0 ]; then exit 1; fi ``` ### Documentation Maintenance ```bash # Regular validation of documentation: claude check-all-mermaid-diagrams --fix-common-errors ``` ## Specific Performance Example: dad_child3_original.md ### File Validation Metrics ```json { "fileName": "dad_child3_original.md", "size": 4581, "totalDiagrams": 1, "validDiagrams": 0, "invalidDiagrams": 1, "processingTime": 0 } ``` ### Diagram Validation Details ```json { "diagramId": "diagram_1", "valid": false, "errors": [ { "type": "syntax_error", "message": "Parse error on line 3:\n...o --> F[Log Error: \"No COMMAREA Received\"\nExpecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', got 'STR'", "line": 3, "column": 1 } ], "metadata": { "diagramType": "flowchart", "validationMethod": "real_jison_grammar", "contentLength": 464, "lineCount": 13, "processingTime": 0 } } ``` ### Performance Analysis **Fast Failure Detection:** - **Processing Time:** 0ms (instantaneous) - **Error Location:** Line 3, Column 1 - **Failure Point:** Quoted text in node label `F[Log Error: "No COMMAREA Received"]` **Why So Fast:** 1. **Early Termination:** Jison parser fails immediately on invalid syntax 2. **Grammar-Based:** Real parser rules catch errors without full document processing 3. **Efficient Error Handling:** No need to continue parsing after syntax error **Performance Comparison:** ``` Total validation (43 diagrams): 46ms This diagram (invalid): 0ms Valid diagrams average: 1-4ms Overall average: ~1ms per diagram ``` **Claude Code Integration Benefits:** - **Immediate Feedback:** Syntax errors caught in milliseconds - **Precise Location:** Exact line and column of error - **Batch Efficiency:** Can process hundreds of diagrams quickly - **Grammar Accuracy:** Real Mermaid parser rules, not regex matching ## Conclusion The Mermaid Validator MCP provides comprehensive validation capabilities when integrated with Claude Code: 1. **Automated Discovery:** Finds all Mermaid diagrams across multiple files 2. **Batch Processing:** Validates dozens of diagrams simultaneously 3. **Detailed Reporting:** Provides specific error messages with line numbers 4. **Grammar Coverage:** Supports 26+ diagram types across two parser engines 5. **Integration Ready:** Works seamlessly with Claude Code's file processing tools 6. **High Performance:** Sub-millisecond validation with early error detection The combination enables efficient diagram validation, error identification, and systematic fixes across large documentation projects with enterprise-grade performance and accuracy.