ohm-mcp について
ohm-mcpは、Pythonプロジェクト向けのASTベースの分析・リファクタリングMCPサーバーです。開発者やコーディングエージェント向けに、設計・型・性能の検査と、変更の自動適用およびロールバックを提供します。
主な機能
- 01ASTによるメソッド抽出とシンボル変更
- 02デッドコードと重複コードの検出
- 03アーキテクチャとSOLIDの分析
- 04型カバレッジ分析とテスト生成
- 05性能パターンの検出
- 06自動適用、操作履歴、ロールバック
活用シーン
- 01メソッドを抽出してパッチを生成
- 02プロジェクト全体のシンボル名やインポートを変更
- 03未使用コードや重複実装を特定
- 04型カバレッジを確認してテストを生成
MCP 対応
MCP対応クライアントにPythonの分析・リファクタリングツールを提供します。GitHub Copilot、Cursor、Clineなどで利用できます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
OHM-MCP
AI を活用した Python のリファクタリングとコード品質のアシスタント
GitHub Copilot、Cursor IDE、Cline、および MCP 互換の AI アシスタントで動作します。
✨ 主な機能
🏗️ アーキテクチャ
🔧 コード品質
|
📊 型安全性
⚡ パフォーマンス
🤖 自動化
|
🚀 クイックスタート
インストール
📦 推奨:NPM 方式(依存関係を自動インストール)
インストールは不要です!NPX を使うと、最新バージョンを自動的に実行できます。
npx -y ohm-mcp@latest
これが最も簡単な始め方です。AI アシスタントに設定を追加するだけです(下記のIDE の設定を参照)。
MCP Registry: 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 Chat を開きます
#と入力し、ohm-mcpツールを選択します- 「このファイルを分析して、リファクタリング案を提案してください」と尋ねます
🟣 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 Chat を開きます(Cmd+L / Ctrl+L)
- ツールは自動的に利用可能になります
- 「ohm-mcp を使ってデッドコードを検出してください」と尋ねます
🟢 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 パネルを開きます
- エージェントのコンテキストでツールを利用できます
- 「型カバレッジを分析して、改善案を提案してください」と尋ねます
🟠 NPX を使った Antigravity
グローバル(npm への公開後):
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
使い方:
- Antigravity でツールを自動的に利用できます
- 「ohm-mcp を使ってアーキテクチャを分析してください」と尋ねます
🔴 NPX を使った Roo Code
グローバル(npm への公開後):
{
"mcpServers": {
"ohm-mcp": {
"command": "npx",
"args": ["-y", "ohm-mcp@latest"]
}
}
}
使い方:
- Roo Code パネルを開きます
- エージェントのコンテキストでツールを利用できます
- 「ohm-mcp を使って重複を検出してください」と尋ねます
⚫ NPX を使った Codex VS Code
設定(config.toml):
[mcp_servers.ohm-mcp]
args = ["-y", "ohm-mcp@latest"]
command = "npx"
使い方:
- Codex パネルを開きます
- ツールは自動的に利用可能になります
- 「ohm-mcp を使ってデザインパターンを提案してください」と尋ねます
🟡 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 パネルを開きます
- エージェントのコンテキストでツールを利用できます
- 「リファクタリングに ohm-mcp を使ってください」と尋ねます
🐍 オプション 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 Chat を開きます
#と入力し、ohm-mcpツールを選択します- 「このファイルを分析して、リファクタリング案を提案してください」と尋ねます
🟣 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 Chat を開きます(Cmd+L / Ctrl+L)
- ツールは自動的に利用可能になります
- 「ohm-mcp を使ってデッドコードを検出してください」と尋ねます
🟢 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 パネルを開きます
- エージェントのコンテキストでツールを利用できます
- 「型カバレッジを分析して、改善案を提案してください」と尋ねます
🔧 その他の MCP 対応クライアント
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 アシスタントのチャットで、現在のファイルに対して #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%)
- ✅ 命名の競合を検出
- ✅ 適用前にすべての出現箇所を表示
- ✅ docstring とコメントを更新
📊 型カバレッジ分析
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 チェーンには Strategy パターン
- ✅ オブジェクト生成の繰り返しには Factory パターン
- ✅ コールバック地獄には Observer パターン
- ✅ 横断的関心事には Decorator パターン
🔧 インポートのリファクタリング
Use #ohm-mcp.refactor_imports to update all files in /path/to/project from "old.module" to "new.module"
以下に対応します:
- ✅ 直接インポート(
import old.module) - ✅ from インポート(
from old.module import X) - ✅ サブモジュールのインポート
- ✅ インポートのエイリアス
🎯 主要なツール(全30種類)
📋 全般的な分析と計画(4ツール)
| ツール | 目的 | 出力 |
|---|---|---|
analyze_codebase | コードを包括的に分析 | 問題点+リファクタリング計画 |
propose_function_refactor | 関数単位のリファクタリングを計画 | 詳細なリファクタリング案 |
explain_refactoring | リファクタリングのパターンを説明 | 学習のためのガイダンス |
create_refactor_patch | 統合差分パッチを生成 | パッチファイル |
🏗️ アーキテクチャと設計(4ツール)
| ツール | 目的 | 出力 |
|---|---|---|
analyze_architecture | God Object、SOLID 原則違反を検出 | 詳細な問題レポート |
suggest_design_patterns | パターン(Strategy、Factory、Observer)を推奨 | パターンの提案+例 |
analyze_tight_coupling | 密結合の問題を検出 | DI の推奨事項 |
suggest_di_refactor | DI コードを生成 | リファクタリング前後の比較 |
🔧 コード品質とリファクタリング(10ツール)
| ツール | 目的 | 主な機能 |
|---|---|---|
extract_method_ast | コードを関数に抽出 | 100% AST ベースの精度 |
suggest_extractable_methods | 抽出可能なブロックを検出 | 凝集度のスコアリング |
detect_dead_code | 未使用コードを検出 | 5種類のデッドコード |
refactor_imports | プロジェクト全体のインポートを更新 | 安全なモジュール名変更 |
refactor_single_file_imports | 1つのファイルのインポートをリファクタリング | 単一ファイルに特化 |
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
📊 型安全性とテスト(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 形式の包括的なダッシュボード
出力プレビュー:
📊 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 | 違反を検出し、具体的な修正方法を提示します |
| 🚫 見落としなし | 分析 → 計画 → 検証 |
🔌 IDE との互換性
|
🤖 あらゆる MCP クライアント ✅ 標準プロトコル ✅ 簡単なセットアップ ✅ すべての MCP 互換 AI アシスタントで動作します |
📊 比較
| 機能 | OHM MCP | 従来のツール |
|---|---|---|
| 精度 | 100% AST | 約70%の正規表現 |
| 安全性 | バックアップ/ロールバックを自動実行 | 手動 |
| テスト | 自動生成 | 手動 |
| 自動化 | 完全対応 | 提案のみ |
| ダッシュボード | HTML/JSON/MD | テキストログ |
| IDE サポート | Copilot/Cursor/Cline | 限定的 |
🎯 ユースケース
| 👨💻 開発者 • レガシーコードを安全にリファクタリング • デッドコードを検出 • パフォーマンスを最適化 | 👥 チーム • 技術的負債を追跡 • 標準を徹底 • デザインパターン | 🚀 CI/CD • 品質ゲート • 傾向の追跡 • 問題のある PR をブロック |
📈 メトリクス
✅ 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 接続の問題
-
Python のパスを確認します:
which python # Unix/Mac where python # Windows -
MCP サーバーを直接テストします:
python -m ohm_mcp.server -
ログを確認します:
- VS Code:出力パネルを確認します
- Cursor:Cursor のログを確認します
- Cline:Cline の設定パネルを確認します
-
よくある問題:
- ❌
commandに相対パスを指定している → 絶対パスを使用します - ❌ 仮想環境が見つからない → 先に venv を有効化します
- ❌ Cline の
cwdが正しくない → 絶対パスで指定する必要があります
- ❌
🤝 コントリビューション
提出前に実行します:
./static_analyser.sh # Runs ruff, mypy, pylint, flake8
pytest # All tests must pass
🙏 クレジット
Model Context Protocol • Python AST を使用して構築 • GitHub Copilot、Cursor IDE、Cline と互換性があります
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。