🚀 OHM-MCP
由人工智能驅動的Python代碼重構與質量輔助工具
可與 GitHub Copilot、Cursor IDE、Cline 以及任何支持MCP的AI助手協同工作。
✨ 主要特性
| 特性分類 |
具體內容 |
| 架構分析 |
- 上帝對象檢測
- SOLID原則違反分析
- 設計模式建議
- 依賴注入重構 |
| 代碼質量 |
- AST提取方法（100%準確）
- 死代碼消除
- 導入語句重構
- 符號重命名（全項目範圍）
- 代碼重複檢測 |
| 類型安全 |
- 類型覆蓋率分析
- 類型存根生成
- 自動測試生成 |
| 性能優化 |
- O(n²)模式檢測
- 熱點分析
- 覆蓋率驅動的優先級排序 |
| 自動化操作 |
- 自動應用並支持回滾
- 操作歷史記錄
- 質量儀表盤 |
🚀 快速開始
安裝
📦 推薦：NPM方法（自動安裝依賴）
無需安裝！使用NPX自動運行最新版本：
npx -y ohm-mcp@latest
這是最簡單的開始方式。只需將配置添加到你的AI助手（見下面的 IDE配置）。
MCP註冊信息：mcp-name: io.github.Murugarajr/ohm-mcp
🐍 可選：PyPI方法（用於本地開發）
當你需要以下情況時使用此方法：
- 在本地使用Python包進行開發
- 使用特定的Python虛擬環境
- 從源代碼安裝以進行定製
從PyPI安裝：
pip install ohm-mcp
從源代碼安裝（用於開發）：
pip install -e .
IDE配置
📦 選項1：NPX（推薦 - 自動安裝依賴）
🔵 使用NPX配置GitHub Copilot (VS Code)
發佈到npm後：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["ohm-mcp@latest"]
}
}
}
本地開發時：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["--package", "/path/to/ohm-mcp-npm", "ohm-mcp"]
}
}
}
使用方法：
- 打開Copilot聊天窗口
- 輸入
# 並選擇 ohm-mcp 工具
- 輸入："Analyze this file and suggest refactorings"
🟣 使用NPX配置Cursor IDE
全局配置（發佈到npm後）：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"]
}
}
}
本地開發時：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["--package", "/path/to/ohm-mcp-npm", "ohm-mcp"]
}
}
}
使用方法：
- 打開Cursor聊天窗口（Cmd+L / Ctrl+L）
- 工具會自動可用
- 輸入："Use ohm-mcp to detect dead code"
🟢 使用NPX配置Cline (VS Code擴展)
全局配置（發佈到npm後）：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"]
}
}
}
本地開發時：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["--package", "/path/to/ohm-mcp-npm", "ohm-mcp"]
}
}
}
使用方法：
- 打開Cline面板
- 工具在代理上下文中可用
- 輸入："Analyze type coverage and suggest improvements"
🟠 使用NPX配置Antigravity
全局配置（發佈到npm後）：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
使用方法：
- 工具在Antigravity中自動可用
- 輸入："Use ohm-mcp to analyze architecture"
🔴 使用NPX配置Roo Code
全局配置（發佈到npm後）：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"]
}
}
}
使用方法：
- 打開Roo Code面板
- 工具在代理上下文中可用
- 輸入："Use ohm-mcp to detect duplicates"
⚫ 使用NPX配置Codex VS Code
配置文件（config.toml）：
[mcp_servers.ohm-mcp]
args = ["-y", "ohm-mcp@latest"]
command = "npx"
使用方法：
- 打開Codex面板
- 工具自動可用
- 輸入："Use ohm-mcp to suggest design patterns"
🟡 使用NPX配置Kilo Code（本地/全局）
本地配置（使用虛擬環境進行本地開發）：
{
"mcpServers": {
"ohm-mcp": {
"command": "/Users/username/project/venv/bin/python",
"args": ["-m", "ohm_mcp.server"],
"disabled": false,
"alwaysAllow": []
}
}
}
全局配置（發佈到npm後）：
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"]
}
}
}
使用方法：
- 打開Kilo Code面板
- 工具在代理上下文中可用
- 輸入："Use ohm-mcp for refactoring"
🐍 選項2：直接使用Python（手動設置）
🔵 使用Python配置GitHub Copilot (VS Code)
首先安裝：pip install ohm-mcp
然後添加到 .vscode/mcp.json：
{
"servers": {
"ohm-mcp": {
"command": "python",
"args": ["-m", "ohm_mcp.server"]
}
},
"inputs": []
}
使用方法：
- 打開Copilot聊天窗口
- 輸入
# 並選擇 ohm-mcp 工具
- 輸入："Analyze this file and suggest refactorings"
🟣 使用Python配置Cursor IDE
首先安裝：pip install ohm-mcp
然後添加到Cursor的MCP設置文件（.cursorrules 或MCP配置）：
{
"mcpServers": {
"ohm-mcp": {
"command": "python",
"args": ["-m", "ohm_mcp.server"]
}
},
"inputs": []
}
使用虛擬環境的示例：
{
"mcpServers": {
"ohm-mcp": {
"command": "/Users/username/projects/venv/bin/python",
"args": ["-m", "ohm_mcp.server"]
}
}
}
使用方法：
- 打開Cursor聊天窗口（Cmd+L / Ctrl+L）
- 工具會自動可用
- 輸入："Use ohm-mcp to detect dead code"
🟢 使用Python配置Cline (VS Code擴展)
首先安裝：pip install ohm-mcp
然後添加到Cline的MCP設置中：
{
"mcpServers": {
"ohm-mcp": {
"command": "python",
"args": ["-m", "ohm_mcp.server"]
}
}
}
使用虛擬環境的示例：
{
"mcpServers": {
"ohm-mcp": {
"command": "/Users/username/projects/venv/bin/python",
"args": ["-m", "ohm_mcp.server"]
}
}
}
注意：Cline要求 command 和 cwd 都使用絕對路徑。
使用方法：
- 打開Cline面板
- 工具在代理上下文中可用
- 輸入："Analyze type coverage and suggest improvements"
🔧 其他支持MCP的客戶端
任何支持MCP的客戶端都可以使用此服務器。通用配置如下：
{
"mcpServers": {
"ohm-mcp": {
"command": "<python-interpreter-path>",
"args": ["<path-to-mcp_server.py>"],
"cwd": "<project-directory>"
}
}
}
查找Python路徑：
which python
which python3
where python
💻 使用示例
配置完成後，只需在AI助手聊天中使用以下格式引用工具：使用 #ohm-mcp.tool_name 處理當前文件或 @file_name.py
🗑️ 查找死代碼
Use #ohm-mcp.detect_dead_code on @utils.py
這將檢測：
- ✅ 未使用的導入（從未被引用的導入語句）
- ✅ 未使用的變量（已賦值但從未被讀取）
- ✅ 不可達代碼（在return/raise/break/continue之後）
- ✅ 未使用的函數（已定義但從未被調用）
- ✅ 被遮蔽的變量（內部作用域隱藏了外部作用域的變量）
📋 代碼重複檢測
Use #ohm-mcp.detect_code_duplicates to find duplicates in /path/to/project
查找：
- ✅ 完全重複的代碼（100%相同的代碼塊）
- ✅ 近似重複的代碼（相似度達90%以上）
- ✅ 重複的函數（結構相同，名稱不同）
- ✅ 提供消除重複的重構建議
🏗️ 架構分析
Analyze architecture of @my_module.py using #ohm-mcp.analyze_architecture
檢測：
- ✅ 上帝對象（承擔過多職責的類）
- ✅ SOLID原則的違反情況
- ✅ 循環依賴
- ✅ 高耦合問題
✂️ 提取方法重構
Use #ohm-mcp.extract_method_ast to extract lines 45-60 from @handler.py into a new function called "process_request"
自動完成：
- ✅ 檢測所需參數
- ✅ 識別返回值
- ✅ 生成重構後的代碼
- ✅ 創建統一的差異補丁
🔄 安全符號重命名
Use #ohm-mcp.rename_symbol to rename "old_function_name" to "new_function_name" in /path/to/project
特點：
- ✅ 基於AST（100%準確）
- ✅ 檢測命名衝突
- ✅ 在應用更改前顯示所有出現的位置
- ✅ 更新文檔字符串和註釋
📊 類型覆蓋率分析
Analyze type hints in @module.py using #ohm-mcp.analyze_type_hints
提供：
- ✅ 覆蓋率百分比和等級
- ✅ 缺少類型提示的函數
- ✅ 建議的類型註解
- ✅ 帶有優先級的遷移計劃
⚡ 性能優化
Use #ohm-mcp.analyze_performance on @slow_module.py
檢測：
- ✅ 嵌套循環（O(n²)複雜度）
- ✅ 二次列表操作
- ✅ 重複的函數調用（缺少緩存）
- ✅ 可變的默認參數
- ✅ 低效的字符串拼接
🧪 自動生成測試
Generate tests for @calculator.py using #ohm-mcp.generate_characterization_tests
創建：
- ✅ 正常路徑測試用例
- ✅ 邊界情況（None、零、負數、空值）
- ✅ 可直接運行的pytest代碼
- ✅ 在重構前保留現有行為
🎨 設計模式建議
Suggest design patterns for @legacy_code.py using #ohm-mcp.suggest_design_patterns
推薦：
- ✅ 針對長if/elif鏈的策略模式
- ✅ 針對重複對象創建的工廠模式
- ✅ 針對回調地獄的觀察者模式
- ✅ 針對橫切關注點的裝飾器模式
🔧 導入語句重構
Use #ohm-mcp.refactor_imports to update all files in /path/to/project from "old.module" to "new.module"
處理：
- ✅ 直接導入（
import old.module）
- ✅ 從導入（
from old.module import X）
- ✅ 子模塊導入
- ✅ 導入別名
🎯 關鍵工具（共30個）
📋 通用分析與規劃（4個工具）
| 工具 |
用途 |
輸出 |
analyze_codebase |
全面的代碼分析 |
問題 + 重構計劃 |
propose_function_refactor |
函數級別的重構規劃 |
詳細的重構建議 |
explain_refactoring |
解釋重構模式 |
教育性指導 |
create_refactor_patch |
生成統一的差異補丁 |
補丁文件 |
🏗️ 架構與設計（4個工具）
| 工具 |
用途 |
輸出 |
analyze_architecture |
檢測上帝對象、SOLID原則違反情況 |
詳細的問題報告 |
suggest_design_patterns |
推薦設計模式（策略、工廠、觀察者） |
模式建議 + 示例 |
analyze_tight_coupling |
查找耦合問題 |
依賴注入建議 |
suggest_di_refactor |
生成依賴注入代碼 |
重構前後對比 |
🔧 代碼質量與重構（10個工具）
| 工具 |
用途 |
關鍵特性 |
extract_method_ast |
將代碼提取到函數中 |
100%基於AST的準確性 |
suggest_extractable_methods |
查找可提取的代碼塊 |
內聚性評分 |
detect_dead_code |
查找未使用的代碼 |
5種類型的死代碼 |
refactor_imports |
全項目範圍更新導入語句 |
安全的模塊重命名 |
refactor_single_file_imports |
重構單個文件中的導入語句 |
專注於單個文件 |
analyze_wildcard_imports |
查找通配符導入 |
顯式替換方案 |
rename_symbol |
在代碼庫中重命名符號 |
衝突檢測 |
detect_code_duplicates |
查找違反DRY原則的代碼 |
完全重複 + 近似重複 |
extract_function_code |
提取單個函數的代碼 |
代碼提取工具 |
apply_function_refactor |
應用函數級別的重構 |
直接修改代碼 |
示例 - 提取方法：
result = extract_method_ast(code, 45, 60, "calculate_total")
📊 類型安全與測試（5個工具）
| 工具 |
用途 |
好處 |
analyze_type_hints |
檢查類型覆蓋率 |
遷移計劃 |
generate_type_stub |
創建 .pyi 文件 |
漸進式類型化 |
generate_characterization_tests |
自動生成測試 |
安全的重構 |
generate_test_for_function |
為單個函數生成測試 |
有針對性的測試 |
suggest_tests |
建議測試策略 |
測試規劃 |
⚡ 性能與優先級排序（2個工具）
| 工具 |
用途 |
檢測內容 |
analyze_performance |
查找性能瓶頸 |
嵌套循環、可變默認參數、O(n²)複雜度 |
prioritize_by_coverage |
基於風險的優先級排序 |
高風險未覆蓋的代碼 |
🤖 自動化執行與歷史記錄（4個工具）
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]
| 工具 |
用途 |
apply_refactoring |
自動應用重構並進行安全檢查 |
rollback_refactoring |
回滾之前的重構 |
show_refactoring_history |
查看重構審計記錄 |
cleanup_old_backups |
清理舊的備份文件 |
特性：
- ✅ 更改前自動備份
- ✅ 測試執行驗證
- ✅ 失敗時自動回滾
- ✅ 完整的審計記錄
- ✅ 自動清理備份文件
📈 指標與報告（1個工具）
generate_quality_report - 以HTML/Markdown/JSON格式生成全面的儀表盤
輸出預覽：
📊 健康評分: 85/100（良好）
📁 文件數量: 47 | 代碼行數: 12,450 | 技術債務: 23分
📊 類型覆蓋率: 67%
🗑️ 死代碼: 8個導入、12個變量、3個函數
⚡ 性能問題: 4個嵌套循環、2個可變默認參數
📋 重複代碼: 3處完全重複、5處近似重複
可視化儀表盤：
- 🎨 圓形健康指標
- 📊 顏色編碼的指標（🟢🟡🔴）
- 📈 趨勢跟蹤功能
- 🔗 支持CI/CD集成（JSON導出）
💡 常見工作流程
1️⃣ 安全重構
generate_characterization_tests → pytest → extract_method_ast → pytest
2️⃣ 消除代碼重複
detect_code_duplicates → review suggestions → extract_method_ast
3️⃣ 類型遷移
analyze_type_hints → follow migration plan → generate_type_stub
4️⃣ 性能優化
analyze_performance → prioritize_by_coverage → apply fixes
5️⃣ 模塊重構
refactor_imports(old="myapp.old", new="myapp.new") → review patches
6️⃣ 符號重命名
rename_symbol(old="calc", new="calculate", preview_only=True) → apply
7️⃣ 質量跟蹤
generate_quality_report(format="html") → open dashboard → track trends
🎨 可視化示例
質量儀表盤預覽
┌─────────────────────────────────────────────┐
│ 🔍 代碼質量儀表盤 │
├─────────────────────────────────────────────┤
│ │
│ ╭─────────╮ 📁 概覽 │
│ │ 85 │ 文件數量: 47 │
│ │ /100 │ 代碼行數: 12,450 │
│ ╰─────────╯ 技術債務: 23 │
│ 健康評分 │
│ │
├─────────────────────────────────────────────┤
│ 📊 類型覆蓋率 ⚡ 性能指標 │
│ ████████░░ 67% 🔴 4個嵌套循環 │
│ 120/180 已類型化 🟡 2個可變參數 │
├─────────────────────────────────────────────┤
│ 🗑️ 死代碼 📋 重複代碼 │
│ 8個導入 3處完全重複 │
│ 12個變量 5處近似重複 │
│ 3個函數 │
└─────────────────────────────────────────────┘
符號重命名預覽
# 之前
- def calc(x, y):
- return x + y
- result = calc(5, 3)
# 之後
+ def calculate_sum(x, y):
+ return x + y
+ result = calculate_sum(5, 3)
✅ 1個函數已重命名
✅ 3個調用位置已更新
✅ 未檢測到衝突
🧠 設計原則
| 原則 |
實現方式 |
| 🧪 測試優先 |
在重構前自動生成特徵測試 |
| ↩️ 可回滾 |
每次更改都有備份和回滾功能 |
| 🎯 基於AST驅動 |
100%準確（不使用正則表達式） |
| 📊 風險感知 |
根據覆蓋率和複雜度進行優先級排序 |
| 🏛️ 遵循SOLID原則 |
檢測違反情況並提供具體修復方案 |
| 🚫 避免盲目操作 |
分析 → 規劃 → 驗證 |
🔌 IDE兼容性
| 兼容性說明 |
🤖 任何支持MCP的客戶端
✅ 標準協議
✅ 易於設置
✅ 可與所有支持MCP的AI助手協同工作 |
📊 對比
| 特性 |
OHM MCP |
傳統工具 |
| 準確性 |
100%基於AST |
約70%基於正則表達式 |
| 安全性 |
自動備份/回滾 |
手動操作 |
| 測試 |
自動生成 |
手動編寫 |
| 自動化程度 |
全面自動化 |
僅提供建議 |
| 儀表盤 |
HTML/JSON/MD格式 |
文本日誌 |
| IDE支持 |
Copilot/Cursor/Cline等 |
有限支持 |
🎯 使用場景
| 用戶群體 |
使用場景 |
| 👨💻 開發者 |
- 安全地重構遺留代碼
- 查找死代碼
- 優化性能 |
| 👥 開發團隊 |
- 跟蹤技術債務
- 強制執行代碼標準
- 應用設計模式 |
| 🚀 CI/CD |
- 質量檢查門控
- 趨勢跟蹤
- 阻止不良PR |
📈 指標
✅ 30個MCP工具
✅ 40多項靜態檢查
✅ 100% AST準確性
✅ 零正則表達式模式
✅ 支持自動執行和回滾
✅ 美觀的儀表盤（HTML/JSON/MD）
✅ 通用MCP兼容性
✅ 支持自動備份的安全重構
🛠️ 故障排除
MCP連接問題
-
驗證Python路徑：
which python
where python
-
直接測試MCP服務器：
python -m ohm_mcp.server
-
查看日誌：
- VS Code：查看輸出面板
- Cursor：查看Cursor日誌
- Cline：查看Cline設置面板
-
常見問題：
- ❌
command 中使用相對路徑 → 使用絕對路徑
- ❌ 缺少虛擬環境 → 先激活虛擬環境
- ❌ Cline的
cwd 路徑錯誤 → 必須使用絕對路徑
🤝 貢獻代碼
提交代碼前請運行以下命令：
./static_analyser.sh
pytest
🙏 致謝
基於 Model Context Protocol、Python AST構建，與GitHub Copilot、Cursor IDE、Cline兼容。
為提升代碼質量而精心打造 ❤️
⭐ 如果這個項目幫助你編寫更簡潔的代碼，請給它點個星！
文檔
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
