Mcp Python Refactoring

MCP Python リファクタリング

Python コードを分析し、コードを自動変更せずに、ガイド付きのリファクタリング提案を提供する Model Context Protocol（MCP）サーバーです。

キーワード

python refactoring code-analysis mcp-server ai-assistant claude rope radon vulture jedi educational mentoring code-quality static-analysis complexity-analysis

このツールは AI コーディングアシスタント（Claude、ChatGPT、Cursor など）と連携し、的確なリファクタリングのガイダンスを提供します。コードを自動で変更するのではなく、Python コードを改善するための具体的な手順を示し、リファクタリングのメンターとして機能します。

このツールの機能

AI コーディングアシスタント向け：

• リファクタリングの候補を構造化された JSON レスポンスで提供します
• 長い関数、複雑度の高いコード、デッドコードを特定します
• メソッド抽出リファクタリングの正確な行番号を示します
• プロフェッショナルなツールを使用して、包括的に分析します

開発者向け：

• リファクタリングの手順を段階的に確認できます
• コード変更を完全に自分で管理できます
• ガイド付きの実践を通じて、リファクタリングのパターンを学べます
• コード品質を体系的に改善できます

従来のツールとの違い

アプローチ	このツール	従来のリファクタリングツール
統合	あらゆる LLM／AI アシスタントと連携します	IDE 固有または単独で動作します
ガイダンス	行番号付きの段階的な手順を示します	自動変更のみを行います
学習	教育的なアプローチでパターンを学べます	学習要素はありません
制御	開発者が完全に管理します	ツールがすべての判断を行います

レジストリへの登録

この MCP サーバーは、MCP エコシステム全体で利用できます。

公式 MCP レジストリ

公開済み・利用可能：registry.modelcontextprotocol.io

• サーバー名：io.github.slamer59/mcp-python-refactoring
• すべての MCP 対応クライアントから検索できます

🟡 Docker MCP レジストリ

プルリクエスト提出済み：docker/mcp-registry #207

• Docker Hub で mcp/mcp-python-refactoring として利用できるようになります
• 署名、SBOM、来歴の追跡など、強化されたセキュリティ機能が含まれます
• Docker Desktop の MCP Toolkit に統合されます

🟡 Awesome MCP Servers リスト

コミュニティによる厳選リスト：

• appcypher/awesome-mcp-servers #180 - 開発ツールのセクション
• punkpeye/awesome-mcp-servers #1321 - コード実行のセクション

📦 インストール方法

すべてのレジストリが公開された後、以下から見つけられます。

• MCP カタログ - 公式レジストリで検索
• Docker Desktop - MCP Toolkit との統合
• コミュニティリスト - GitHub の Awesome リスト
• Docker Hub - mcp/mcp-python-refactoring（強化されたセキュリティ機能付き）

Docker のサポート

Docker MCP カタログでの使用

# Pull from Docker Hub (after registry approval)
docker run -i mcp/mcp-python-refactoring

# Or build locally
docker build -t mcp-python-refactoring .
docker run -i mcp-python-refactoring

Dockerfile

FROM python:3.13-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    && rm -rf /var/lib/apt/lists/*

# Copy project files
COPY pyproject.toml README.md ./
COPY src/ ./src/

# Install the package
RUN pip install --no-cache-dir -e .

# Expose MCP server port (optional, for documentation)
EXPOSE 3000

# Run the MCP server
ENTRYPOINT ["python-refactor", "server"]

インストール

uvx でクイックスタート（推奨）

# Install and run MCP server directly from GitHub
uvx --from git+https://github.com/slamer59/mcp-python-refactoring.git python-refactor server

Claude Code への追加（ワンコマンド）

# Add to Claude Code MCP configuration
claude-code mcp add mcp-python-refactoring uvx --from git+https://github.com/slamer59/mcp-python-refactoring.git python-refactor server

このコマンドを実行した後、Claude Desktop を再起動すると、Claude との会話で Python リファクタリングツールを利用できるようになります。

開発用インストール

# Clone and setup for development
git clone https://github.com/slamer59/mcp-python-refactoring.git
cd mcp-python-refactoring
uv sync

# Run MCP server locally
python -m mcp_refactoring_assistant server

# Or use the entry point after installation
pip install -e .
python-refactor server

CLI の使用方法

python-refactor-cli エントリーポイント（uv sync または pip install -e . でインストール）を使うと、MCP クライアントなしで各分析を単独で実行できます。スクリプトや CI での利用、またはエージェントのシェルからツールを直接実行する場合に便利です。

uv run python-refactor-cli --help

コマンドは機能ごとにグループ化されており、すべて合わせると各 MCP ツールに対応しています。

グループ	コマンド	MCP ツール
file	analyze、long-functions、extraction	analyze_python_file、find_long_functions、get_extraction_guidance
test	coverage、tdd	analyze_test_coverage、tdd_refactoring_guidance
security	scan	analyze_security_and_patterns
package	analyze、metrics、issues、dependencies	analyze_python_package、get_package_metrics、find_package_issues
repo	index、query	—

uv run python-refactor-cli file long-functions src/app.py --line-threshold 30 --format json
uv run python-refactor-cli file extraction src/app.py --function-name process_order
uv run python-refactor-cli test coverage src/ --test-path tests/ --target-coverage 80
uv run python-refactor-cli test tdd src/app.py --function-name process_order
uv run python-refactor-cli security scan src/app.py --format table
uv run python-refactor-cli package metrics src/mypackage --format json

すべてのコマンドの使用方法と例を確認するには、python-refactor-cli skills（または <group> <command> --help）を実行してください。以前のフラットな名前（find-long-functions、security-scan、package-metrics、…）も、非表示のエイリアスとして引き続き使用できます。

すべてのコマンドで、機械可読な出力を得るために --format json を指定できます。

エージェントでの使用

このプロジェクトには、エージェントがこのツールをどのように呼び出すべきかを説明する SKILL.md が含まれています。どの状況でどのコマンドを使うか、また JSON 出力の仕様が記載されています。

uv run python-refactor-cli skills       # print the skill + every command with examples
uv run python-refactor-cli skill path   # print the path to SKILL.md

出力されたパスをコーディングエージェント（例：Claude Code）に示し、このリポジトリの Python コードをリファクタリングする前にスキルファイルを読み込むよう依頼してください。汎用的なプロンプトの例：

uv run python-refactor-cli skills を実行し、このセッションではそのスキルに従ってください。

利用可能な MCP ツール

統合サーバー

単一サーバー：ガイドのみのモードと変更適用モードの両方を、1 つのサーバーで利用できます。

接続方法：

• stdin/stdout：python-refactor server（デフォルト）
• モジュール実行：python -m mcp_refactoring_assistant server

ツール

1. analyze_python_code

自動リファクタリングのオプションを備えた包括的な分析です。

パラメーター：

• content（必須）：文字列形式の Python ファイルの内容
• mode（任意）："guide_only"（デフォルト）または "apply_changes"
• file_path（任意）：コンテキストとして使用するファイルのパス
• line_threshold（任意）：長い関数とみなす最小行数（デフォルト：20）

モード：guide_only - 手順のみを返します モード：apply_changes - 変更後のコードを返します

2. analyze_security_and_patterns 🔒 新機能！

包括的なセキュリティスキャンと、最新の Python パターンの分析を行います。

パラメーター：

• content（必須）：文字列形式の Python ファイルの内容
• file_path（任意）：コンテキストとして使用するファイルのパス
• include_security_scan（任意）：セキュリティ脆弱性のスキャンを有効にします（デフォルト：true）
• include_dependency_scan（任意）：依存関係の脆弱性スキャンを有効にします（デフォルト：true）
• include_modernization（任意）：最新の Python パターンの提案を有効にします（デフォルト：true）

機能：

• セキュリティ分析：20 種類以上の脆弱性（ハードコードされたシークレット、SQL インジェクション、脆弱な暗号方式など）を検出します
• 依存関係のスキャン：pip-audit を使用して、既知の CVE があるかプロジェクトの依存関係をスキャンします
• モダナイゼーション：最新の Python パターン（f-string、pathlib、enumerate など）を提案します
• 優先度のインテリジェントな設定：重大度と影響度に基づいて問題をランク付けします
• 分析の設定：必要に応じて、スキャンの種類ごとに有効／無効を切り替えられます

3. extract_function

ガイドモードまたは適用モードで、指定した関数を抽出します。

パラメーター：

• content（必須）：Python ファイルの内容
• mode（任意）："guide_only" または "apply_changes"
• function_name（任意）：対象とする特定の関数
• start_line、end_line（apply_changes の場合）：抽出する範囲を正確に指定します
• new_function_name（apply_changes の場合）：抽出した関数の名前

4. quick_analyze

すぐに実施できるリファクタリング候補を高速に分析します。

パラメーター：

• content（必須）：Python ファイルの内容

戻り値： 長い関数とパラメーターの問題に関する簡潔な概要

4. check_types_with_pyrefly

pyrefly を使用した高度な型チェックと品質分析です。

パラメーター：

• content（必須）：型チェックする Python コードの内容

戻り値： 詳細な型エラー、品質上の問題、改善の提案

5. get_server_capabilities（内部用）

サーバーの機能と利用可能な分析ツールを返します。

戻り値： 利用可能なツールの一覧：rope、radon、vulture、jedi、libcst、pyrefly、mccabe、complexipy

分析機能

検出されるコード品質の問題：

• 20 行を超える関数（メソッド抽出の機会）
• McCabe 分析による高い循環的複雑度（>10）
• Complexipy 分析による高い認知的複雑度（>15）
• パラメーターが多すぎる関数（>5）
• Vulture によるデッドコード／未使用コードの検出（提案を統合）
• Radon の指標による低い保守性インデックス（<20）
• Pyrefly によって検出される型注釈の問題
• モジュール分割の推奨対象となる大きなファイル（>500 行）
• 再構成を推奨するインポート数の多すぎるファイル（>20）

🔒 セキュリティとモダナイゼーション機能（新機能！）：

• セキュリティ脆弱性の検出：Bandit を使用した包括的なセキュリティスキャン
• 依存関係のセキュリティ分析：pip-audit を使用したプロジェクト依存関係内の CVE 検出
• 最新の Python パターン：Refurb を使用したコードのモダナイゼーション提案
• 統合分析：セキュリティとモダナイゼーションを組み合わせた、インテリジェントな優先順位付け
• 設定可能なスキャン：MCP エンドポイントから特定の分析タイプを有効化／無効化

その他の分析ツール：

• パフォーマンス分析：ボトルネックの特定と最適化の提案
• 型ヒント：型注釈の不足を検出
• ドキュメント：docstring の網羅性と品質を評価

使用するプロフェッショナルツール：

🔧 中核となるリファクタリング分析：

• Rope：プロフェッショナルなリファクタリング分析とメソッド抽出の検出
• Radon：コード複雑度の指標（循環的複雑度、保守性インデックス）
• Vulture：デッドコードの検出と未使用インポートの分析
• Jedi：セマンティックコード分析と変数の追跡
• LibCST：正確なコード分析のための構文木操作
• Pyrefly：高度な型チェックと品質分析
• McCabe：循環的複雑度の測定
• Complexipy：高度な複雑度分析と認知的複雑度

🔒 セキュリティとモダナイゼーションのツール（新機能！）：

• Bandit：AST ベースのセキュリティ脆弱性スキャナー（20 種類以上の脆弱性）
• pip-audit：CVE データベースを使用した依存関係の脆弱性スキャナー
• Refurb：最新の Python パターンの提案とコードのモダナイゼーション

📁 組み込みの分析：

• ファイル分析：ファイルサイズの分析とモジュール分割の推奨
• パッケージ分析：パッケージ構造と依存関係の包括的な分析

テストとデバッグ

MCP Inspector でテストする

# Launch MCP Inspector
bunx @modelcontextprotocol/inspector

# In the web interface:
# Command: python
# Args: -m mcp_refactoring_assistant server
# Working Directory: /path/to/your/project

Inspector で両方のモードをテストする：

ガイドモードのテスト：

{
  "content": "def long_function():\n    print('line1')\n    # ... 20+ lines",
  "mode": "guide_only"
}

適用モードのテスト：

{
  "content": "def long_function():\n    print('line1')\n    # ... 20+ lines", 
  "mode": "apply_changes"
}

Bun でテストする（最速）

# Install Bun if not available
curl -fsSL https://bun.sh/install | bash

# Install MCP SDK
bun install -g @modelcontextprotocol/sdk

# Run tests
export PATH=.venv/bin:$PATH && bun run test_unified.js

単独でテストする（MCP なし）

# Simple Python test
python test_tool.py

# Test with example file
python -m mcp_refactoring_assistant --help

サーバーの問題をデバッグする

# Check dependencies
uv sync

# Verify MCP imports
python -c "import mcp; print('MCP available')"

# Test individual tools
python -c "
from src.mcp_refactoring_assistant.server import EnhancedRefactoringAnalyzer
analyzer = EnhancedRefactoringAnalyzer()
print('Analyzer working')
"

使用例

学習ワークフロー

1. AI アシスタントが guide_only モードで analyze_python_code を呼び出します
2. ツールが、正確な手順を含む構造化された提案を返します
3. 開発者が手順に沿って作業します
4. 開発者は実践を通じてリファクタリングのパターンを学びます

生産性向上ワークフロー

1. AI アシスタントが apply_changes モードで analyze_python_code を呼び出します
2. ツールがリファクタリングを適用した変更後のコードを返します
3. 開発者が変更を確認し、必要に応じて適用します
4. 経験豊富な開発者のリファクタリングを高速化します

MCP レスポンスのサンプル（ガイドモード）

{
  "analysis_summary": {
    "total_issues_found": 2,
    "medium_priority": 1,
    "low_priority": 1
  },
  "refactoring_guidance": [
    {
      "issue_type": "extract_function",
      "location": "Function 'process_data' lines 45-78",
      "description": "Long function (34 lines) with extractable blocks",
      "precise_steps": [
        "SELECT lines 45-52 (validation block)",
        "CREATE function: validate_input(data)",
        "REPLACE with: is_valid = validate_input(data)"
      ]
    },
    {
      "issue_type": "dead_code", 
      "location": "Multiple locations (6 items)",
      "description": "6 unused items found",
      "precise_steps": [
        "Review all unused items listed below:",
        "• Line 11: Unused import 're'",
        "• Line 12: Unused import 'Optional'",
        "Verify each item is truly unused",
        "Remove confirmed unused code"
      ]
    }
  ]
}

コーディングアシスタントとの統合

Claude Code/CLI

MCP 設定に追加します：

{
  "servers": {
    "python-refactoring": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/slamer59/mcp-python-refactoring.git", "python-refactor", "server"]
    }
  }
}

または、ローカルにインストールする場合：

{
  "servers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "python-refactoring": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/slamer59/mcp-python-refactoring.git", "python-refactor", "server"]
    }
  }
}

または、ローカルにインストールする場合：

{
  "mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Cline（VSCode 拡張機能）

VSCode の設定または .vscode/settings.json に追加します：

{
  "cline.mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Cursor

Cursor の MCP 設定に追加します：

{
  "mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Continue（VSCode 拡張機能）

~/.continue/config.json に追加します：

{
  "mcpServers": [
    {
      "name": "python-refactoring",
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  ]
}

Windsurf

Windsurf の MCP 設定に追加します：

{
  "servers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Aider

MCP ブリッジまたは直接統合を使用します：

aider --mcp-server "python -m mcp_refactoring_assistant server"

OpenHands（旧称 OpenDevin）

OpenHands の設定に追加します：

mcp_servers:
  python-refactoring:
    command: python
    args: ["-m", "mcp_refactoring_assistant", "server"]

Roo-Code

Roo-Code の MCP 設定に追加します：

{
  "mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Codex CLI

~/.codex/config.toml に追加します：

[mcp_servers.python-refactoring]
command = "python"
args = ["-m", "mcp_refactoring_assistant", "server"]

ターミナルベースのクライアント

ほとんどのターミナルベースの MCP クライアントでは、次のようにします：

# With uvx
client-name --mcp-server "uvx --from git+https://github.com/slamer59/mcp-python-refactoring.git python-refactor server"

# With local installation  
client-name --mcp-server "python -m mcp_refactoring_assistant server"

SSE モード（Web ベースのクライアント）

SSE 接続に対応した Web ベースのクライアントの場合：

1. サーバーを SSE モードで起動します：

# SSE mode is not currently supported
# Use stdin/stdout mode instead
python-refactor server

2. SSE の代わりに stdin/stdout 接続を使用します

mcpo との使用（ChatGPT など）

MCP に標準対応していないクライアントの場合：

# Install mcpo
pip install mcpo

# Bridge MCP to OpenAI-compatible API
mcpo --mcp-server "python -m mcp_refactoring_assistant server" --port 8080

次に、API エンドポイントとして http://localhost:8080 を使用するようにクライアントを設定します。

注意事項

• ローカルにインストールする場合は、python -m mcp_refactoring_assistant server を使用します
• uvx でインストールする場合は、ローカルパスではなく uvx コマンド全体を使用します
• クライアントによっては、追加の設定が必要な場合や、構文が異なる場合があります
• Python 実行ファイルを指定する際は、必ず絶対パスを使用します
• 利用できる場合は、クライアントの MCP デバッグツールで接続をテストします

仕組み

1. 分析：サーバーが複数のプロフェッショナル向けツールを使用して Python コードを分析します
2. 検出：メトリクスを用いて、具体的なリファクタリングの機会を特定します
3. ガイダンス：正確な行番号と手順を示します
4. 統合：AI アシスタントが結果を解釈し、開発者をガイドします
5. 制御：開発者がすべてのコード変更を完全に管理します

ユーザーのフィードバック

このツールを AI アシスタントと使用することで、コード品質への理解とリファクタリングスキルが大幅に向上したと、ユーザーから報告されています。ガイド付きのアプローチにより、開発者はコード変更を自分で管理しながら、リファクタリングのパターンを学べます。

"リファクタリングを代わりに行うのではなく、教えてくれるツールにようやく出会えました"
"正確な行番号のおかげで、提案に簡単に沿って作業できます"
"レガシーコードを扱ううえで、画期的なツールです"

トラブルシューティング

MCP 接続の問題：

• すべての依存関係がインストールされていることを確認します：uv sync
• Python のパスを確認します：which python
• MCP のインポートを確認します：python -c "import mcp"

分析が機能しない場合：

• アナライザーを直接テストします：python test_tool.py
• ファイルのアクセス権を確認します
• サンプルファイルが存在することを確認します：ls examples/

ツールの応答が空の場合：

• 分析対象の関数がコードに含まれているか確認します（複雑度の最低しきい値があります）
• テスト用に行数のしきい値を上げます："line_threshold": 10
• ファイルの構文が有効な Python であることを確認します
• 仮想環境が有効になっていることを確認します

SSE 接続の問題：

• ポートが使用中でないことを確認します：netstat -an | grep 3001
• ローカル接続のファイアウォール設定を確認します
• Starlette と Uvicorn がインストールされていることを確認します：uv add starlette uvicorn

パフォーマンスの問題：

• 大規模なコードベース（100 ファイル超）では、ファイルを指定した分析の使用を検討してください
• MCP クライアント設定のタイムアウト値を増やします
• 特定の関数に関するフィードバックをすぐに得るには、quick_analyze を使用します

コミュニティレジストリ

awesome リストやコミュニティカタログに登録します：

• MCPServers.org - GitHub issue を作成
• Awesome MCP Servers - PR を送信
• Wong2's Awesome List - PR を送信

🆕 最近の主な更新

バージョン 2.0：セキュリティとモダン化機能

🎉 新機能：

• 🔒 セキュリティスキャン：Bandit によるプロフェッショナルレベルの脆弱性検出

  • 20 種類以上のセキュリティ問題を検出します（SQL インジェクション、ハードコードされたシークレット、脆弱な暗号化など）
  • 既存のリファクタリング分析とシームレスに連携します

• 📦 依存関係のセキュリティ：pip-audit による CVE スキャン

  • プロジェクトの依存関係に既知の脆弱性がないかスキャンします
  • 具体的なバージョンアップグレードの推奨事項を提示します

• ⚡ コードのモダン化：Refurb による Python パターンの提案

  • モダンな Python 機能（f-strings、pathlib、enumerate など）を提案します
  • レガシーコードを最新のベストプラクティスに準拠させるのに役立ちます

• 🎯 統合分析：インテリジェントな優先順位付けシステム

  • セキュリティ、モダン化、リファクタリングの分析を統合します
  • 重大度と影響に基づいて優先順位をスマートに設定します
  • 新しい MCP エンドポイントからスキャンオプションを設定できます

• ✅ 本番環境対応：

  • 177 件以上の包括的なテスト（すべて合格）
  • 広範なエラー処理とエッジケースの網羅
  • 大規模なコードベースでのパフォーマンステスト済み
  • 完全な後方互換性を維持

📊 実証された成果：

• 反復的な改善を通じて、自身の分析と改善に成功
• 強力な新機能を追加しながら、コードの複雑さを軽減
• コードベース全体の型安全性と保守性を向上

ライセンス

MIT License - 個人利用および商用利用は無料です。