Mcp Python Refactoring

MCP Python 重构

一个 Model Context Protocol（MCP）服务，用于分析 Python 代码并提供有指导的重构建议，而不会自动修改代码。

关键词

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 服务列表

社区整理的列表：

• 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，Python 重构工具便会在 Claude 对话中可用！

开发环境安装

# 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，或通过 Agent 的 Shell 直接调用工具：

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，以输出机器可读的内容。

与 Agent 配合使用

此项目提供了一个 SKILL.md，其中说明 Agent 应如何调用它—— 在不同情况下使用哪些命令，以及 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

将此命令打印出的路径提供给你的编码 Agent（例如 Claude Code），并让它在重构此代码库中的 Python 代码前加载技能文件。一个通用的提示词示例：

运行 uv run python-refactor-cli skills，并在本次会话中遵循该技能。

可用的 MCP 工具

统一服务

单一服务：在一个服务中同时提供仅提供指南和应用更改两种模式

连接选项：

• 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 端点启用/禁用特定分析类型

其他分析工具：

• 性能分析：识别瓶颈并提供优化建议
• 类型提示：检测缺失的类型注解
• 文档：评估文档字符串的覆盖率和质量

使用的专业工具：

🔧 核心重构分析：

• 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. 使用 stdin/stdout 连接，而不是 SSE

使用 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

然后将客户端配置为使用 http://localhost:8080 作为 API 端点。

注意事项

• 本地安装时使用 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 即时获取特定函数的反馈

社区收录列表

提交到精选列表和社区目录：

• 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-string、pathlib、enumerate）
  • 帮助将旧代码升级为符合当代最佳实践的代码

• 🎯 统一分析：智能优先级排序系统

  • 综合安全、现代化和重构分析
  • 根据严重程度和影响智能排序
  • 通过新的 MCP 端点配置扫描选项

• ✅ 可用于生产环境：

  • 177 项以上全面测试（全部通过）
  • 完善的错误处理和边界情况覆盖
  • 在大型代码库上经过性能测试
  • 保持完全向后兼容

📊 成效验证：

• 通过迭代优化，成功分析并改进自身
• 在增加强大新功能的同时降低代码复杂度
• 提升整个代码库的类型安全性和可维护性

许可证

MIT 许可证——可免费用于个人和商业用途。