MCP Servers

OHM-MCP

AI-powered Python refactoring assistant that provides AST-based code analysis, SOLID violation detection, dead code elimination, type safety analysis, performance optimization, and automated refactoring with rollback capabilities.

README

OHM-MCP

AI-Powered Python Refactoring & Code Quality Assistant

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

</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).

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

pip install ohm-mcp

Install from source (for development):

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:

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "npx",
      "args": ["ohm-mcp@latest"]
    }
  }
}

For local development:

{
  "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):

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "npx",
      "args": ["-y", "ohm-mcp@latest"]
    }
  }
}

For local development:

{
  "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):

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "npx",
      "args": ["-y", "ohm-mcp@latest"]
    }
  }
}

For local development:

{
  "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):

{
  "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):

{
  "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):

[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):

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "/Users/username/project/venv/bin/python",
      "args": ["-m", "ohm_mcp.server"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Global (After publishing to npm):

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

{
  "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):

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "python",
      "args": ["-m", "ohm_mcp.server"]
    }
  },
  "inputs": []
}

Example with virtual environment:

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

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "python",
      "args": ["-m", "ohm_mcp.server"]
    }
  }
}

Example with virtual environment:

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

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

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

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

</details>

<details> <summary>📊 Type Safety & Testing (5 tools)</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>⚡ Performance & Prioritization (2 tools)</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>🤖 Automated Execution & History (4 tools)</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:

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

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

E2B

Using MCP to run code via e2b.

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured