Provides comprehensive validation of Mermaid diagrams with support for 28+ diagram types including flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, and more. Validates diagram syntax using real grammar parsers and supports batch processing of markdown files and ZIP archives.
Mermaid Validator API
High-performance API and Model Context Protocol (MCP) server for validating Mermaid diagrams with comprehensive security features, multiple transport options, and enterprise-grade capabilities.
Author: Gregorio Elias Roecker Momm (gregoriomomm@gmail.com)
š Latest Updates (v1.0.29)
Unified CLI with Port Configuration:
ā Single Command: One
npx
command with flags to start any server modeā Port Control:
--port <number>
flag works with all server modesā Environment Variables:
PORT
,MCP_HTTP_PORT
,MCP_HTTP_HOST
supportā REST API:
npx @ai-of-mine/mermaid-validator-mcp
(default port: 8000)ā MCP HTTP:
npx @ai-of-mine/mermaid-validator-mcp --mcp-http
(default port: 8080)ā Built-in Help:
npx @ai-of-mine/mermaid-validator-mcp --help
Package Features:
ā NPM Package: Available as
@ai-of-mine/mermaid-validator-mcp
ā Security Updates: Fixed multer vulnerabilities
ā Clean Logging: Default log level set to
warn
for production readinessā Complete Distribution: Both source (
src/
) and compiled (dist/mcp/
) filesā Enterprise Ready: Unlimited configuration, environment variables, Docker support
API Endpoints:
http://localhost:8000/api/v1/validate
- Direct diagram validation (JSON)http://localhost:8000/api/v1/upload/file
- File upload validation (multipart)
MCP Server Commands:
npx @ai-of-mine/mermaid-validator-mcp --mcp-stdio
- Stdio transport (Claude Desktop)npx @ai-of-mine/mermaid-validator-mcp --mcp-http
- HTTP transport (port 8080)npx @ai-of-mine/mermaid-validator-mcp --mcp-secure
- Secure HTTP with authentication
š Dual Architecture: REST API + MCP Server
This project provides two complementary interfaces:
š REST API: Traditional HTTP API for web applications and direct integrations
š¤ MCP Server: Model Context Protocol server for LLM integrations (Claude Desktop, etc.)
Quick Start
Alternative: Install from source
Test MCP HTTP server:
šÆ Core Features
Validation Capabilities
28 Mermaid Diagram Types: Complete support with real grammar parsing
Multi-format Support: Markdown files, ZIP archives, direct input
Real Grammar Validation: Jison, ANTLR, and Langium parsers
High Performance: Optimized with minimal dependencies
MCP Server Features
Multiple Transports: Stdio, HTTP streamable, Server-Sent Events (SSE)
3 MCP Tools: validate-diagrams, validate-files, get-validation-stats
2 MCP Resources: config://limits, info://diagram-types
Full Protocol Compliance: JSON-RPC 2.0, MCP specification 2024-11-05
Security & Enterprise
Security Compliant: Complete audit logging and security best practices
Authentication: API key and Bearer token support
Rate Limiting: Configurable request throttling
Input Validation: Comprehensive sanitization and validation
Container Ready: Docker deployment with optimized images
Supported Diagram Types (28 Total)
Jison-based Validation (23 types)
Flowchart:
flowchart
,graph
- Flow diagrams and process charts āSequence:
sequenceDiagram
- UML sequence diagrams āClass:
classDiagram
- UML class diagrams āState:
stateDiagram
,stateDiagram-v2
- UML state diagrams āER:
erDiagram
- Entity relationship diagrams āGantt:
gantt
- Project timeline charts āUser Journey:
journey
- User experience journey maps āRequirement:
requirement
,requirementDiagram
- Requirements engineering diagrams āSankey:
sankey-beta
- Sankey flow diagrams āXY Chart:
xychart-beta
- Line and bar charts āKanban:
kanban
- Kanban boards āBlock:
block
,block-beta
- Block diagrams āC4:
c4
,C4Context
- C4 architecture diagrams āMindmap:
mindmap
- Mind maps āQuadrant:
quadrant
,quadrantChart
- Four-quadrant charts āTimeline:
timeline
- Timeline diagrams āExample:
exampleDiagram
- Example/test diagrams ā
Langium-based Validation (5 types)
Packet:
packet
,packet-beta
- Packet diagrams āArchitecture:
architecture
,architecture-beta
- Architecture diagrams āTreemap:
treemap
- Treemap diagrams ā
Validation Results: 28/28 types supported with real grammar parsing
š¤ MCP Server Documentation
For complete MCP server documentation, see: docs/api/README-MCP.md
Quick MCP Commands
MCP Tools Available
validate_mermaid: Direct diagram validation with comprehensive error reporting
validate_file: File content validation (Markdown, ZIP support) with base64 encoding
get_examples: Get sample diagrams for all 28+ supported diagram types
MCP Resources Available
config://limits: Validation limits and configuration
info://diagram-types: All 28 supported diagram types
š ļø Claude Code Integration
Adding to Claude Code
Install and start the MCP server:
# Install from npm npm install @ai-of-mine/mermaid-validator-mcp # Or from source git clone https://github.com/gregoriomomm/mermaid-validator-mcp.git cd mermaid-validator-mcp npm install npm run build:mcp npm run start:mcp-http # HTTP transport for Claude CodeConfigure Claude Code using the CLI:
claude mcp add --transport http -s project mermaid-validator http://localhost:8080/mcpThis creates a
.mcp.json
file in your project:{ "mcpServers": { "mermaid-validator": { "type": "http", "url": "http://localhost:8080/mcp" } } }Available Tools in Claude Code:
š validate_file - Validate ZIP Archives and Markdown Files
Process Base64-encoded ZIP archives containing multiple markdown files, or individual markdown files. Automatically extracts ZIP contents, finds ```mermaid code blocks, and validates all diagrams. Perfect for: Documentation validation, CI/CD checks, bulk processingš§ validate_mermaid - Validate Individual Mermaid Diagrams
Validate raw Mermaid diagram code blocks directly. Supports all 28+ diagram types with detailed syntax checking. Returns comprehensive error information with line numbers. Perfect for: Single diagram validation, syntax checking, error debuggingš get_examples - Get Sample Diagrams
Retrieve sample Mermaid diagrams for all supported diagram types. Perfect for learning syntax, testing validation, and development.
Usage Examples with Claude Code
Validate a documentation repository:
Check a single diagram:
Get sample diagrams:
Developer Workflow Example:
Supported Integrations
ā Claude Code (HTTP transport)
ā MCP Inspector (SSE/HTTP)
ā Claude Desktop (stdio transport)
ā Custom MCP clients (all transports)
š REST API Documentation
Quick Start
Start the API server:
The server runs on http://localhost:8000
by default.
API Endpoints
1. Direct Diagram Validation
Examples:
Valid Flowchart:
Invalid Flowchart:
Valid Sequence Diagram:
2. File Upload Validation
Parameters:
file
: One or multiple markdown files (.md
,.markdown
,.txt
) or ZIP archives (.zip
)timeout
: Optional timeout in milliseconds
Examples:
Single File Upload:
Multiple Files Upload:
Upload ZIP Archive:
With Validation Timeout:
Response:
Multiple Files Upload:
Response:
ZIP Archive Upload:
Response:
Error Response Example:
Test Results - All 25 Diagram Types:
Health Check
Response:
Direct Validation (Alternative Method)
Request:
Response:
Validation Statistics
Response:
š Quick Start
Using Docker (Recommended)
Using Node.js
Environment Variables
š New Configurable Limits (v1.0.15)
š Unlimited Mode
Set any limit to -1
to disable it completely:
š See
Deployment
Prerequisites
Kubernetes cluster with kubectl access
Container registry access (Docker Hub, GitHub Container Registry, etc.)
Docker/Podman for building images
Helm 3.x (for Helm deployments)
Make Commands
Development
Build & Deploy
Kubernetes (Kustomize)
Kubernetes (Helm)
Docker Development
Production Deployment
With Monitoring
Environment Configuration
Variable | Description | Default |
NODE_ENV | Application environment | production |
PORT | Server port | 8000 |
LOG_LEVEL | Logging level | info |
See DEPLOYMENT.md
for comprehensive deployment instructions.
Monitoring
Health Endpoints
GET /api/v1/health
- Basic health checkGET /api/v1/health/detailed
- Detailed system informationGET /api/v1/health/live
- Kubernetes liveness probeGET /api/v1/health/ready
- Kubernetes readiness probe
Metrics (with Prometheus)
Request rate and response times
Error rates by endpoint
Memory and CPU usage
File processing statistics
Validation success/failure rates
Grafana Dashboards
API performance metrics
System resource utilization
Error rate monitoring
Request volume trends
Security Features
Rate Limiting: Configurable per-IP request limits (100 requests per 15 minutes)
Input Validation: Comprehensive request validation with express-validator
File Security: Dual MIME type and file extension validation for robust upload security
Content Security: CSP headers, XSS protection, and security headers via Helmet
CORS Protection: Configurable cross-origin policies with whitelist support
Process Security: Non-root container execution with dedicated nodejs user
Resource Limits: Memory and disk usage monitoring with configurable thresholds
Upload Protection: File size limits, suspicious filename detection, and malware prevention
Testing
API Documentation
Interactive API documentation is available at /docs
when running in development mode.
Performance
Custom Grammar Parser: Fast validation without browser dependencies
Concurrent Processing: Multiple diagrams processed in parallel
Memory Efficient: Automatic cleanup of temporary files
Minimal Dependencies: Reduced attack surface and faster startup
Response Compression: Built-in compression for faster responses
Configuration
See src/config/config.js
for all available configuration options. Most settings can be controlled via environment variables for easy deployment customization.
š Claude Code Usage Examples
For comprehensive examples of using this validator with Claude Code, see:
CLAUDE_CODE_USAGE_EXAMPLE.md - Original validation examples
LATEST_CHANGES.md - Latest features and capabilities
docs/CONFIGURATION.md - Complete configuration guide
docs/PERFORMANCE_TESTING.md - Load testing methodology
docs/LOAD_TESTING_EVIDENCE.md - Performance evidence
Validation Results Summary
Recent validation of the examples/
folder:
Total Files Processed: 9
Total Diagrams Found: 43
Valid Diagrams: 32 (74% success rate)
Invalid Diagrams: 11
Common Issues and Fixes
1. Quoted Text in Node Labels
2. Diagram Type Syntax
3. Beta Suffix Requirements
Developer Workflow with Latest Features
Discovery:
claude validate all diagrams in examples folder
Batch Processing: Validates 43 diagrams across 9 files with unlimited processing
Error Analysis: Comprehensive error reporting with line numbers and context
Systematic Fixes: Apply corrections based on detailed error messages
Re-validation: Instant re-validation with optimized performance
Enterprise Scale: Process 100MB files, 100k+ diagrams with zero limits
Performance Capabilities (v1.0.15)
Single Pod: 500+ concurrent connections (with nginx proxy)
Cluster Scale: Auto-scale to 10,000+ concurrent connections
Processing: 145 req/sec sustained throughput
Zero-Error Experience: Aggressive HPA prevents connection failures
Enterprise Limits: 100MB files, 1MB diagrams, unlimited processing
License
PROPRIETARY - see LICENSE file for details.
Author
Gregorio Elias Roecker Momm
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Validates Mermaid diagrams with comprehensive grammar parsing supporting 28+ diagram types. Processes markdown files, ZIP archives, and direct input with detailed error reporting and enterprise-grade performance capabilities.
- š Latest Updates (v1.0.29)
- š Dual Architecture: REST API + MCP Server
- šÆ Core Features
- Supported Diagram Types (28 Total)
- š¤ MCP Server Documentation
- š ļø Claude Code Integration
- š REST API Documentation
- API Endpoints
- š Quick Start
- Deployment
- Monitoring
- Security Features
- Testing
- API Documentation
- Performance
- Configuration
- š Claude Code Usage Examples
- License
- Author