OHM-MCP

AI-Powered Python Refactoring & Code Quality Assistant

Works with GitHub Copilot, Cursor IDE, Cline, and any MCP-compatible AI assistant.

---

Core Capabilities

Architecture

• God Object Detection
• SOLID Violation Analysis
• Design Pattern Suggestions
• Dependency Injection Refactoring

Code Quality

• AST Extract Method (100% accurate)
• Dead Code Elimination
• Import Refactoring
• Symbol Renaming (project-wide)
• Duplication Detection

Type Safety

• Type Coverage Analysis
• Type Stub Generation
• Auto Test Generation

Performance

• O(n) Pattern Detection
• Hotspot Analysis
• Coverage-Driven Prioritization

Automation

• Auto-Apply with Rollback
• Operation History
• Quality Dashboard

---

Quick Start

Installation

pip install -e .

IDE Configuration

Add to .vscode/mcp.json:

{
  "servers": {
    "ohm-mcp": {
      "command": "python",
      "args": ["${workspaceFolder}/mcp_server.py"]
    }
  },
  "inputs": []
}

Usage:

• Open Copilot Chat
• Type # and select ohm-mcp tools
• Ask: "Analyze this file and suggest refactorings"

Add to Cursor's MCP settings file (.cursorrules or MCP config):

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "/path/to/your/python",
      "args": [
        "${workspaceFolder}/ohm-mcp/mcp_server.py"
      ]
    }
  },
  "inputs": []
}

Example with virtual environment:

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "/Users/username/projects/venv/bin/python",
      "args": [
        "${workspaceFolder}/ohm-mcp/mcp_server.py"
      ]
    }
  }
}

Usage:

• Open Cursor Chat (Cmd+L / Ctrl+L)
• Tools are automatically available
• Ask: "Use ohm-mcp to detect dead code"

Add to Cline's MCP settings:

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "/path/to/your/python",
      "args": ["mcp_server.py"],
      "cwd": "/absolute/path/to/ohm-mcp"
    }
  }
}

Example with virtual environment:

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "/Users/username/projects/venv/bin/python",
      "args": ["mcp_server.py"],
      "cwd": "/Users/username/projects/ohm-mcp"
    }
  }
}

Note: Cline requires absolute paths for both command and cwd.

Usage:

• Open Cline panel
• Tools are available in agent context
• Ask: "Analyze type coverage and suggest improvements"

Any MCP-compatible client can use this server. General configuration:

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "<python-interpreter-path>",
      "args": ["<path-to-mcp_server.py>"],
      "cwd": "<project-directory>"
    }
  }
}

Finding your Python path:

# Unix/Mac
which python
# or
which python3

# Windows
where python

---

Key Tools

Tool	Purpose	Output
analyze_architecture	Detect God Objects, SOLID violations	Detailed issue report
suggest_design_patterns	Recommend patterns (Strategy, Factory, Observer)	Pattern suggestions + examples
analyze_tight_coupling	Find coupling issues	DI recommendations
suggest_di_refactor	Generate DI code	Before/after refactor

Tool	Purpose	Key Feature
extract_method_ast	Extract code into function	100% AST-based accuracy
suggest_extractable_methods	Find extractable blocks	Cohesion scoring
detect_dead_code	Find unused code	5 types of dead code
refactor_imports	Update imports project-wide	Safe module renaming
rename_symbol	Rename across codebase	Conflict detection
detect_code_duplicates	Find DRY violations	Exact + near duplicates

Example - Extract Method:

# Input: Lines 45-60
result = extract_method_ast(code, 45, 60, "calculate_total")

# Output: Refactored code + patch + auto-detected params/returns

Tool	Purpose	Benefit
analyze_type_hints	Check type coverage	Migration plan
generate_type_stub	Create .pyi files	Gradual typing
generate_characterization_tests	Auto-generate tests	Safe refactoring
generate_test_for_function	Single function tests	Targeted testing

Tool	Purpose	Detects
analyze_performance	Find bottlenecks	Nested loops, mutable defaults, O(n)
prioritize_by_coverage	Risk-based prioritization	High-risk uncovered code

graph LR
    A[apply_refactoring] --> B{Dry Run?}
    B -->|Yes| C[Show Preview]
    B -->|No| D[Create Backup]
    D --> E[Apply Changes]
    E --> F{Run Tests}
    F -->|Pass| G[Success]
    F -->|Fail| H[Auto Rollback]
    H --> I[rollback_refactoring]

Features:

• Automatic backup before changes
• Test execution validation
• Auto-rollback on failure
• Full audit trail (show_refactoring_history)

generate_quality_report - Comprehensive dashboard in HTML/Markdown/JSON

Output Preview:

 Health Score: 85/100 (Good)
 Files: 47 | Lines: 12,450 | Tech Debt: 23 pts

 Type Coverage: 67%
 Dead Code: 8 imports, 12 variables, 3 functions
 Performance: 4 nested loops, 2 mutable defaults
 Duplication: 3 exact, 5 near-duplicates

Visual Dashboard:

• Circular health gauge
• Color-coded metrics ()
• Trend tracking ready
• CI/CD integration (JSON export)

---

Common Workflows

1 Safe Refactoring

generate_characterization_tests  pytest  extract_method_ast  pytest

2 Eliminate Duplication

detect_code_duplicates  review suggestions  extract_method_ast

3 Type Migration

analyze_type_hints  follow migration plan  generate_type_stub

4 Performance Optimization

analyze_performance  prioritize_by_coverage  apply fixes

5 Module Refactoring

refactor_imports(old="myapp.old", new="myapp.new")  review patches

6 Symbol Renaming

rename_symbol(old="calc", new="calculate", preview_only=True)  apply

7 Quality Tracking

generate_quality_report(format="html")  open dashboard  track trends

---

Visual Examples

Quality Dashboard Preview

   Code Quality Dashboard                  

                                             
             Overview          
          85         Files: 47            
         /100        Lines: 12,450        
            Tech Debt: 23        
     Health Score                            
                                             

   Type Coverage        Performance      
   67%          4 nested loops  
  120/180 typed           2 mutable args  

   Dead Code            Duplication      
  8 imports              3 exact            
  12 variables           5 near             
  3 functions                               

Symbol Rename Preview

# Before
- def calc(x, y):
-     return x + y
- result = calc(5, 3)

# After
+ def calculate_sum(x, y):
+     return x + y
+ result = calculate_sum(5, 3)

 1 function renamed
 3 call sites updated
 0 conflicts detected

---

Design Principles

Principle	Implementation
Test-First	Auto-generate characterization tests before refactoring
Reversible	Every change = backup + rollback capability
AST-Driven	100% accurate (no regex)
Risk-Aware	Coverage + complexity = prioritization
SOLID	Detect violations + concrete fixes
No Blindness	Analyze Plan Validate

---

IDE Compatibility

---

Comparison

Feature	OHM MCP	Traditional Tools
Accuracy	100% AST	~70% Regex
Safety	Auto backup/rollback	Manual
Testing	Auto-generates	Manual
Automation	Full	Suggestions only
Dashboard	HTML/JSON/MD	Text logs
IDE Support	Copilot/Cursor/Cline	Limited

---

Use Cases

---

Metrics

 13 Advanced Capabilities
 30+ Static Checks
 100% AST Accuracy
 Zero Regex Patterns
 Automated Execution
 Beautiful Dashboards
 Universal MCP Compatibility

---

Troubleshooting

1. Verify Python path:

   which python  # Unix/Mac
   where python  # Windows
   

2. Test MCP server directly:

   python mcp_server.py
   

3. Check logs:

   • VS Code: Check Output panel
   • Cursor: Check Cursor logs
   • Cline: Check Cline settings panel

4. Common issues:

   • Relative paths in command Use absolute paths
   • Missing virtual environment Activate venv first
   • Wrong cwd for Cline Must be absolute path

---

Contributing

Run before submitting:

./static_analyser.sh  # Runs ruff, mypy, pylint, flake8
pytest                 # All tests must pass

---

Credits

Built with Model Context Protocol Python AST Compatible with GitHub Copilot, Cursor IDE, Cline

---

Made with for better code quality

Star this repo if it helps you write cleaner code!

Documentation