MCP Python Refactoring

A Model Context Protocol (MCP) server that analyzes Python code and provides guided refactoring suggestions without automatically modifying your code.

Keywords

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

This tool integrates with AI coding assistants (Claude, ChatGPT, Cursor, etc.) to provide intelligent refactoring guidance. Instead of making automatic code changes, it gives you precise instructions on how to improve your Python code, acting as your refactoring mentor.

What This Tool Does

For AI Coding Assistants:

Provides structured JSON responses with refactoring opportunities
Identifies long functions, high complexity code, and dead code
Gives precise line numbers for extract method refactoring
Uses professional tools for comprehensive analysis

For Developers:

Get step-by-step refactoring instructions
Maintain full control over code changes
Learn refactoring patterns through guided practice
Improve code quality systematically

How It Differs

| Approach | This Tool | Traditional Refactoring Tools | | ----------- | ------------------------------------------- | ----------------------------- | | Integration | Works with any LLM/AI assistant | IDE-specific or standalone | | Guidance | Step-by-step instructions with line numbers | Automatic changes only | | Learning | Educational approach teaches patterns | No learning component | | Control | Developer maintains full control | Tool makes all decisions |

Registry Submissions

This MCP server is available across the entire MCP ecosystem:

Official MCP Registry

Published and Live: registry.modelcontextprotocol.io

Server name: io.github.slamer59/mcp-python-refactoring
Discoverable by all MCP-compatible clients

🟡 Docker MCP Registry

Pull Request Submitted: docker/mcp-registry #207

Will be available as mcp/mcp-python-refactoring on Docker Hub
Includes enhanced security: signatures, SBOM, provenance tracking
Integrated into Docker Desktop's MCP Toolkit

🟡 Awesome MCP Servers Lists

Community Curated Lists:

appcypher/awesome-mcp-servers #180 - Development Tools section
punkpeye/awesome-mcp-servers #1321 - Code Execution section

📦 Installation Options

Once all registries are live, users can discover via:

MCP catalog - Official registry search
Docker Desktop - MCP Toolkit integration
Community lists - GitHub awesome lists
Docker Hub - mcp/mcp-python-refactoring (with enhanced security)

Docker Support

Using with Docker MCP Catalog

# 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"]

Installation

Quick Start with uvx (Recommended)

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

Add to Claude Code (One Command)

# 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

After running this command, restart Claude Desktop and the Python refactoring tools will be available in your Claude conversations!

Development Installation

# 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

Available MCP Tools

Unified Server

Single Server: Both guide-only and apply-changes modes in one server

Connection Options:

stdin/stdout: python-refactor server (default)
Module execution: python -m mcp_refactoring_assistant server

Tools

1. `analyze_python_code`

Comprehensive analysis with optional automatic refactoring.

Parameters:

content (required): Python file content as string
mode (optional): "guide_only" (default) or "apply_changes"
file_path (optional): Path to the file for context
line_threshold (optional): Minimum lines for long functions (default: 20)

Mode: guide_only - Returns instructions only Mode: apply_changes - Returns modified code

2. `analyze_security_and_patterns` 🔒 NEW!

Comprehensive security scanning and modern Python patterns analysis.

Parameters:

content (required): Python file content as string
file_path (optional): Path to the file for context
include_security_scan (optional): Enable security vulnerability scanning (default: true)
include_dependency_scan (optional): Enable dependency vulnerability scanning (default: true)
include_modernization (optional): Enable modern Python pattern suggestions (default: true)

Features:

Security Analysis: Detects 20+ vulnerability types (hardcoded secrets, SQL injection, weak crypto, etc.)
Dependency Scanning: Scans project dependencies for known CVEs using pip-audit
Modernization: Suggests modern Python patterns (f-strings, pathlib, enumerate, etc.)
Intelligent Prioritization: Issues ranked by severity and impact
Configurable Analysis: Enable/disable specific scanning types as needed

3. `extract_function`

Extract specific functions with guide or apply mode.

Parameters:

content (required): Python file content
mode (optional): "guide_only" or "apply_changes"
function_name (optional): Specific function to target
start_line, end_line (for apply_changes): Exact extraction range
new_function_name (for apply_changes): Name for extracted function

4. `quick_analyze`

Fast analysis for immediate refactoring opportunities.

Parameters:

content (required): Python file content

Returns: Quick summary of long functions and parameter issues

4. `check_types_with_pyrefly`

Advanced type checking and quality analysis using pyrefly.

Parameters:

content (required): Python code content to type check

Returns: Detailed type errors, quality issues, and improvement suggestions

5. `get_server_capabilities` (Internal)

Returns server capabilities and available analysis tools.

Returns: List of available tools: rope, radon, vulture, jedi, libcst, pyrefly, mccabe, complexipy

Analysis Capabilities

Code Quality Issues Detected:

Functions over 20 lines (extract method opportunities)
High cyclomatic complexity (>10) using McCabe analysis
High cognitive complexity (>15) using Complexipy analysis
Functions with too many parameters (>5)
Dead/unused code (consolidated suggestions) via Vulture
Low maintainability index (<20) using Radon metrics
Type annotation problems detected by Pyrefly
Large files (>500 lines) with module splitting recommendations
Files with too many imports (>20) suggesting restructuring

🔒 Security & Modernization Features (NEW!):

Security Vulnerability Detection: Comprehensive security scanning using Bandit
Dependency Security Analysis: CVE detection in project dependencies with pip-audit
Modern Python Patterns: Code modernization suggestions using Refurb
Unified Analysis: Intelligent prioritization combining security and modernization
Configurable Scanning: Enable/disable specific analysis types via MCP endpoint

Additional Analysis Tools:

Performance Analysis: Bottleneck identification and optimization suggestions
Type Hints: Missing type annotation detection
Documentation: Docstring coverage and quality assessment

Professional Tools Used:

🔧 Core Refactoring Analysis:

Rope: Professional refactoring analysis and extract method detection
Radon: Code complexity metrics (cyclomatic, maintainability index)
Vulture: Dead code detection and unused import analysis
Jedi: Semantic code analysis and variable tracking
LibCST: Syntax tree manipulation for precise code analysis
Pyrefly: Advanced type checking and quality analysis
McCabe: Cyclomatic complexity measurement
Complexipy: Advanced complexity analysis and cognitive complexity

🔒 Security & Modernization Tools (NEW!):

Bandit: AST-based security vulnerability scanner (20+ vulnerability types)
pip-audit: Dependency vulnerability scanner with CVE database
Refurb: Modern Python pattern suggestions and code modernization

📁 Built-in Analysis:

File Analysis: File size analysis and module splitting recommendations
Package Analysis: Comprehensive package structure and dependency analysis

Testing and Debugging

Test with 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

Test Both Modes in Inspector:

Guide Mode Test:

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

Apply Mode Test:

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

Test with Bun (Fastest)

# 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

Test Standalone (No MCP)

# Simple Python test
python test_tool.py

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

Debug Server Issues

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

Example Usage

Educational Workflow

AI assistant calls analyze_python_code with guide_only mode
Tool returns structured suggestions with precise steps
Developer follows step-by-step instructions
Developer learns refactoring patterns through practice

Productivity Workflow

AI assistant calls analyze_python_code with apply_changes mode
Tool returns modified code with applied refactorings
Developer reviews changes and applies as needed
Faster refactoring for experienced developers

Sample MCP Response (Guide Mode)

{
  "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"
      ]
    }
  ]
}

Integration with Coding Assistants

Claude Code/CLI

Add to your MCP configuration:

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

Or for local installation:

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

Claude Desktop

Add to claude_desktop_config.json:

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

Or for local installation:

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

Cline (VSCode Extension)

In VSCode settings or .vscode/settings.json:

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

Cursor

Add to Cursor's MCP configuration:

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

Continue (VSCode Extension)

In ~/.continue/config.json:

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

Windsurf

Add to Windsurf MCP configuration:

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

Aider

Use with MCP bridge or direct integration:

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

OpenHands (formerly OpenDevin)

In OpenHands configuration:

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

Roo-Code

Add to Roo-Code's MCP settings:

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

Codex CLI

Add to ~/.codex/config.toml:

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

Terminal-based clients

For most terminal-based MCP clients:

# 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 Mode (Web-based clients)

For web-based clients that support SSE connections:

Start the server in SSE mode:

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

Use stdin/stdout connection instead of SSE

Using with mcpo (ChatGPT and others)

For clients without native MCP support:

# Install mcpo
pip install mcpo

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

Then configure your client to use http://localhost:8080 as API endpoint.

Notes

Use python -m mcp_refactoring_assistant server for local installations
For uvx installation, use the full uvx command instead of local paths
Some clients may require additional configuration or have different syntax
Always use absolute paths when specifying python executable
Test the connection with the client's MCP debugging tools if available

How It Works

Analysis: Server analyzes Python code using multiple professional tools
Detection: Identifies specific refactoring opportunities with metrics
Guidance: Provides precise line numbers and step-by-step instructions
Integration: AI assistant interprets results and guides developer
Control: Developer maintains full control over all code changes

User Feedback

Users report significant improvements in code quality understanding and refactoring skills when using this tool with AI assistants. The guided approach helps developers learn refactoring patterns while maintaining control over code changes.

"Finally, a tool that teaches me refactoring instead of doing it for me"
"The precise line numbers make it easy to follow the suggestions"
"Game changer for working with legacy code"

Troubleshooting

MCP Connection Issues:

Ensure all dependencies installed: uv sync
Check Python path: which python
Verify MCP import: python -c "import mcp"

Analysis Not Working:

Test analyzer directly: python test_tool.py
Check file permissions
Verify example file exists: ls examples/

Tool Responses Empty:

Check if code has functions to analyze (minimum complexity threshold)
Increase line threshold for testing: "line_threshold": 10
Verify file syntax is valid Python
Ensure virtual environment is activated

SSE Connection Issues:

Verify port is not in use: netstat -an | grep 3001
Check firewall settings for local connections
Ensure FastAPI and Uvicorn are installed: uv add fastapi uvicorn

Performance Issues:

For large codebases (>100 files), consider using file-specific analysis
Increase timeout settings in MCP client configuration
Use quick_analyze for immediate feedback on specific functions

Community Registries

Submit to awesome lists and community catalogs:

MCPServers.org - Create GitHub issue
Awesome MCP Servers - Submit PR
Wong2's Awesome List - Submit PR

🆕 Recent Major Updates

Version 2.0: Security & Modernization Features

🎉 What's New:

🔒 Security Scanning: Professional-grade vulnerability detection using Bandit
- Detects 20+ security issue types (SQL injection, hardcoded secrets, weak crypto)
- Integrates seamlessly with existing refactoring analysis
📦 Dependency Security: CVE scanning with pip-audit
- Scans project dependencies for known vulnerabilities
- Provides specific version upgrade recommendations
⚡ Code Modernization: Python pattern suggestions using Refurb
- Suggests modern Python features (f-strings, pathlib, enumerate)
- Helps upgrade legacy code to contemporary best practices
🎯 Unified Analysis: Intelligent prioritization system
- Combines security, modernization, and refactoring analysis
- Smart priority ordering by severity and impact
- Configurable scanning options via new MCP endpoint
✅ Production Ready:
- 177+ comprehensive tests (100% passing)
- Extensive error handling and edge case coverage
- Performance tested on large codebases
- Full backward compatibility maintained

📊 Proven Results:

Successfully analyzed and improved itself through iterative refinement
Reduced code complexity while adding powerful new features
Enhanced type safety and maintainability throughout the codebase

License

MIT License - Free for personal and commercial use.

MCP Python Refactoring

Keywords

What This Tool Does

How It Differs

Registry Submissions

Official MCP Registry

🟡 Docker MCP Registry

🟡 Awesome MCP Servers Lists

📦 Installation Options

Docker Support

Using with Docker MCP Catalog

Dockerfile

Installation

Quick Start with uvx (Recommended)

Add to Claude Code (One Command)

Development Installation

Available MCP Tools

Unified Server

Tools

1. analyze_python_code

2. analyze_security_and_patterns 🔒 NEW!

3. extract_function

4. quick_analyze

4. check_types_with_pyrefly

5. get_server_capabilities (Internal)

Analysis Capabilities

Testing and Debugging

Test with MCP Inspector

Test with Bun (Fastest)

Test Standalone (No MCP)

Debug Server Issues

Example Usage

Educational Workflow

Productivity Workflow

Sample MCP Response (Guide Mode)

Integration with Coding Assistants

Claude Code/CLI

Claude Desktop

Cline (VSCode Extension)

Cursor

Continue (VSCode Extension)

Windsurf

Aider

OpenHands (formerly OpenDevin)

Roo-Code

Codex CLI

Terminal-based clients

SSE Mode (Web-based clients)

Using with mcpo (ChatGPT and others)

Notes

How It Works

User Feedback

Troubleshooting

Community Registries

🆕 Recent Major Updates

Version 2.0: Security & Modernization Features

License

Install Package (if required)

Cursor configuration (mcp.json)

1. `analyze_python_code`

2. `analyze_security_and_patterns` 🔒 NEW!

3. `extract_function`

4. `quick_analyze`

4. `check_types_with_pyrefly`

5. `get_server_capabilities` (Internal)