🔮 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 roottarget(required): Function name, class name, or process descriptionfile_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 rootorm_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 rootframework(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 rootdiagram_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 rootmodule_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:
- Scan the project structure
- Detect Django framework and dependencies
- Generate a project overview diagram
- 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:
- Find the function in the codebase
- Analyze the logic flow
- Generate a Mermaid flowchart
- 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:
- Find all SQLAlchemy models
- Extract table definitions and relationships
- Generate an ER diagram
- 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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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: support@diagenix.dev
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📖 Documentation: docs.diagenix.dev
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.