Skip to main content

🔮 DiageniX - AI-Powered Code Diagram Generator

Your codebase, visualized instantly

DiageniX is a production-ready MCP (Model Context Protocol) server that analyzes local codebases and generates intelligent diagrams on-demand using Google Gemini Pro API.

Python 3.11+ License: MIT MCP

✨ Features

  • 🎯 6 Diagram Types: Flowcharts, Class Diagrams, Database Schemas, API Maps, Architecture, and Project Structure
  • 🤖 AI-Powered: Uses Google Gemini Pro for intelligent diagram generation
  • 🔍 Multi-Language Support: Python, JavaScript, TypeScript, and more
  • 📊 Mermaid Output: Industry-standard diagram syntax
  • 🚀 Fast Analysis: Optimized code scanning and caching
  • 🔌 MCP Compatible: Works with Claude Desktop, VS Code, and other MCP clients
  • 🎨 Smart Detection: Automatically detects frameworks, ORMs, and tech stacks

📋 Table of Contents

🚀 Installation

Prerequisites

  • Python 3.11 or higher
  • Google Gemini API key (Get one here)

Install from Source

# Clone the repository
git clone https://github.com/diagenix/diagenix.git
cd diagenix

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Set up environment variables
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

Install from PyPI (Coming Soon)

pip install diagenix

⚡ Quick Start

1. Set Up API Key

export GEMINI_API_KEY="your_api_key_here"

2. Run the Server

python -m diagenix

3. Use with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "diagenix": {
      "command": "python",
      "args": ["-m", "diagenix"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop and start using DiageniX!

🛠️ Available Tools

1. analyze_project

Analyzes project structure and detects technology stack.

Parameters:

  • project_path (required): Absolute path to project root

Example:

Analyze the project at /Users/username/my-project

Output:

  • Project overview with file statistics
  • Detected languages and frameworks
  • Technology stack summary
  • Project structure diagram

2. generate_flowchart

Generates a flowchart for a specific function, class, or process.

Parameters:

  • project_path (required): Absolute path to project root
  • target (required): Function name, class name, or process description
  • file_path (optional): Specific file to analyze

Example:

Generate a flowchart for the 'process_payment' function in /Users/username/my-project

Output:

  • Mermaid flowchart showing logic flow
  • Decision points and branches
  • Function calls and operations

3. generate_database_schema

Generates database schema diagram from models/migrations.

Parameters:

  • project_path (required): Absolute path to project root
  • orm_type (optional): ORM framework (auto, sqlalchemy, django, prisma, sequelize)

Example:

Generate database schema for /Users/username/my-project

Output:

  • ER diagram with tables and relationships
  • Primary and foreign keys
  • Column types and constraints

4. generate_api_diagram

Maps all API endpoints and their relationships.

Parameters:

  • project_path (required): Absolute path to project root
  • framework (optional): Web framework (auto, fastapi, flask, express, django)

Example:

Generate API diagram for /Users/username/my-api

Output:

  • API endpoint map with HTTP methods
  • Route groupings and dependencies
  • Request/response flows

5. generate_architecture

Creates high-level system architecture diagram.

Parameters:

  • project_path (required): Absolute path to project root
  • diagram_type (optional): Architecture style (c4, component, deployment)

Example:

Generate component architecture for /Users/username/my-project

Output:

  • System component diagram
  • Service interactions
  • Technology stack per component

6. generate_class_diagram

Generates UML class diagram for OOP code.

Parameters:

  • project_path (required): Absolute path to project root
  • module_path (optional): Specific module/package to diagram

Example:

Generate class diagram for /Users/username/my-project/src/models

Output:

  • UML class diagram
  • Inheritance and composition relationships
  • Methods and attributes

⚙️ Configuration

Environment Variables

Create a .env file in your project root:

# Required
GEMINI_API_KEY=your_api_key_here

# Optional
MAX_FILE_SIZE_MB=10
CACHE_ENABLED=true
LOG_LEVEL=INFO

YAML Configuration

Edit config/config.yaml for advanced settings:

analysis:
  max_file_size_mb: 10
  ignore_directories:
    - node_modules
    - venv
    - __pycache__

diagrams:
  default_theme: "default"
  max_nodes: 100

llm:
  model: "gemini-pro"
  temperature: 0.3
  max_tokens: 4096

💡 Usage Examples

Example 1: Analyze a Django Project

I want to understand the structure of my Django project at /Users/me/django-blog

DiageniX will:

  1. Scan the project structure
  2. Detect Django framework and dependencies
  3. Generate a project overview diagram
  4. List all models, views, and URLs

Example 2: Generate Flowchart for a Function

Create a flowchart for the 'authenticate_user' function in /Users/me/auth-service

DiageniX will:

  1. Find the function in the codebase
  2. Analyze the logic flow
  3. Generate a Mermaid flowchart
  4. Show decision points and error handling

Example 3: Database Schema from SQLAlchemy Models

Generate database schema for /Users/me/flask-app using SQLAlchemy

DiageniX will:

  1. Find all SQLAlchemy models
  2. Extract table definitions and relationships
  3. Generate an ER diagram
  4. Show foreign keys and constraints

🔌 IDE Integration

Claude Desktop

See Quick Start for configuration.

VS Code

Install the DiageniX extension (coming soon) or use the MCP extension with this config:

{
  "diagenix.mcpServerPath": "python -m diagenix",
  "diagenix.autoAnalyze": true,
  "diagenix.geminiApiKey": "${env:GEMINI_API_KEY}"
}

Bob IDE

Add to your Bob IDE MCP configuration:

{
  "mcp": {
    "servers": {
      "diagenix": {
        "command": "python",
        "args": ["-m", "diagenix"],
        "env": {
          "GEMINI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

🧪 Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=diagenix --cov-report=html

Code Quality

# Format code
black src/

# Lint
ruff check src/

# Type checking
mypy src/

Project Structure

diagenix/
├── src/diagenix/
│   ├── server.py           # MCP server
│   ├── tools/              # MCP tool implementations
│   ├── analyzers/          # Code analyzers
│   ├── llm/                # Gemini integration
│   └── utils/              # Utilities
├── config/                 # Configuration files
├── examples/               # Example configs
├── tests/                  # Test suite
└── README.md

🐛 Troubleshooting

Common Issues

Issue: "GEMINI_API_KEY not found"

# Solution: Set the environment variable
export GEMINI_API_KEY="your_key_here"

Issue: "No module named 'mcp'"

# Solution: Install dependencies
pip install -e .

Issue: "Permission denied"

# Solution: Check file permissions
chmod +x venv/bin/python

Debug Mode

Enable debug logging:

export LOG_LEVEL=DEBUG
python -m diagenix

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow PEP 8 style guide
  • Add tests for new features
  • Update documentation
  • Use type hints
  • Write clear commit messages

📄 License

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

🙏 Acknowledgments

📞 Support


Made with ❤️ by the DiageniX Team

Your codebase, visualized instantly 🔮

Metadata

Release files for diagenix 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for diagenix 0.1.0
File Size Uploaded Provenance Actions
diagenix-0.1.0.tar.gz 39.7 kB Without provenance Details for diagenix-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for diagenix 0.1.0
File Interpreter ABI Platform Actions
diagenix-0.1.0-py3-none-any.whl Python 3 none any Details for diagenix-0.1.0-py3-none-any.whl

Total release size: 85.9 kB

Release files / diagenix-0.1.0.tar.gz

Download URL diagenix-0.1.0.tar.gz
Size 39.7 kB
Tags Source
SHA-256 checksum
How to use checksums
6b2717d8ab18daa9e4112f8ab916d470d577c633bbebcb5af7ee65aabd365a5b
BLAKE2b-256 checksum
How to use checksums
5936c14d227dc5e56a92e97d008b3bc6e932487d419f8b67c2e5e283b2db6145
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Release files / diagenix-0.1.0-py3-none-any.whl

Download URL diagenix-0.1.0-py3-none-any.whl
Size 46.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
44f9023c332f015e5fcc039136193714645358ae266bc082e64dd15507655a06
BLAKE2b-256 checksum
How to use checksums
553df53183af7ff67e9334f054275ce3588e1e70384eb782db1296f0edd41529
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for diagenix 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page