C++ UML Class Diagram Generator

A powerful Model Context Protocol (MCP) server that recursively analyzes C++ source and header files, extracts class definitions, inheritance relationships, and member information, then generates comprehensive UML class diagrams in PlantUML format.

Features

• 🔍 Multi-format C++ file support: .cpp, .hpp, .h, .cc, .cxx files
• 🏗️ Class & struct extraction: Automatically detects class/struct definitions
• 🔗 Inheritance mapping: Captures inheritance relationships and generates proper UML arrows
• 👁️ Member visibility: Handles public, private, and protected member access levels
• 📁 Directory scanning: Recursively processes entire project folders
• 📄 Content-based processing: Generate UML from provided file contents directly
• 🛡️ Error handling: Robust error handling with diagnostic UML output
• 🌐 MCP server support: Works as both HTTP and stdio MCP server
• 🐳 Docker ready: Containerized deployment support
• ✨ PlantUML output: Clean, valid PlantUML format for easy rendering

Installation

Quick Start

# Clone the repository
git clone https://github.com/hydavinci/uml-diagram.git
cd uml-diagram

# Install dependencies
pip install -r requirements.txt
# or using uv
uv sync

Docker Deployment

# Build the container
docker build -t uml-diagram-mcp .

# Run as HTTP server
docker run -p 8081:8081 -e TRANSPORT=http uml-diagram-mcp

# Run as stdio server
docker run -e TRANSPORT=stdio uml-diagram-mcp

Usage

As a Standalone Script

# Navigate to the src directory
cd src

# Generate UML from a C++ project directory
python uml_generate.py /path/to/your/cpp/project

# The UML diagram will be written to 'uml_output.puml' in the current directory

Example:

python uml_generate.py "C:\Projects\MyProject\src"
# Output: uml_output.puml

As a Python Module

Directory-based Generation

from src.uml_generate import generate_cpp_uml_from_path

# Generate UML from a directory
uml_diagram = generate_cpp_uml_from_path('/path/to/cpp/project')
print(uml_diagram)

# Save to file
with open('my_diagram.puml', 'w') as f:
    f.write(uml_diagram)

Content-based Generation

from src.uml_generate import generate_cpp_uml_from_content

# Dictionary where keys are file names and values are file contents
file_contents = {
    "animal.h": """
    class Animal {
    public:
        virtual void makeSound() = 0;
        virtual ~Animal() = default;
    protected:
        std::string name_;
    private:
        int age_;
    };
    """,
    "dog.h": """
    #include "animal.h"
    
    class Dog : public Animal {
    public:
        void makeSound() override;
        void bark();
    private:
        std::string breed_;
        bool isTrained_;
    };
    """,
    "cat.h": """
    #include "animal.h"
    
    class Cat : public Animal {
    public:
        void makeSound() override;
        void purr();
    private:
        bool isIndoor_;
    };
    """
}

uml_diagram = generate_cpp_uml_from_content(file_contents)
print(uml_diagram)

As an MCP Server

This tool provides a complete Model Context Protocol (MCP) server implementation with two available tools:

Available MCP Tools

1. generate_cpp_uml - Directory-based UML generation

   • Parameter: path (string) - Path to directory containing C++ files
   • Returns: PlantUML diagram as string
   • Example: Analyze entire C++ project directory

2. generate_cpp_uml_from_content - Content-based UML generation

   • Parameter: file_contents (Dict[str, str]) - Dictionary mapping file names to their contents
   • Returns: PlantUML diagram as string
   • Example: Generate UML from provided source code snippets

Starting the MCP Server

HTTP Mode (recommended for web clients):

# Set transport mode and start server
export TRANSPORT=http
python src/server.py

# Server will start on port 8081 by default
# Access at: http://localhost:8081

Stdio Mode (for command-line clients):

# Default mode - no environment variable needed
python src/server.py

# Or explicitly set stdio mode
export TRANSPORT=stdio
python src/server.py

MCP Client Integration Example

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def use_uml_generator():
    server_params = StdioServerParameters(
        command="python",
        args=["src/server.py"],
        cwd="/path/to/uml-diagram"
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the session
            await session.initialize()
            
            # Generate UML from directory
            result = await session.call_tool(
                "generate_cpp_uml",
                {"path": "/path/to/cpp/project"}
            )
            
            print("Generated UML:")
            print(result.content[0].text)

# Run the example
asyncio.run(use_uml_generator())

Requirements

System Requirements

• Python: 3.10 or higher
• Operating System: Windows, Linux, macOS
• Memory: Minimum 512MB RAM (more for large codebases)

Dependencies

Core Dependencies (included in pyproject.toml)

• fastmcp>=0.2.0 - For MCP server functionality

Python Standard Library (no installation needed)

• os - File system operations
• re - Regular expression parsing
• typing - Type hints
• json - JSON handling (middleware)
• base64 - Encoding (middleware)
• urllib.parse - URL parsing (middleware)

Development Dependencies (optional)

# For development and testing
pip install pytest black flake8

PlantUML Rendering (optional)

To view the generated .puml files:

• VS Code: Install PlantUML extension
• Online: Use PlantUML Online Server
• Local: Install PlantUML with Java runtime

Output Examples

Generated PlantUML Structure

The tool generates clean, well-formatted PlantUML diagrams:

@startuml
class Animal {
    + virtual makeSound() = 0
    + virtual ~Animal() = default
    # std::string name_
    - int age_
}

class Dog {
    + makeSound() override
    + bark()
    - std::string breed_
    - bool isTrained_
}

class Cat {
    + makeSound() override
    + purr()
    - bool isIndoor_
}

Animal <|-- Dog
Animal <|-- Cat
@enduml

Symbol Meanings

• + Public members
• - Private members
• # Protected members
• <|-- Inheritance relationship (base <|-- derived)

File Output

• Script mode: Creates uml_output.puml in current directory
• Module mode: Returns PlantUML string for programmatic use
• MCP mode: Returns PlantUML string via MCP protocol

Project Structure

uml-diagram/
├── src/
│   ├── server.py           # MCP server implementation
│   ├── uml_generate.py     # Core UML generation logic
│   └── middleware.py       # HTTP request middleware
├── Dockerfile              # Container configuration
├── pyproject.toml          # Project dependencies and metadata
├── smithery.yaml           # Smithery platform configuration
├── README.md               # This file
└── LICENSE                 # MIT license

Supported C++ Features

Class Detection

• ✅ Class definitions
• ✅ Struct definitions
• ✅ Template classes (generics stripped for PlantUML compatibility)
• ✅ Nested classes (basic support)

Inheritance

• ✅ Single inheritance
• ✅ Multiple inheritance
• ✅ Public inheritance
• ✅ Protected inheritance
• ✅ Private inheritance

Member Detection

• ✅ Public, private, protected members
• ✅ Methods and functions
• ✅ Variables and fields
• ✅ Virtual and pure virtual methods
• ✅ Constructors and destructors
• ✅ Static members (basic support)

Limitations

• ⚠️ Complex template specializations may not be fully captured
• ⚠️ Preprocessor macros are not expanded
• ⚠️ Forward declarations without definitions are skipped
• ⚠️ Some complex C++ syntax may require manual review

Configuration

Environment Variables

• TRANSPORT: Set to "http" for HTTP mode, "stdio" for stdio mode (default)
• PORT: HTTP server port (default: 8081)
• SERVER_TOKEN: Optional authentication token for stdio mode

Smithery Platform

This project includes smithery.yaml for deployment on the Smithery platform:

• Containerized runtime
• HTTP transport mode
• Auto-scaling support

Troubleshooting

Common Issues

"No C++ classes found" message:

• Verify the path contains .cpp, .hpp, .h, .cc, or .cxx files
• Check file encoding (UTF-8 recommended)
• Ensure class definitions use standard C++ syntax

Empty or malformed UML output:

• Review C++ syntax for unsupported constructs
• Check for balanced braces in class definitions
• Verify inheritance syntax follows standard format

MCP server connection issues:

• Ensure correct transport mode (http vs stdio)
• Check port availability (8081 by default)
• Verify dependencies are installed (fastmcp)

Debug Mode

Enable verbose logging by modifying server.py:

# Add debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Commit: git commit -am 'Add feature-name'
5. Push: git push origin feature-name
6. Create a Pull Request

Development Setup

# Clone and setup development environment
git clone https://github.com/hydavinci/uml-diagram.git
cd uml-diagram

# Install in development mode
pip install -e .

# Run tests (if available)
python -m pytest

# Format code
black src/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v0.1.0

• Initial release
• Directory-based UML generation
• Content-based UML generation
• MCP server with HTTP and stdio transport
• Docker containerization support
• PlantUML output format
• Class, inheritance, and member detection

---

Author: hydavinci
Repository: https://github.com/hydavinci/uml-diagram