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