# MMI Architecture Analyzer
> Model Context Protocol (MCP) server for analyzing C# project architecture quality using the MMI (Modularity Maturity Index) framework by Carola Lilienthal.
## Overview
This MCP server provides automated analysis of .NET/C# projects to assess architecture quality across four critical dimensions from Carola Lilienthal's MMI framework:
- **Dimension 2: Layering** - Validates Clean Architecture layer dependencies
- **Dimension 5: Encapsulation** - Analyzes public vs internal type visibility
- **Dimension 8: Abstraction Levels** - Detects mixing of business logic with technical details
- **Dimension 9: Circular Dependencies** - Identifies dependency cycles using Tarjan's algorithm
## Features
**Token-Optimized Reports**: Compact mode reduces token usage by 66%
**Interactive Heatmap**: D3.js visualization with cycle detection
**Incremental Analysis**: File-hash caching for 70% faster monitoring
**Live Monitoring**: Real-time analysis with trend tracking
**Cycle Detection**: Graph-based circular dependency analysis with visual highlighting
## Installation
### Prerequisites
- Node.js 18 or higher
- Cursor IDE
### Setup
1. Clone this repository:
```bash
git clone https://github.com/lady-logic/mmi-analyzer.git
cd mmi-analyzer
```
2. Install dependencies:
```bash
npm install
```
3. Configure in Cursor:
Add to your Cursor MCP settings (`~/.cursor/config.json` or via Settings → MCP):
```json
{
"mcpServers": {
"mmi-analyzer": {
"command": "node",
"args": ["C:/path/to/mmi-analyzer/src/server.js"]
}
}
}
```
**Note:** Use absolute paths. On Windows, use forward slashes.
4. Restart Cursor
## Usage
The MMI Analyzer provides seven tools accessible via Cursor's AI assistant:
### 1. Complete MMI Analysis
```
analyze_mmi(projectPath: "D:/Projects/MyApp")
analyze_mmi(projectPath: "D:/Projects/MyApp", mode: "detailed") // Full report
```
Runs all four dimension analyses and provides an overall architecture quality score.
### 2. Interactive Architecture Heatmap
```
visualize_architecture(projectPath: "D:/Projects/MyApp")
```
Generates D3.js visualization showing:
- Files as nodes colored by quality score (green=excellent, red=critical)
- Dependencies as links (gray=normal, red=violations, pink=cycles)
- Animated pulsing for circular dependencies
- Interactive filtering by layer or cycles
- Click nodes to see detailed issues
### 3. Circular Dependency Analysis
```
analyze_cycles(projectPath: "D:/Projects/MyApp")
analyze_cycles(projectPath: "D:/Projects/MyApp", mode: "detailed")
```
Detects circular dependencies across the entire project:
- Uses graphlib's Tarjan algorithm for cycle detection
- Analyzes ALL C# dependencies (using statements)
- Severity classification:
- 🔴 **CRITICAL**: Domain layer involved in cycle
- 🟠 **HIGH**: 2-way circular dependency
- 🟡 **MEDIUM**: 3-4 files in cycle
- 🔵 **LOW**: 5+ files in cycle
- Shows complete cycle paths
### 4. Live Monitoring
```
start_monitoring(projectPath: "D:/Projects/MyApp")
get_monitoring_status()
stop_monitoring(projectPath: "D:/Projects/MyApp")
```
Watches `.cs` files and automatically analyzes changes with trend visualization.
### 5. Layering Analysis
```
analyze_layering(projectPath: "D:/Projects/MyApp")
```
Detects Clean Architecture violations (e.g., Domain depending on Infrastructure).
### 6. Encapsulation Analysis
```
analyze_encapsulation(projectPath: "D:/Projects/MyApp")
```
Identifies over-exposed types that should be internal.
### 7. Abstraction Level Analysis
```
analyze_abstraction(projectPath: "D:/Projects/MyApp")
```
Finds mixing of business logic with technical details (SQL, HTTP, File I/O).
## Report Modes
### Compact Mode (Default)
- Token-optimized output (~66% reduction)
- Grouped violations
- Concise recommendations
- Perfect for quick checks and monitoring
### Detailed Mode
- Full violation listings
- Code examples
- Comprehensive tables
- Ideal for documentation and deep analysis
## Example Output
```markdown
# Complete MMI Analysis Report
Overall MMI Score: 4.2/5 (Gut)
## MMI Scorecard
| Dimension | Score | Level | Status |
|------------------------|-------|------------|--------|
| Layering | 5/5 | Exzellent | ✅ |
| Encapsulation | 4/5 | Gut | ✅ |
| Abstraction Levels | 3/5 | Akzeptabel | 🟡 |
| Circular Dependencies | 5/5 | Exzellent | ✅ |
## 🎯 Priority Actions
1. **Fix abstraction mixing** - Remove SQL queries from Domain layer
```
## Heatmap Visualization
The interactive heatmap provides real-time visual feedback:
**Color Coding:**
- 🟢 Green: Excellent (4.5-5.0)
- 🔵 Blue: Good (3.5-4.5)
- 🟠 Orange: Acceptable (2.5-3.5)
- 🔴 Red: Critical (<2.5)
- 🟣 Pink: Circular dependency
**Interactive Features:**
- Drag nodes to rearrange
- Zoom and pan
- Filter by layer or cycles
- Click nodes for detailed issues
- Animated pink pulsing links show cycles
## Architecture
```
mmi-analyzer/
├── src/
│ ├── server.js # MCP server implementation
│ ├── config/
│ │ └── report-config.js # Report mode configuration
│ ├── analyzers/
│ │ ├── layering.js # Dimension 2: Layer dependencies
│ │ ├── encapsulation.js # Dimension 5: Type visibility
│ │ ├── abstraction.js # Dimension 8: Abstraction mixing
│ │ └── cycle-analyzer.js # Dimension 9: Circular dependencies
│ ├── formatters/ # Report formatters (compact/detailed)
│ │ ├── cycle-formatter.js # Cycle-specific formatting
│ │ └── combined-formatter.js # 4D MMI reports
│ ├── monitoring/ # File watching & history
│ ├── visualizations/ # Heatmap generator with cycle viz
│ └── utils/
│ └── file-cache.js # Hash-based caching
├── package.json
└── README.md
```
## Scoring System
**MMI Scores (0-5):**
- **5 - Exzellent**: State-of-the-art architecture
- **4 - Gut**: Strong architecture, minor improvements needed
- **3 - Akzeptabel**: Solid foundation, some refactoring recommended
- **2 - Verbesserungswürdig**: Significant technical debt
- **1 - Schlecht**: Major refactoring required
- **0 - Kritisch**: Architecture fundamentally broken
**Cycle Scoring:**
- 0 cycles = 5 points
- <1% files in cycles = 4 points
- <3% files in cycles = 3 points
- <5% files in cycles = 2 points
- <10% files in cycles = 1 point
- ≥10% files in cycles = 0 points
## Performance
- **Compact reports**: ~2,400 tokens (vs. 7,000 detailed)
- **Monitoring**: Only analyzes changed files (70% reduction)
- **Caching**: MD5 hash-based file tracking
- **Cycle detection**: O(V + E) using Tarjan's SCC algorithm
- **First analysis**: Full scan, subsequent: incremental
## Breaking Cycles
When circular dependencies are detected, the tool suggests resolution strategies:
1. **Dependency Inversion** - Introduce interfaces
2. **Event-Driven Architecture** - Use message bus (e.g., MassTransit)
3. **Extract Common Dependencies** - Create shared module
4. **Merge Components** - Combine artificially separated code
5. **Anti-Corruption Layer** - Add translation layer
## Troubleshooting
### Server not connecting
1. Check absolute paths in Cursor config
2. Verify Node.js version: `node --version` (needs 18+)
3. Check logs: `mmi-analyzer.log` in server directory
### No analysis results
- Ensure the project path contains `.cs` files
- Verify project follows folder structure (`Domain/`, `Application/`, `Infrastructure/`)
### Cache issues
- Delete `.mmi-cache.json` in project root to force full re-analysis
### Cycles not detected
- Ensure files have proper `namespace` declarations
- Check that `using` statements reference project namespaces
- Multiple files can share the same namespace (supported)
## Contributing
Contributions welcome! This is an experimental tool for learning MCP server development.
## License
MIT
## References
- **MMI Framework**: [Carola Lilienthal - Langlebige Softwarearchitekturen](https://www.dpunkt.de/buecher/13125/9783864906091-langlebige-software-architekturen.html)
- **MCP Protocol**: [Anthropic Model Context Protocol](https://modelcontextprotocol.io/)
- **Clean Architecture**: Robert C. Martin
- **Cycle Detection**: Tarjan's Strongly Connected Components algorithm
---
**Status**: Experimental | **Version**: 0.4.0
