Findings & checks · 1 flagged
HIGHLong base64-encoded blob hidden in the skill documentationSS-SKILL-INJECT-B64-PAYLOAD-01 · Prompt injection · README.md
A base64 string of 128+ characters appears in a documentation file. Encoded prompt injection hides the hostile instruction in base64 — invisible to keyword filters — and relies on the agent's ability to decode it at runtime. There is no normal authoring reason to embed a multi-hundred-byte base64 blob in skill docs.
- Decode the base64 string and confirm it is not an instruction directed at the agent.
- Move any legitimate binary or signature data into a dedicated file (
*.sig,SIGNATURES) outside the documentation.
Trace & refs
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<div align="center">
<img src="https://raw.githubusercontent.com/murugarajr/ohm-mcp/main/image/ohm-mcp.png" alt="OHM-MCP" width="300">
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
<table> <tr> <td width="50%">
🏗️ 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@latestThis 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:
pip install ohm-mcpInstall from source (for development):
pip install -e .IDE Configuration
#### 📦 Option 1: NPX (Recommended - Auto-installs dependencies)
<details> <summary><b>🔵 GitHub Copilot (VS Code) with NPX</b></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 selectohm-mcptools - Ask: "Analyze this file and suggest refactorings"
</details>
<details> <summary><b>🟣 Cursor IDE with NPX</b></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><b>🟢 Cline (VS Code Extension) with NPX</b></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><b>🟠 Antigravity with NPX</b></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>
<details> <summary><b>🔴 Roo Code with NPX</b></summary>
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><b>⚫ Codex VS Code with NPX</b></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><b>🟡 Kilo Code with NPX (Local/Global)</b></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><b>🔵 GitHub Copilot (VS Code) with Python</b></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 selectohm-mcptools - Ask: "Analyze this file and suggest refactorings"
</details>
<details> <summary><b>🟣 Cursor IDE with Python</b></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><b>🟢 Cline (VS Code Extension) with Python</b></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><b>🔧 Other MCP-Compatible Clients</b></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.pyThis 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/projectFinds:
- ✅ 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_architectureDetects:
- ✅ 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/projectFeatures:
- ✅ 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_hintsProvides:
- ✅ 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.pyDetects:
- ✅ 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_testsCreates:
- ✅ 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_patternsRecommends:
- ✅ 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><b>📋 General Analysis & Planning (4 tools)</b></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><b>🏗️ Architecture & Design (4 tools)</b></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><b>🔧 Code Quality & Refactoring (10 tools)</b></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><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><b>📈 Metrics & Reporting (1 tool)</b></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-duplicatesVisual 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 → pytest2️⃣ Eliminate Duplication
detect_code_duplicates → review suggestions → extract_method_ast3️⃣ Type Migration
analyze_type_hints → follow migration plan → generate_type_stub4️⃣ Performance Optimization
analyze_performance → prioritize_by_coverage → apply fixes5️⃣ Module Refactoring
refactor_imports(old="myapp.old", new="myapp.new") → review patches6️⃣ Symbol Renaming
rename_symbol(old="calc", new="calculate", preview_only=True) → apply7️⃣ 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%"> <b>🤖 Any MCP Client</b><br> ✅ Standard Protocol<br> ✅ Easy Setup<br> ✅ 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><b>👨💻 Developers</b><br>• Refactor legacy code safely<br>• Find dead code<br>• Optimize performance</td> <td><b>👥 Teams</b><br>• Track tech debt<br>• Enforce standards<br>• Design patterns</td> <td><b>🚀 CI/CD</b><br>• Quality gates<br>• Trend tracking<br>• 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><b>MCP Connection Issues</b></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
cwdfor 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
<div align="center">
Made with ❤️ for better code quality
⭐ Star this repo if it helps you write cleaner code!
</div>