Skip to main content
Glama

mcp-refactoring

An MCP (Model Context Protocol) server that exposes Martin Fowler's refactoring catalog to LLMs through a pluggable, language-agnostic architecture.

Features

  • 71+ Refactorings: Full implementation of Martin Fowler's refactoring catalog

  • Pluggable Architecture: Support for multiple languages (Python first, Ruby/Java/Go planned)

  • Safe by Default: Preview mode shows changes before applying

  • LLM-Optimized: TOON output format for token efficiency

Related MCP server: mcp-code-context

Installation

# Using uvx (recommended)
uvx mcp-refactoring

# Using pip
pip install mcp-refactoring

# Using pipx
pipx install mcp-refactoring

Requirements

  • Python 3.10+

  • A language backend (e.g., molting-cli for Python)

Install the Python backend:

pip install molting-cli

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "refactoring": {
      "command": "uvx",
      "args": ["mcp-refactoring"]
    }
  }
}

Available Tools

list_refactorings

List available refactorings with their parameter contracts.

list_refactorings(language="python", category="composing_methods")

preview_refactoring

Preview what changes a refactoring would make (dry-run).

preview_refactoring(
    refactoring="extract-method",
    target="src/order.py::Order::calculate#L10-L15",
    params={"name": "calculate_tax"}
)

apply_refactoring

Apply a refactoring to the codebase.

apply_refactoring(
    refactoring="rename-method",
    target="src/order.py::Order::calc",
    params={"new_name": "calculate_total"}
)

inspect_structure

Get structural information about code.

inspect_structure(path="src/order.py", depth="method")

analyze_code

Analyze code for smells and suggest refactorings.

analyze_code(path="src/order.py", smells=["long-method"])

Target Specification

Each language uses its native conventions:

Python

src/order.py::Order::calculate_total        # Method
src/order.py::Order::calculate_total#L10-L15  # Line range
src/order.py::Order                         # Class

Configuration

Create ~/.mcp-refactoring/config.toml:

[backends.python]
enabled = true
command = "molting"

[backends.ruby]
enabled = false
command = "molting-rb"

Environment variable overrides:

MCP_REFACTORING_PYTHON_COMMAND=/path/to/molting
MCP_REFACTORING_PYTHON_ENABLED=true

Refactoring Categories

Based on Martin Fowler's catalog:

  • Composing Methods: extract-method, inline-method, etc.

  • Moving Features: move-method, extract-class, etc.

  • Organizing Data: encapsulate-field, replace-type-code, etc.

  • Simplifying Conditionals: decompose-conditional, guard-clauses, etc.

  • Simplifying Method Calls: rename-method, add-parameter, etc.

  • Dealing with Generalization: pull-up-method, extract-interface, etc.

Development

# Clone the repository
git clone https://github.com/marshally/mcp-refactoring.git
cd mcp-refactoring

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy src/

License

MIT License - see LICENSE for details.

Available Tools

5 tools
analyze_codeA
Read-onlyIdempotent

Analyze code for smells and suggest refactorings.

Detects code smells like long methods, large classes, feature envy, and suggests appropriate refactorings to address them.

Note: This feature requires backend support. Returns backend_supported: false for backends that don't implement analysis yet.

Args: path: File or directory path to analyze smells: Optional list of smell types to check for (e.g., ['long-method', 'large-class', 'feature-envy'])

Returns: TOON-formatted string with analysis results.

Supported smell types (when backend supports analysis): - long-method: Method exceeds line threshold - large-class: Class has too many responsibilities - feature-envy: Method uses another class's data excessively - data-clumps: Same data items appear together repeatedly - primitive-obsession: Overuse of primitives instead of objects - duplicate-code: Similar code in multiple locations

Inputs: path (required), smells. Returns: result

apply_refactoringA

Apply a refactoring to the codebase.

This actually modifies files. Use preview_refactoring first to see what changes will be made. Changes can be reverted with git.

Args: refactoring: Name of the refactoring (e.g., 'extract-method') target: Target in language-native format (e.g., 'src/order.py::Order::calculate#L10-L15') params: Refactoring-specific parameters

Returns: TOON-formatted string with results of the applied refactoring.

Example: apply_refactoring( refactoring="rename-method", target="src/order.py::Order::calc_total", params={"new_name": "calculate_total"} )

Inputs: refactoring (required), target (required), params. Returns: result

inspect_structureA
Read-onlyIdempotent

Get structural information about code (classes, methods, line numbers).

Inspects a file to return information about its structure. Use this to understand the code before applying refactorings.

Args: path: File path to inspect (e.g., 'src/order.py') depth: Level of detail - 'file', 'class', or 'method' (default: 'class')

Returns: TOON-formatted string with structural information.

Example: inspect_structure(path="src/order.py", depth="method")

Inputs: path (required), depth. Returns: result

list_refactoringsA
Read-onlyIdempotent

List available refactorings with their parameter contracts.

Returns the catalog of available refactorings from all enabled backends, optionally filtered by language and/or category.

Args: language: Filter by language (e.g., 'python'). If not specified, returns all. category: Filter by Fowler category (e.g., 'composing_methods')

Returns: TOON-formatted string containing refactoring specifications.

Categories: - composing_methods: Extract/inline methods, variables - moving_features: Move methods/fields between classes - organizing_data: Encapsulation, type codes - simplifying_conditionals: Guard clauses, polymorphism - simplifying_method_calls: Rename, add/remove parameters - dealing_with_generalization: Pull up/push down, inheritance

Inputs: language, category. Returns: result

preview_refactoringA
Read-onlyIdempotent

Preview what changes a refactoring would make without applying them.

This is a dry-run mode that shows the diff of what would change, without actually modifying any files. Always preview before applying.

Args: refactoring: Name of the refactoring (e.g., 'extract-method') target: Target in language-native format (e.g., 'src/order.py::Order::calculate#L10-L15') params: Refactoring-specific parameters (e.g., {'name': 'calculate_tax'})

Returns: TOON-formatted string with preview results including diff.

Example: preview_refactoring( refactoring="extract-method", target="src/order.py::Order::calculate#L10-L15", params={"name": "calculate_tax"} )

Inputs: refactoring (required), target (required), params. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: analyzing code smells, inspecting structure, listing available refactorings, previewing changes, and applying refactorings. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (e.g., analyze_code, preview_refactoring). No mixing of conventions.

    Tool Count5/5

    Five tools is well-scoped for a refactoring server, covering analysis, inspection, listing, preview, and application without unnecessary tools.

    Completeness4/5

    The toolset covers the main refactoring workflow: analysis, preview, and application. Missing a dedicated undo tool, but git revert is suggested. Minor gap but acceptable.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides LLM-optimized tools for advanced code analysis, repository complexity evaluation, and call graph generation. It enables users to visualize directory structures, detect code patterns, and build semantic context with significant token savings.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables LLMs to efficiently read, write, and refactor code using precise AST-based operations, reducing token usage and context window waste.
      25
      238 npm
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables coding agents to perform safe, project-wide Python refactoring (rename, move, extract, inline, change signature, organize imports, etc.) with a dry-run safety contract and LSP-coordinate addressing.
      15
      MIT