diag2md-mcp

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

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.

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.

Related MCP server: drawio-mcp

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).

Recommended (Globally Installed Package)

{
  "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:

Server Configuration

The MCP server settings can be customized via environment variables:

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