diagenix 0.1.0

AI-Powered Code Diagram Generator - MCP Server

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

✨ 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
• Quick Start
• Available Tools
• Configuration
• Usage Examples
• IDE Integration
• Development
• Troubleshooting
• Contributing
• License

🚀 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

• Model Context Protocol for the MCP specification
• Google Gemini for the AI capabilities
• Mermaid for diagram syntax
• The open-source community

📞 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: docs.diagenix.dev

---

Made with ❤️ by the DiageniX Team

Your codebase, visualized instantly 🔮