Name: Python代码重构与质量分析工具
Author: Murugarajr

使用说明

OHM-MCP

AI驱动的Python重构和代码质量助手

使用 GitHub Copilot, 光标IDE, 克莱恩，以及任何兼容MCP的AI助手。

✨ 核心能力

🏗️ 建筑

上帝物体检测
固体违规分析
设计模式建议
依赖注入重构

🔧 代码质量

AST提取法（100%准确）
死代码消除
导入重构
符号重命名（项目范围）
重复检测

📊 类型安全

类型覆盖分析
类型树桩生成
自动测试生成

⚡ 演出

O（n²）模式检测
热点分析法
覆盖率驱动的优先级

🤖 自动化

使用回滚功能自动应用
操作历史记录
质量仪表盘

🚀 快速开始

安装

📦 推荐：NPM方法（自动安装依赖项）

无需安装！使用NPX自动运行最新版本：

npx -y ohm-mcp@latest

这是最简单的开始方式。只需将配置添加到您的AI助手中（请参阅 IDE配置在......下面

MCP注册表： mcp名称：io.github。Murugarajr/ohm mcp

🐍 备选方案：PyPI方法（用于当地开发）

需要时使用此方法：

使用Python包进行本地开发
使用特定的Python虚拟环境
从源代码安装以进行自定义

从PyPI安装：

pip install ohm-mcp

从源代码安装（用于开发）：

pip install -e .

IDE配置

📦 选项1:NPX（推荐-自动安装依赖关系）

🔵 GitHub Copilot (VS Code) with NPX

发布到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 工具
询问：“分析此文件并建议重构”

🟣 Cursor IDE with NPX

Global（发布到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"]
    }
  }
}

用途：

打开光标聊天（Cmd+L/Ctrl+L）
工具自动可用
询问：“使用欧姆mcp检测死码”

🟢 Cline (VS Code Extension) with NPX

Global（发布到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面板
代理环境中有可用的工具
提问：“分析类型覆盖率并提出改进建议”

🟠 Antigravity with NPX

Global（发布到npm后）：

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

用途：

工具在Antigravity中自动可用
问：“使用ohm-mcp分析架构”

🔴 Roo Code with NPX

Global（发布到npm后）：

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

用途：

打开Roo Code面板
代理环境中有可用的工具
询问：“使用欧姆mcp检测重复项”

⚫ Codex VS Code with NPX

配置（config.toml）：

[mcp_servers.ohm-mcp]
args = ["-y", "ohm-mcp@latest"]
command = "npx"

用途：

打开Codex面板
工具自动可用
问：“使用ohm-mcp建议设计模式”

🟡 Kilo Code with NPX (Local/Global)

本地（用于虚拟环境的本地开发）：

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

Global（发布到npm后）：

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

用途：

打开Kilo Code面板
代理环境中有可用的工具
问：“使用ohm-mcp进行重构”

🐍 选项2：直接Python（手动设置）

🔵 GitHub Copilot (VS Code) with Python

首次安装： pip install ohm-mcp

然后添加到 .vscode/mcp.json:

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

用途：

打开Copilot聊天
类型 # 并选择 ohm-mcp 工具
询问：“分析此文件并建议重构”

🟣 Cursor IDE with Python

首次安装： 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"]
    }
  }
}

用途：

打开光标聊天（Cmd+L/Ctrl+L）
工具自动可用
询问：“使用欧姆mcp检测死码”

🟢 Cline (VS Code Extension) with Python

首次安装： 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面板
代理环境中有可用的工具
提问：“分析类型覆盖率并提出改进建议”

🔧 Other MCP-Compatible Clients

任何兼容MCP的客户端都可以使用此服务器。总体配置：

{
  "mcpServers": {
    "ohm-mcp": {
      "command": "<python-interpreter-path>",
      "args": ["<path-to-mcp_server.py>"],
      "cwd": "<project-directory>"
    }
  }
}

找到你的Python路径：

# Unix/Mac
which python
# or
which python3

# Windows
where python

💡 快速使用示例

配置后，只需使用以下格式在AI助手聊天中引用工具：use #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

创建：

✅ 快乐之路测试用例
✅ 边缘情况（无、零、负、空）
✅ 准备运行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个）

📋 General Analysis & Planning (4 tools)

工具	目的	输出
`analyze_codebase`	全面的代码分析	问题+重构计划
`propose_function_refactor`	功能级重构规划	详细重构建议
`explain_refactoring`	解释重构模式	教育指导
`create_refactor_patch`	生成统一的差异补丁	补丁文件

🏗️ Architecture & Design (4 tools)

工具	目的	输出
`analyze_architecture`	检测上帝之物，SOLID违规	详细问题报告
`suggest_design_patterns`	推荐模式（策略、工厂、观察者）	模式建议+示例
`analyze_tight_coupling`	查找耦合问题	DI建议
`suggest_di_refactor`	生成DI代码	重构前后

🔧 Code Quality & Refactoring (10 tools)

工具	目的	关键功能
`extract_method_ast`	将代码提取到函数中	基于AST的准确率为100%
`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`	应用函数级重构	直接修改代码

示例-提取方法：

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

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

📊 Type Safety & Testing (5 tools)

工具	目的	好处
`analyze_type_hints`	检查类型覆盖率	迁移计划
`generate_type_stub`	创建.pyi文件	逐步键入
`generate_characterization_tests`	自动生成测试	安全重构
`generate_test_for_function`	单功能测试	目标测试
`suggest_tests`	建议测试策略	测试计划

⚡ Performance & Prioritization (2 tools)

工具	目的	检测
`analyze_performance`	查找瓶颈	嵌套循环，可变默认值，O（n²）
`prioritize_by_coverage`	基于风险的优先级排序	高风险未覆盖代码

🤖 Automated Execution & History (4 tools)

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`	清理旧备份文件

特征：

✅ 更改前自动备份
✅ 测试执行验证
✅ 故障时自动回滚
✅ 具有历史记录的完整审计跟踪
✅ 自动备份清理

📈 Metrics & Reporting (1 tool)

generate_quality_report -HTML/Markdown/JSON格式的综合仪表板

输出预览：

📊 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

可视化仪表板：

🎨 圆形健康测量仪
📊 颜色编码指标(🟢🟡🔴)
📈 趋势跟踪就绪
🔗 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

🎨 视觉示例

质量仪表板预览

┌─────────────────────────────────────────────┐
│  🔍 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                                │
└─────────────────────────────────────────────┘

符号重命名预览

# 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

🧠 设计原则

原理	实施
🧪 先测试	重构前自动生成特征测试
↩️ 可逆的	每次更改=备份+回滚功能
🎯 AST驱动	100%准确（无正则表达式）
📊 风险意识	覆盖率+复杂性=优先级
🏛️ SOLID	检测违规行为+具体修复
🚫 无失明	分析→ Plan → 验证

🔌 IDE兼容性

🤖 Any MCP Client
✅ Standard Protocol
✅ Easy Setup
✅ Works with all MCP-compatible AI assistants

📊 比较

功能	OHM MCP	传统工具
准确度	100%AST	~70%正则表达式
安全	自动备份/回滚	手动
测试	自动生成	手动
自动化	完整	仅供参考
仪表板	HTML/JSON/MD	文本日志
IDE支持	复制/光标/临床	有限

🎯 用例

👨‍💻 Developers
• Refactor legacy code safely
• Find dead code
• Optimize performance

👥 Teams
• Track tech debt
• Enforce standards
• Design patterns

🚀 CI/CD
• Quality gates
• Trend tracking
• Block bad PRs

📈 指标

✅ 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

🛠️ 故障排除

MCP Connection Issues

验证Python路径：

which python  # Unix/Mac
where python  # Windows

直接测试MCP服务器：
```
python -m ohm_mcp.server
```
检查日志：
- VS代码：检查输出面板
- 游标：检查游标日志
- Cline：检查Cline设置面板
常见问题：
- ❌ 相对路径 command → 使用绝对路径
- ❌ 缺少虚拟环境→ 先激活venv
- ❌ 错误 cwd 为克莱恩→ 必须是绝对路径

🤝 贡献

提交前运行：

./static_analyser.sh  # Runs ruff, mypy, pylint, flake8
pytest                 # All tests must pass

🙏 学分

建于模型上下文协议 •Python AST•与GitHub Copilot、Cursor IDE、Cline兼容

由...制作❤️ 为了获得更好的代码质量

⭐ 标记此回购 如果它能帮助你编写更简洁的代码！

文档

使用说明

OHM-MCP

✨ 核心能力

🏗️ 建筑

🔧 代码质量

📊 类型安全

⚡ 演出

🤖 自动化

🚀 快速开始

安装

📦 推荐：NPM方法（自动安装依赖项）

🐍 备选方案：PyPI方法（用于当地开发）

IDE配置

📦 选项1:NPX（推荐-自动安装依赖关系）

🐍 选项2：直接Python（手动设置）

💡 快速使用示例

🗑️ 查找死代码

📋 代码重复检测

🏗️ 架构分析

✂️ 提取方法重构

🔄 安全符号重命名

📊 类型覆盖分析

⚡ 性能优化

🧪 自动生成测试

🎨 设计模式建议

🔧 导入重构

🎯 关键工具（共30个）

💡 常见工作流

1️⃣ 安全重构

2️⃣ 消除重复

3️⃣ 类型迁移

4️⃣ 性能优化

5️⃣ 模块重构

6️⃣ 符号重命名

7️⃣ 质量追踪

🎨 视觉示例

质量仪表板预览

符号重命名预览

🧠 设计原则

🔌 IDE兼容性

📊 比较

🎯 用例

📈 指标

🛠️ 故障排除

🤝 贡献

🙏 学分

相关 MCP

代码智能体IDE

TypeScript重构工具

代码辅助工具

代码质量与安全分析MCP服务器

AI代码生成工具

AI代理构建工具