# Mermaid Lint MCP

[中文版本](README_zh.md) | **English**

A powerful tool for validating Mermaid diagrams with both CLI and MCP server capabilities. Perfect for developers, technical writers, and AI assistants who work with Mermaid diagrams.

## 🚀 Quick Start

### Install and Use Immediately

```bash
# Validate a Mermaid file
npx mermaid-lint-mcp lint diagram.mmd

# Validate Mermaid code directly
npx mermaid-lint-mcp lint --code "graph TD; A-->B"

# Start MCP server for AI assistants
npx mermaid-lint-mcp server

# Get help
npx mermaid-lint-mcp --help
```

No installation required! The tool will be downloaded automatically on first use.

## 🎯 Use Cases

### For Developers
- **Pre-commit validation**: Ensure all Mermaid diagrams in your codebase are valid
- **CI/CD integration**: Add diagram validation to your build pipeline
- **Documentation quality**: Catch syntax errors before publishing docs

### For Technical Writers
- **Content validation**: Verify diagrams render correctly before publication
- **Error debugging**: Get clear error messages for syntax issues

### For AI Assistants
- **Real-time validation**: Validate generated diagrams instantly
- **MCP integration**: Seamless integration with Claude Code, Cursor, Trae, and other AI tools
- **Automated workflows**: Enable AI to self-validate diagram outputs

## 📋 Features

- ✅ **Fast Validation**: Optimized for speed with browser reuse and local libraries
- ✅ **Multiple Formats**: Support for all Mermaid diagram types
- ✅ **Dual Interface**: Both CLI tool and MCP server in one package
- ✅ **Error Details**: Clear error messages with line numbers and suggestions
- ✅ **Timeout Control**: Configurable validation timeouts
- ✅ **Zero Config**: Works out of the box

## 🛠️ Installation Options

### Option 1: Use with npx (Recommended)
No installation needed - just use `npx mermaid-lint-mcp` directly.

### Option 2: Global Installation
```bash
npm install -g mermaid-lint-mcp
# Then use: mermaid-lint-mcp
```

### Option 3: Local Project Installation
```bash
npm install mermaid-lint-mcp
# Then use: npx mermaid-lint-mcp
```

## 📖 Usage Guide

### CLI Commands

#### Validate Diagrams
```bash
# Validate a file
npx mermaid-lint-mcp lint diagram.mmd
npx mermaid-lint-mcp diagram.mmd  # 'lint' is default

# Validate code string
npx mermaid-lint-mcp lint --code "graph TD; A-->B"

# With custom timeout (5 seconds)
npx mermaid-lint-mcp lint --timeout 5000 diagram.mmd

# Validate with file option
npx mermaid-lint-mcp lint --file diagram.mmd
```

#### Start MCP Server
```bash
# Start server for AI assistant integration
npx mermaid-lint-mcp server
```

#### Get Help
```bash
npx mermaid-lint-mcp --help     # Show all commands
npx mermaid-lint-mcp --version  # Show version
```

### MCP Server Integration

#### For Claude Desktop
Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mermaid-lint": {
      "command": "npx",
      "args": ["mermaid-lint-mcp", "server"]
    }
  }
}
```

#### For Other MCP Clients, the setup is similar to above, please refer to the official documentation

## 📊 Supported Diagram Types

| Type | Syntax | Example |
|------|--------|---------|
| Flowchart | `flowchart TD` | Decision trees, processes |
| Sequence | `sequenceDiagram` | API interactions, workflows |
| Class | `classDiagram` | Object relationships |
| State | `stateDiagram-v2` | State machines |
| ER | `erDiagram` | Database schemas |
| Gantt | `gantt` | Project timelines |
| Pie | `pie` | Data visualization |
| Journey | `journey` | User experiences |
| Git Graph | `gitgraph` | Version control flows |
| ... | `...` | ... |

## 🔧 Configuration

### Validation Options
```typescript
interface ValidationOptions {
  timeout?: number;  // Timeout in milliseconds (default: 5000)
}
```

### Environment Variables
```bash
# Set default timeout
export MERMAID_TIMEOUT=10000

# Enable debug logging
export DEBUG=mermaid-lint-mcp
```

## 🔍 Example Outputs

### Valid Diagram
```json
{
  "isValid": true,
  "error": null,
  "diagramType": "flowchart"
}
```

### Invalid Diagram
```json
{
  "isValid": false,
  "error": "Parse error on line 8: ...> C E --> F[End ---------------------^ Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got '1'",
  "diagramType": "flowchart"
}
```

### CLI Output
```bash
$ npx mermaid-lint-mcp lint --code "graph TD; A-->B"
🔍 Validating Mermaid diagram...
✅ Diagram is valid!
📊 Diagram type: flowchart
```

## 🚨 Common Issues & Solutions

### Issue: "Command not found"
**Solution**: Use `npx mermaid-lint-mcp` instead of `mermaid-lint-mcp`

### Issue: Validation timeout
**Solution**: Increase timeout with `--timeout 10000`

### Issue: Permission denied
**Solution**: Run with appropriate permissions or use `npx`

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙋‍♂️ Support

- 📖 [Documentation](https://github.com/yaodebian/mermaid-lint-mcp)
- 🐛 [Report Issues](https://github.com/yaodebian/mermaid-lint-mcp/issues)
- 💬 [Discussions](https://github.com/yaodebian/mermaid-lint-mcp/discussions)

## 🔗 Related Tools

- [Mermaid](https://mermaid.js.org/) - Create diagrams with text
- [Mermaid Live Editor](https://mermaid.live/) - Online diagram editor
- [Model Context Protocol](https://modelcontextprotocol.io/) - AI integration standard