ohm-mcp 0.1.5__tar.gz

ohm_mcp-0.1.5/PKG-INFO

@@ -0,0 +1,653 @@
+Metadata-Version: 2.4
+Name: ohm-mcp
+Version: 0.1.5
+Summary: AI-Powered Python Refactoring & Code Quality Assistant - MCP Server with AST-based analysis
+Author-email: Murugaraj <murugaraj@gmail.com>
+Maintainer-email: Murugaraj <murugaraj@gmail.com>
+License: MIT
+Project-URL: Homepage, https://www.ohm-mcp.dev
+Keywords: mcp,model-context-protocol,refactoring,code-quality,ast,python,static-analysis,testing,automation,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=0.1.0
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Murugarajr/ohm-mcp-pypi/refs/heads/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.
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-0.1.0+-green.svg)](https://modelcontextprotocol.io)
+[![AST-Based](https://img.shields.io/badge/AST--Based-100%25-brightgreen.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)]()
+
+</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
+```bash
+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:**
+```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><b>🟣 Cursor IDE with NPX</b></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 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>
+
+**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 Cline panel
+- Tools are available in agent context
+- Ask: "Analyze type coverage and suggest improvements"
+
+</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`:
+```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><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):
+```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><b>🟢 Cline (VS Code Extension) with Python</b></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><b>🔧 Other MCP-Compatible Clients</b></summary>
+
+Any MCP-compatible client can use this server. General configuration:
+
+```json
+{
+  "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>
+
+---
+
+## 🎯 Key Tools
+
+<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 (6 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 |
+| `rename_symbol` | Rename across codebase | Conflict detection |
+| `detect_code_duplicates` | Find DRY violations | Exact + near duplicates |
+
+**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 (4 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 |
+
+</details>
+
+<details>
+<summary><b>⚡ Performance & Coverage (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 (3 tools)</b></summary>
+
+```mermaid
+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`)
+
+</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-duplicates
+```
+
+**Visual Dashboard:**
+- 🎨 Circular health gauge
+- 📊 Color-coded metrics (🟢🟡🔴)
+- 📈 Trend tracking ready
+- 🔗 CI/CD integration (JSON export)
+
+</details>
+
+---
+
+## 💡 Common Workflows
+
+### 1️⃣ **Safe Refactoring**
+```bash
+generate_characterization_tests → pytest → extract_method_ast → pytest
+```
+
+### 2️⃣ **Eliminate Duplication**
+```bash
+detect_code_duplicates → review suggestions → extract_method_ast
+```
+
+### 3️⃣ **Type Migration**
+```bash
+analyze_type_hints → follow migration plan → generate_type_stub
+```
+
+### 4️⃣ **Performance Optimization**
+```bash
+analyze_performance → prioritize_by_coverage → apply fixes
+```
+
+### 5️⃣ **Module Refactoring**
+```bash
+refactor_imports(old="myapp.old", new="myapp.new") → review patches
+```
+
+### 6️⃣ **Symbol Renaming**
+```bash
+rename_symbol(old="calc", new="calculate", preview_only=True) → apply
+```
+
+### 7️⃣ **Quality Tracking**
+```bash
+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
+
+```diff
+# 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
+
+```
+✅ 13 Advanced Capabilities
+✅ 30+ Static Checks
+✅ 100% AST Accuracy
+✅ Zero Regex Patterns
+✅ Automated Execution
+✅ Beautiful Dashboards
+✅ Universal MCP Compatibility
+```
+
+---
+
+## 🛠️ Troubleshooting
+
+<details>
+<summary><b>MCP Connection Issues</b></summary>
+
+1. **Verify Python path:**
+   ```bash
+   which python  # Unix/Mac
+   where python  # Windows
+   ```
+
+2. **Test MCP server directly:**
+   ```bash
+   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
+
+</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](https://modelcontextprotocol.io) • 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!
+
+[Documentation](https://www.ohm-mcp.dev) 
+
+</div>