Diagram Generator

Overview

Generate and edit diagrams in multiple formats (drawio, mermaid, excalidraw) by creating structured JSON descriptions and delegating file generation to the mcp-diagram-generator MCP server.

Contact Information If you encounter any issues, please contact AlkaidY at tccio2023@gmail.com.

Prerequisites Check

IMPORTANT: This skill requires the mcp-diagram-generator MCP server to be installed and configured.

Quick Verification

Before using this skill, verify the MCP server is available by checking if you can access these tools:

• - INLINECODE1
• INLINECODE2
• INLINECODE3

If these tools are NOT available, you need to configure the MCP server first (see below).

Installation & Configuration

Option 1: Using npx (Recommended - Auto-downloads the package)

Add the following to your Claude Code configuration file:

• - Global config (~/.claude.json) for all projects, or
• Project config (.claude.json) for specific project

CODEBLOCK0

After adding this configuration:

1. 1. Restart Claude Code
2. The MCP server will auto-download via npx on first use
3. No manual installation needed

Option 2: Local Development (For developers)

If you're developing the MCP server locally:

CODEBLOCK1

Verification Steps

After configuration, verify it works:

1. 1. Check configuration: Call get_config() tool
2. If successful, you'll see current paths and initialization status
3. If the tool doesn't exist, check your configuration file syntax

Common Issues

Issue: "Tool not found" error

• - Solution: MCP server not configured. Follow installation steps above.

Issue: Configuration looks correct but tools still not available

• - Solution: Restart Claude Code to reload MCP server configuration

Quick Start

First Time Use

On first use, the MCP server will automatically:

1. 1. Create default configuration file (.diagram-config.json)
2. Create default output directories if they don't exist
3. Use sensible defaults: INLINECODE8

You can customize paths at any time using the init_config tool.

Basic Usage

Simple example - just provide diagram spec, let the server handle the rest:

CODEBLOCK2

Skill will:

1. 1. Generate JSON spec
2. Call generate_diagram with only diagram_spec parameter
3. Server auto-creates directories and saves to INLINECODE12

Workflow

Step 1: Understand Requirements

Extract from user's natural language:

• - Diagram type: flowchart, sequence diagram, class diagram, ER diagram, mindmap, architecture diagram, network topology
• Content: nodes, relationships, nested structure (for network topology)
• Style/theme: if mentioned (e.g., "clean style", "detailed")
• Output preferences: specific filename? custom path?

Step 2: Choose Format

Use format-selection-guide.md to decide:

Step 3: Generate Structured JSON

Create a JSON description following the JSON Schema. Key structure:

CODEBLOCK3

Important: Use unique IDs for all elements. For nested structures, maintain parent-child relationships.

Step 4: Call MCP Server

Option A: Use defaults (recommended)

CODEBLOCK4

The MCP server will:

• - Validate the JSON schema
• Generate the appropriate XML/JSON/markdown
• Auto-create output directories if needed
• Save to configured default path (e.g., diagrams/drawio/network-topology-2025-02-03.drawio)

Option B: Specify custom path

CODEBLOCK5

Option C: Just provide filename, use default directory

CODEBLOCK6

Step 5: Editing Existing Diagrams

1. 1. Read the existing file to understand structure
2. Parse the diagram (use MCP tool if available, or read raw file)
3. Modify the JSON description based on user's change request
4. Generate new diagram (overwrite or create new file)

Configuration Management

Initialize Configuration

Initialize with defaults:
CODEBLOCK7

Initialize with custom paths:
CODEBLOCK8

View Current Configuration

CODEBLOCK9

Update Single Path

CODEBLOCK10

Supported Diagram Types

Flowchart

• - Simple process flows, decision trees
• Use mermaid for quick output
• Use drawio for complex layouts with multiple branches

Sequence Diagram

• - Show interactions over time between components
• mermaid recommended (native support)
• Use drawio if custom styling needed

Class Diagram

• - Show classes, methods, relationships
• mermaid recommended (compact, standard UML)
• drawio for detailed diagrams with many classes

ER Diagram

• - Database schema, entity relationships
• mermaid recommended
• drawio for complex schemas with many relationships

Mindmap

• - Hierarchical ideas, brainstorming
• mermaid recommended (native support)
• excalidraw for creative/hand-drawn style

Architecture Diagram

• - System architecture, component relationships
• drawio recommended for complex systems
• mermaid for high-level overviews

Network Topology

• - Network environments, datacenters, zones, devices
• Must use drawio (4-layer nesting: environment → datacenter → zone → device)
• See network-topology-examples.md for patterns

Network Topology Special Notes

Network topology diagrams require a 4-level hierarchical structure:

CODEBLOCK11

Style conventions:

• - Environment: fillColor: #e1d5e7, strokeColor: #9673a6 (purple)
• Datacenter: fillColor: #d5e8d4, strokeColor: #82b366 (green)
• Zone: fillColor: #fff2cc, strokeColor: #d6b656 (yellow)
• Device: Based on device type (router, switch, firewall, etc.)

Device types and styles:

• - Router: strokeColor: #607D8B (blue-gray)
• Switch: strokeColor: #4CAF50 (green)
• Firewall: strokeColor: #F44336 (red)
• PC/Server: strokeColor: #607D8B (blue-gray)

Common Patterns

Pattern 1: Simple Flowchart (Mermaid)

User: "画一个用户登录流程图，包含登录验证、重定向、错误处理"

Generate JSON:
CODEBLOCK12

Call MCP:
CODEBLOCK13

Pattern 2: Network Topology (Drawio)

User: "创建一个网络拓扑图，包含省中心机房（上联区、汇聚区、终端区），连接到生产网"

Generate JSON with nested containers (see json-schema-guide.md for details).

Call MCP:
CODEBLOCK14

Resources

references/

• - format-selection-guide.md: When to use drawio vs mermaid vs excalidraw
• json-schema-guide.md: Complete JSON schema with examples for all diagram types
• network-topology-examples.md: Example JSON for network topology patterns

assets/

• - No templates needed - MCP server handles all generation

scripts/

• - Not used - all generation delegated to MCP server

Troubleshooting

MCP Server Setup

If mcp-diagram-generator is not available, you need to install it.

Option 1: Using npx (Recommended)

Add to your Claude Code/OpenCode settings:

CODEBLOCK15

Option 2: Local Development

1. 1. Install dependencies: INLINECODE25
2. Build: INLINECODE26
3. Configure with local path:

Invalid JSON Schema

If MCP server returns validation error:

1. 1. Check json-schema-guide.md
2. Verify all required fields are present
3. Ensure all IDs are unique
4. Check parent-child relationships

Directory Not Found

Old behavior: Error if directory doesn't exist
New behavior: Directory is created automatically ✅

If you still see directory errors:

1. 1. Check write permissions for the project directory
2. Verify configuration with INLINECODE27
3. Reinitialize with INLINECODE28

Wrong File Extension

The server automatically uses the correct extension based on format:

• - drawio → INLINECODE29
• mermaid → INLINECODE30
• excalidraw → INLINECODE31

You don't need to specify extension in filename parameter.

Nested Container Issues (Network Topology)

• - Verify level field matches hierarchy (environment/datacenter/zone)
• Check parent IDs are correct in child elements
• Ensure geometry coordinates are relative to parent container

Best Practices

1. Use Default Paths

Let the server manage output paths for consistency:

CODEBLOCK17

2. Provide Descriptive Titles

Titles are used for auto-generated filenames:

CODEBLOCK18

3. Use Configuration for Custom Paths

Instead of specifying output_path every time, configure once:

CODEBLOCK19

4. Check Configuration When Troubleshooting

CODEBLOCK20