OHM MCP

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": "
",
      "args": ["
"],
      "cwd": "
"
    }
  }
}

找到你的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)

🏗️ Architecture & Design (4 tools)

🔧 Code Quality & Refactoring (10 tools)

示例-提取方法：

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

⚡ Performance & Prioritization (2 tools)

🤖 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]

特征：

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

📈 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

______________________________________________________________________

🧠 设计原则

______________________________________________________________________

🔌 IDE兼容性

🤖 Any MCP Client

✅ Standard Protocol

✅ Easy Setup

✅ Works with all MCP-compatible AI assistants

______________________________________________________________________

📊 比较

______________________________________________________________________

🎯 用例

👨‍💻 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

1. 验证Python路径：

   which python  # Unix/Mac
   where python  # Windows

1. 直接测试MCP服务器：

   python -m ohm_mcp.server

1. 检查日志：

- VS代码：检查输出面板 - 游标：检查游标日志 - Cline：检查Cline设置面板

1. 常见问题：

- ❌ 相对路径 command → 使用绝对路径 - ❌ 缺少虚拟环境→ 先激活venv - ❌ 错误 cwd 为克莱恩→ 必须是绝对路径

______________________________________________________________________

🤝 贡献

提交前运行：

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

______________________________________________________________________

🙏 学分

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

______________________________________________________________________

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

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

文档