diagenix 0.1.0
AI-Powered Code Diagram Generator - MCP Server
License: MIT
Requires Python: >=3.11
Keywords: mcp, diagrams, code-analysis, gemini, mermaid, visualization

# 🔮 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+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

## ✨ 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](#installation)
- [Quick Start](#quick-start)
- [Available Tools](#available-tools)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [IDE Integration](#ide-integration)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## 🚀 Installation

### Prerequisites

- Python 3.11 or higher
- Google Gemini API key ([Get one here](https://makersuite.google.com/app/apikey))

### Install from Source

```bash
# 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)

```bash
pip install diagenix
```

## ⚡ Quick Start

### 1. Set Up API Key

```bash
export GEMINI_API_KEY="your_api_key_here"
```

### 2. Run the Server

```bash
python -m diagenix
```

### 3. Use with Claude Desktop

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

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

```bash
# 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:

```yaml
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](#quick-start) for configuration.

### VS Code

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

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

### Bob IDE

Add to your Bob IDE MCP configuration:

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

## 🧪 Development

### Running Tests

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

# Run tests
pytest

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

### Code Quality

```bash
# 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"**
```bash
# Solution: Set the environment variable
export GEMINI_API_KEY="your_key_here"
```

**Issue: "No module named 'mcp'"**
```bash
# Solution: Install dependencies
pip install -e .
```

**Issue: "Permission denied"**
```bash
# Solution: Check file permissions
chmod +x venv/bin/python
```

### Debug Mode

Enable debug logging:

```bash
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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
- [Google Gemini](https://ai.google.dev/) for the AI capabilities
- [Mermaid](https://mermaid.js.org/) for diagram syntax
- The open-source community

## 📞 Support

- 📧 Email: support@diagenix.dev
- 🐛 Issues: [GitHub Issues](https://github.com/diagenix/diagenix/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/diagenix/diagenix/discussions)
- 📖 Documentation: [docs.diagenix.dev](https://docs.diagenix.dev)

---

**Made with ❤️ by the DiageniX Team**

*Your codebase, visualized instantly* 🔮