Skip to main content
Glama

diag2md-mcp

Model Context Protocol (MCP) server providing AI coding agents with Draw.io C4 and UML architectural guardrails and diagram conversion capabilities.

GitHub Release License: MIT TypeScript

diag2md-mcp bridges Draw.io architecture diagrams (.xml, .drawio) with AI coding agents (such as Antigravity, Cursor, Claude Desktop, and VS Code MCP clients) by converting C4 and UML diagrams into structured Mermaid Markdown in real time.

Powered by diag2md.


Problem Statement

  • The Problem: AI coding assistants cannot natively interpret visual architecture diagrams (such as Draw.io files). Without a way to parse these diagrams, AI agents frequently generate code that violates a project's established C4 system and container boundaries.

  • The Impact: Attempting to solve this by pasting massive, static architectural documents into the AI's prompt severely bloats the context window and reduces the model's performance. As a result, projects suffer from "architectural drift," where the AI-generated codebase slowly misaligns with the intended system design and dependency rules.

  • The Need: There is a need for a dynamic, on-demand integration (via an MCP server) that translates visual Draw.io C4 diagrams into an AI-readable format (Mermaid Markdown). This solution will serve as a strict, real-time architectural guardrail, ensuring every AI prompt and code change remains aligned with the project's single source of truth.

  • Why the C4 Model?: The C4 model is the ideal architectural language for this bridge because it caters to both human and machine audiences perfectly. Its hierarchical structure (Context, Containers, Components, Code) provides high-level visual clarity that is easy for non-technical stakeholders and business leaders to understand. Simultaneously, its strict categorization provides the exact deterministic boundaries and structural logic that an AI needs to reason about system architecture, making it the perfect standard for AI-assisted engineering guardrails.


Related MCP server: drawio-mcp

Agent Architectural Guardrails (AGENTS.md / .cursorrules)

You can enforce strict architectural compliance across your team by adding an architectural rule directive to your project's AGENTS.md, GEMINI.md, or .cursorrules:

### ARCHITECTURAL RULES
Before writing any new modules, creating new services, or adding dependencies,
you MUST call the `convert_diagrams_read` MCP tool to verify that proposed changes
align with the C4 Draw.io architecture. Do not suggest structural changes that
violate these boundaries.

Key Features

  • Automated Workspace Discovery: Scans project directories for Draw.io diagram files matching configurable glob patterns (**/architecture/**/*.xml, **/*.drawio).

  • High-Performance In-Memory Conversion: Converts Draw.io XML models to Mermaid C4 & UML Markdown in-memory without subshell process spawning overhead.

  • AI Context Provider (convert_diagrams_read): Reads and converts diagrams dynamically to provide rich architectural context directly to AI coding assistants during chat sessions.

  • Batch Diagram Synchronization (convert_diagrams_write): Keeps architecture documentation up to date by generating .md files alongside diagram sources.


Quick Start

Running via npx

You can run the MCP server directly without pre-installing:

npx -y diag2md-mcp

Installing Globally

npm install -g diag2md-mcp

MCP Server Configuration

To connect diag2md-mcp to your favorite AI assistant or MCP client, add the server to your client configuration file (e.g., mcp_config.json, claude_desktop_config.json, Cursor, or Antigravity MCP settings).

{
  "mcpServers": {
    "diag2md-mcp": {
      "command": "diag2md-mcp"
    }
  }
}

Alternative: Local Built Source

{
  "mcpServers": {
    "diag2md-mcp": {
      "command": "node",
      "args": ["/path/to/diag2md-mcp/dist/index.js"]
    }
  }
}

Alternative: On-Demand via npx

{
  "mcpServers": {
    "diag2md-mcp": {
      "command": "npx",
      "args": ["-y", "diag2md-mcp"]
    }
  }
}

MCP Tools Reference

diag2md-mcp exposes 3 core tools to AI coding agents:

Tool Name

Description

Arguments

list_diagrams

Discovers all Draw.io architecture diagram files (.xml, .drawio) in the workspace matching glob patterns.

patterns (optional string[]), ignore (optional string[])

convert_diagrams_write

Batch scans workspace diagram files matching glob patterns, converts them, and writes updated .md files to disk.

patterns (optional string[]), diagramType (optional "c4" | "uml")

convert_diagrams_read

Batch scans workspace diagram files and returns converted Mermaid Markdown directly as context for the AI assistant.

patterns (optional string[]), diagramType (optional "c4" | "uml")


Server Configuration

The MCP server settings can be customized via environment variables:

Environment Variable

Description

Default Value

DIAG2MD_PATTERNS

Comma-separated glob patterns to discover diagram files.

**/architecture/**/*.xml, **/architecture/*.xml, **/*.drawio

DIAG2MD_IGNORE

Comma-separated glob patterns to ignore during file discovery.

**/node_modules/**, **/dist/**, **/.git/**

DIAG2MD_TYPE

Default conversion diagram type (c4 or uml).

c4

Configuration Example with env Patterns

You can configure custom search patterns directly in your MCP server JSON configuration using the env block:

{
  "mcpServers": {
    "diag2md-mcp": {
      "command": "diag2md-mcp",
      "env": {
        "DIAG2MD_PATTERNS": "**/architecture/**/*.xml, **/docs/**/*.drawio",
        "DIAG2MD_IGNORE": "**/tmp/**, **/node_modules/**",
        "DIAG2MD_TYPE": "c4"
      }
    }
  }
}

Dynamic Tool Call Example with patterns

AI assistants or tools can also override search patterns dynamically per request:

{
  "name": "convert_diagrams_read",
  "arguments": {
    "patterns": [
      "**/architecture/**/*.xml",
      "**/docs/**/*.drawio"
    ]
  }
}

Development

# Clone the repository
git clone https://github.com/diag2md/diag2md-mcp.git
cd diag2md-mcp

# Install dependencies
npm install

# Build TypeScript to JavaScript dist/
npm run build

# Run unit tests
npm run test

# Run type checker
npm run typecheck

License

MIT © polymatic.ventures

Available Tools

3 tools
convert_diagrams_readA

Batch scan and convert all workspace diagram files (.xml, .drawio) into Mermaid Markdown, returning their content directly as AI context.

Inputs: patterns, diagramType.

convert_diagrams_writeA

Batch scan workspace diagrams matching glob patterns and convert them to updated .md files on disk.

Inputs: patterns, diagramType.

list_diagramsA

Discover all Draw.io architecture diagram files (.xml, .drawio) in the workspace using glob patterns.

Inputs: ignore, patterns.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    list_diagrams is clearly discovery-only, while the two convert tools are separated by output behavior: _write persists .md files to disk and _read returns content as AI context. There is no meaningful overlap between any pair.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in lowercase snake_case, using the same 'diagrams' resource. The _read/_write suffixes are a coherent way to distinguish output modes, and list_diagrams fits the pattern as an independent discovery action.

    Tool Count5/5

    Three tools is a well-scoped set for a focused converter utility: discover source files, convert to files, and convert to context. Each tool addresses a distinct workflow step without unnecessary expansion.

    Completeness5/5

    The core workflow of finding Draw.io diagrams and converting them to Mermaid Markdown is fully covered in both output modes (disk and context). No obvious dead ends or missing lifecycle operations are apparent for this narrow domain.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to programmatically create, modify, and analyze Draw.io diagrams through the Model Context Protocol. Supports generating architectural diagrams, flowcharts, and visualizations with bidirectional communication between AI systems and Draw.io.
      13
      1,500
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to generate professional UML diagrams (class, use case, activity, sequence) from natural language descriptions, producing editable .drawio files compatible with diagrams.net.
      7
      109 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to create, read, update, and delete Draw.io diagrams, allowing automated generation of architectural diagrams, flowcharts, and visual documentation.
      MIT