OHM-MCP

AI-Powered Python Refactoring & Code Quality Assistant

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

![MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Murugarajr%2Fohm-mcp/versions/1.0.1) ![Python 3.8+](https://www.python.org/downloads/) ![MCP](https://modelcontextprotocol.io) ![AST-Based]() ![License]()

</div>

---

✨ 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

</td> <td width="50%">

📊 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

</td> </tr> </table>

---

🚀 Quick Start

Installation

📦 Recommended: NPM Method (Auto-installs dependencies)

No installation required! Use NPX to run the latest version automatically:

npx -y ohm-mcp@latest

This is the easiest way to get started. Just add the configuration to your AI assistant (see IDE Configuration below).

MCP Registry: mcp-name: io.github.Murugarajr/ohm-mcp

🐍 Alternative: PyPI Method (For local development)

Use this method when you need to:

Develop locally with the Python package
Use a specific Python virtual environment
Install from source for customization

Install from PyPI: ``bash pip install ohm-mcp ``

Install from source (for development): ``bash pip install -e . ``

IDE Configuration

📦 Option 1: NPX (Recommended - Auto-installs dependencies)

<details> <summary>🔵 GitHub Copilot (VS Code) with NPX</summary>

After publishing to npm: ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["ohm-mcp@latest"] } } } ``

For local development: ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["--package", "/path/to/ohm-mcp-npm", "ohm-mcp"] } } } ``

Usage:

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

</details>

<details> <summary>🟣 Cursor IDE with NPX</summary>

Global (After publishing to npm): ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["-y", "ohm-mcp@latest"] } } } ``

For local development: ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["--package", "/path/to/ohm-mcp-npm", "ohm-mcp"] } } } ``

Usage:

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

</details>

<details> <summary>🟢 Cline (VS Code Extension) with NPX</summary>

Global (After publishing to npm): ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["-y", "ohm-mcp@latest"] } } } ``

For local development: ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["--package", "/path/to/ohm-mcp-npm", "ohm-mcp"] } } } ``

Usage:

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

</details>

<details> <summary>🟠 Antigravity with NPX</summary>

Global (After publishing to npm): ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["-y", "ohm-mcp@latest"], "env": { "PYTHONUNBUFFERED": "1" } } } } ``

Usage:

Tools are automatically available in Antigravity
Ask: "Use ohm-mcp to analyze architecture"

</details>

Global (After publishing to npm): ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["-y", "ohm-mcp@latest"] } } } ``

Usage:

Open Roo Code panel
Tools are available in agent context
Ask: "Use ohm-mcp to detect duplicates"

</details>

<details> <summary>⚫ Codex VS Code with NPX</summary>

Configuration (config.toml): ``toml [mcp_servers.ohm-mcp] args = ["-y", "ohm-mcp@latest"] command = "npx" ``

Usage:

Open Codex panel
Tools are automatically available
Ask: "Use ohm-mcp to suggest design patterns"

</details>

<details> <summary>🟡 Kilo Code with NPX (Local/Global)</summary>

Local (For local development with virtual environment): ``json { "mcpServers": { "ohm-mcp": { "command": "/Users/username/project/venv/bin/python", "args": ["-m", "ohm_mcp.server"], "disabled": false, "alwaysAllow": [] } } } ``

Global (After publishing to npm): ``json { "mcpServers": { "ohm-mcp": { "command": "npx", "args": ["-y", "ohm-mcp@latest"] } } } ``

Usage:

Open Kilo Code panel
Tools are available in agent context
Ask: "Use ohm-mcp for refactoring"

</details>

🐍 Option 2: Direct Python (Manual setup)

<details> <summary>🔵 GitHub Copilot (VS Code) with Python</summary>

First install: pip install ohm-mcp

Then add to .vscode/mcp.json: ``json { "servers": { "ohm-mcp": { "command": "python", "args": ["-m", "ohm_mcp.server"] } }, "inputs": [] } ``

Usage:

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

</details>

<details> <summary>🟣 Cursor IDE with Python</summary>

First install: pip install ohm-mcp

Then add to Cursor's MCP settings file (.cursorrules or MCP config): ``json { "mcpServers": { "ohm-mcp": { "command": "python", "args": ["-m", "ohm_mcp.server"] } }, "inputs": [] } ``

Example with virtual environment: ``json { "mcpServers": { "ohm-mcp": { "command": "/Users/username/projects/venv/bin/python", "args": ["-m", "ohm_mcp.server"] } } } ``

Usage:

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

</details>

<details> <summary>🟢 Cline (VS Code Extension) with Python</summary>

First install: pip install ohm-mcp

Then add to Cline's MCP settings: ``json { "mcpServers": { "ohm-mcp": { "command": "python", "args": ["-m", "ohm_mcp.server"] } } } ``

Example with virtual environment: ``json { "mcpServers": { "ohm-mcp": { "command": "/Users/username/projects/venv/bin/python", "args": ["-m", "ohm_mcp.server"] } } } ``

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"

</details>

<details> <summary>🔧 Other MCP-Compatible Clients</summary>

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

Unix/Mac

which python

or

which python3

Windows

where python ```

</details>

---

💡 Quick Usage Examples

Once configured, simply reference tools in your AI assistant chat using the format: use #ohm-mcp.tool_name on the current file or @file_name.py

🗑️ Find Dead Code

Use #ohm-mcp.detect_dead_code on @utils.py

This will detect:

✅ Unused imports (import statements never referenced)
✅ Unused variables (assigned but never read)
✅ Unreachable code (after return/raise/break/continue)
✅ Unused functions (defined but never called)
✅ Shadowed variables (inner scope hides outer scope variable)

📋 Code Duplication Detection

Use #ohm-mcp.detect_code_duplicates to find duplicates in /path/to/project

Finds:

✅ Exact duplicates (100% identical code blocks)
✅ Near duplicates (90%+ similarity)
✅ Duplicate functions (same structure, different names)
✅ Provides refactoring suggestions to eliminate duplication

🏗️ Architecture Analysis

Analyze architecture of @my_module.py using #ohm-mcp.analyze_architecture

Detects:

✅ God Objects (classes doing too much)
✅ SOLID principle violations
✅ Circular dependencies
✅ High coupling issues

✂️ Extract Method Refactoring

Use #ohm-mcp.extract_method_ast to extract lines 45-60 from @handler.py into a new function called "process_request"

Automatically:

✅ Detects required parameters
✅ Identifies return values
✅ Generates refactored code
✅ Creates unified diff patch

🔄 Safe Symbol Renaming

Use #ohm-mcp.rename_symbol to rename "old_function_name" to "new_function_name" in /path/to/project

Features:

✅ AST-based (100% accurate)
✅ Detects naming conflicts
✅ Shows all occurrences before applying
✅ Updates docstrings and comments

📊 Type Coverage Analysis

Analyze type hints in @module.py using #ohm-mcp.analyze_type_hints

Provides:

✅ Coverage percentage and grade
✅ Functions missing type hints
✅ Suggested type annotations
✅ Migration plan with priorities

⚡ Performance Optimization

Use #ohm-mcp.analyze_performance on @slow_module.py

Detects:

✅ Nested loops (O(n²) complexity)
✅ Quadratic list operations
✅ Repeated function calls (missing caching)
✅ Mutable default arguments
✅ Inefficient string concatenation

🧪 Auto-Generate Tests

Generate tests for @calculator.py using #ohm-mcp.generate_characterization_tests

Creates:

✅ Happy path test cases
✅ Edge cases (None, zero, negative, empty)
✅ Ready-to-run pytest code
✅ Preserves current behavior before refactoring

🎨 Design Pattern Suggestions

Suggest design patterns for @legacy_code.py using #ohm-mcp.suggest_design_patterns

Recommends:

✅ Strategy pattern for long if/elif chains
✅ Factory pattern for repetitive object creation
✅ Observer pattern for callback hell
✅ Decorator pattern for cross-cutting concerns

🔧 Import Refactoring

Use #ohm-mcp.refactor_imports to update all files in /path/to/project from "old.module" to "new.module"

Handles:

✅ Direct imports (import old.module)
✅ From imports (from old.module import X)
✅ Submodule imports
✅ Import aliases

---

🎯 Key Tools (30 Total)

<details> <summary>📋 General Analysis & Planning (4 tools)</summary>

| Tool | Purpose | Output | |------|---------|--------| | analyze_codebase | Comprehensive code analysis | Issues + refactoring plan | | propose_function_refactor | Function-level refactor planning | Detailed refactor proposal | | explain_refactoring | Explain refactoring patterns | Educational guidance | | create_refactor_patch | Generate unified diff patches | Patch file |

</details>

<details> <summary>🏗️ Architecture & Design (4 tools)</summary>

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

</details>

<details> <summary>🔧 Code Quality & Refactoring (10 tools)</summary>

| 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 | | refactor_single_file_imports | Refactor imports in one file | Single file focus | | analyze_wildcard_imports | Find wildcard imports | Explicit replacements | | rename_symbol | Rename across codebase | Conflict detection | | detect_code_duplicates | Find DRY violations | Exact + near duplicates | | extract_function_code | Extract single function code | Code extraction utility | | apply_function_refactor | Apply function-level refactor | Direct code modification |

Example - Extract Method: ```python

Input: Lines 45-60

result = extract_method_ast(code, 45, 60, "calculate_total")

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


</details>

<details>
<summary><b>📊 Type Safety & Testing (5 tools)</b></summary>

| 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 |
| `suggest_tests` | Suggest test strategies | Test planning |

</details>

<details>
<summary><b>⚡ Performance & Prioritization (2 tools)</b></summary>

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

</details>

<details>
<summary><b>🤖 Automated Execution & History (4 tools)</b></summary>

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] ```

| Tool | Purpose | |------|--------| | apply_refactoring | Auto-apply refactoring with safety checks | | rollback_refactoring | Rollback previous refactoring | | show_refactoring_history | View refactoring audit trail | | cleanup_old_backups | Clean up old backup files |

Features:

✅ Automatic backup before changes
✅ Test execution validation
✅ Auto-rollback on failure
✅ Full audit trail with history
✅ Automatic backup cleanup

</details>

<details> <summary>📈 Metrics & Reporting (1 tool)</summary>

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)

</details>

---

💡 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

<table> <tr> <td align="center" width="100%"> 🤖 Any MCP Client ✅ Standard Protocol ✅ Easy Setup ✅ Works with all MCP-compatible AI assistants </td> </tr> </table>

---

📊 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

<table> <tr> <td>👨‍💻 Developers • Refactor legacy code safely • Find dead code • Optimize performance</td> <td>👥 Teams • Track tech debt • Enforce standards • Design patterns</td> <td>🚀 CI/CD • Quality gates • Trend tracking • Block bad PRs</td> </tr> </table>

---

📈 Metrics

✅ 30 MCP Tools
✅ 40+ Static Checks
✅ 100% AST Accuracy
✅ Zero Regex Patterns
✅ Automated Execution with Rollback
✅ Beautiful Dashboards (HTML/JSON/MD)
✅ Universal MCP Compatibility
✅ Safe Refactoring with Auto-Backup

---

🛠️ Troubleshooting

<details> <summary>MCP Connection Issues</summary>

Verify Python path:

   which python  # Unix/Mac
   where python  # Windows

Test MCP server directly:

   python -m ohm_mcp.server

Check logs:

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

Common issues:

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

</details>

---

🤝 Contributing

Run before submitting: ``bash ./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

</div>

ohm-mcp

OHM-MCP

✨ Core Capabilities

🏗️ Architecture

🔧 Code Quality

📊 Type Safety

⚡ Performance

🤖 Automation

🚀 Quick Start

Installation

📦 Recommended: NPM Method (Auto-installs dependencies)

🐍 Alternative: PyPI Method (For local development)

IDE Configuration

📦 Option 1: NPX (Recommended - Auto-installs dependencies)

🐍 Option 2: Direct Python (Manual setup)

Unix/Mac

or

Windows

💡 Quick Usage Examples

🗑️ Find Dead Code

📋 Code Duplication Detection

🏗️ Architecture Analysis

✂️ Extract Method Refactoring

🔄 Safe Symbol Renaming

📊 Type Coverage Analysis

⚡ Performance Optimization

🧪 Auto-Generate Tests

🎨 Design Pattern Suggestions

🔧 Import Refactoring

🎯 Key Tools (30 Total)

Input: Lines 45-60

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

💡 Common Workflows

1️⃣ Safe Refactoring

2️⃣ Eliminate Duplication

3️⃣ Type Migration

4️⃣ Performance Optimization

5️⃣ Module Refactoring

6️⃣ Symbol Renaming

7️⃣ Quality Tracking

🎨 Visual Examples

Quality Dashboard Preview

Symbol Rename Preview

🧠 Design Principles

🔌 IDE Compatibility

📊 Comparison

🎯 Use Cases

📈 Metrics

🛠️ Troubleshooting

🤝 Contributing

🙏 Credits

Related MCP servers

MCP servers by category