ropey
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ropey rename `get_data` to `fetch_data` in current file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ropey
Safe, project-wide Python refactoring for coding agents. ropey is an MCP server that exposes the rope refactoring library as tools a coding agent (Claude in Claude Code, OpenCode, or any MCP client) can call.
Why
Coding agents read and navigate Python well. An LSP like Astral's ty answers "where is this defined?" and "who references it?" precisely. What agents lack is a safe way to change Python structurally. Renaming a symbol used across thirty files by hand-editing text is slow and unreliable: the agent can't be sure it found every reference, can't prove a textual match is the same binding, and routinely leaves half-renamed code.
ropey closes that gap with one division of labour:
ty finds and reads; ropey changes.
The agent points at code using the exact line/character coordinates its
LSP already returned, and ropey performs the behaviour-preserving
transformation across the whole project: rename, move, extract, inline,
change signature, organise imports, and so on. One sibling tool, rewrite,
takes a pattern→goal transformation for structural changes none of the
refactorings express, addressed by a code template rather than a
coordinate (see the safety contract).
Related MCP server: rope-mcp-server
The safety contract
Behaviour is preserved, with one exception. Every refactoring alters the structure of your code without changing what it does, and rope proves each transformation safe before ropey writes it.
rewriteis the exception: it makes no behaviour-preservation claim. The agent asserts that pattern and goal are equivalent, and the tool guarantees only that it rewrites exactly the matches it reports. In exchange it surfaces every Match Site (file + range, flaggedmatchedorunsure) for the agent to audit, leaves unprovable sites un-rewritten unless explicitly opted in, and refuses any rewrite that would produce unparsable Python. Both preview and apply mode enforce that refusal.Dry Run by default. Every tool takes an
applyflag. Withapply=false(the default) the full consequence is computed and reported but nothing is written.apply=trueperforms the same change for real. Both report identical detail.The Blast Radius. Every result enumerates every affected file with what happened to it:
modified,created,moved(with its old path), ordeleted. The list is never truncated and never carries file contents. After a live run,git diffshows the exact text.Uncertain Occurrences. Python is dynamically typed, so sometimes rope cannot prove that
obj.save()refers to the method being renamed. ropey applies only the certain occurrences and reports every uncertain one as a flagged location for the agent to adjudicate. Nothing is silently included or silently dropped.Freshness is self-established. Before every refactoring the server re-checks the source on disk, so edits from any writer are reflected, whether they came from the agent, a human editor,
git checkout, or a formatter. Correctness never depends on the host announcing its edits.git is the undo. ropey writes no cache artifacts into your repo (no
.ropeproject/), never edits gitignored files (git couldn't revert them), and recommends a clean working tree before applying sogit diff/git checkoutare always a complete reversal mechanism.Failures are structured. A refactoring that cannot proceed returns a machine-readable reason ("the selection crosses a scope boundary", "the file
broken.pycannot be parsed") rather than a stack trace.
Install
Claude Code (plugin marketplace)
/plugin marketplace add andrewesweet/ropey
/plugin install ropey@ropeyThe plugin bundles the MCP server config; tools appear after a restart. Requires uv on your PATH.
OpenCode
Add to opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ropey": {
"type": "local",
"command": [
"uvx", "--from", "git+https://github.com/andrewesweet/ropey", "ropey"
],
"enabled": true
}
}
}Any other MCP client
ropey is a standard stdio MCP server. Generic config:
{
"mcpServers": {
"ropey": {
"command": "uvx",
"args": ["--from", "git+https://github.com/andrewesweet/ropey", "ropey"]
}
}
}Or run it directly: uvx --from git+https://github.com/andrewesweet/ropey ropey
The catalogue
Tool | What it does |
| Rename a symbol everywhere, optionally in docstrings/comments and across a class hierarchy |
| Move a global, a method, or a whole module; imports updated project-wide |
| Convert a module file into a package |
| Extract a selection into a helper or a named value |
| Inline a method, variable, or parameter (kind auto-detected) |
| Add / remove / reorder parameters with every call site updated |
| Sort, dedupe, expand star-imports, relative→absolute |
| Turn a selected expression into a new parameter that defaults to it, with call sites updated |
| Wrap a class attribute behind getter/setter; reads and writes rewritten project-wide |
| Add a factory (static method or module function) for a class and route instantiations through it |
| Convert a method into a method object (a class whose |
| Promote a method-local variable to an instance field ( |
| Replace code that duplicates a function's body with calls to it, project-wide |
| Pattern→goal rewrite of every matching site ( |
Targets are addressed with LSP coordinates (0-based line/character, UTF-16
units), the same coordinates an LSP returns; byte offsets never appear.
Point refactorings accept an optional expected_symbol so a stale position
fails loudly instead of refactoring the wrong code. The exception is
rewrite, which is addressed by a pattern (Python source with
${wildcard} placeholders) instead of a coordinate, and reports its Match
Sites back as LSP ranges. ty finds and reads; ropey changes.
Development
uv sync
uv run pytestDomain documentation lives in CONTEXT.md, the decision
records in docs/adr/, and the PRD in
docs/prd/. Operability notes and measured latency envelopes:
docs/operability.md.
Available Tools
15 toolschange_signatureA
Change a function or method signature — add, remove, or reorder parameters — updating every certain call site across the project. Point at the function name (0-based LSP line/character, UTF-16 units) and pass operations, a list applied in order: {action:'add', name, index?, default?, value?} (default is the parameter's default expression; value is what existing call sites should pass), {action:'remove', name or index}, {action:'reorder', order:[names or indices covering every parameter]}. For methods, parameter lists include self (index 0). across_class_hierarchy applies the change to matching overrides. Defaults to a Dry Run preview; set apply=true to write. Uncertain call sites are reported as uncertain_occurrences, never silently edited. Locate the function with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), operations (required), +4 more. Returns: object
encapsulate_fieldA
Encapsulate a class attribute behind getter/setter methods, rewriting reads to the getter and writes to the setter across the project. Point at the attribute name (0-based LSP line/character, UTF-16 units), exactly as your LSP returns it. getter_name and setter_name override the default get_/set_ names. Defaults to a Dry Run preview; set apply=true to write. Accesses that cannot be proven to be this attribute are reported as uncertain_occurrences, never silently rewritten. Supply expected_symbol when edits may have intervened since your LSP answer. Locate the attribute with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), root, +4 more. Returns: object
extract_methodA
Extract a selected block of statements (or an expression) into a new method or function, with parameters and return values inferred from the data flow. Pass the file and the selection Range — start_line/start_character to end_line/end_character, 0-based, character in UTF-16 units, exactly as an editor selection. The selection must be complete statements or one complete expression. Options: replace_similar replaces other occurrences of the same pattern; to_global_scope extracts to module level; method_kind makes a classmethod or staticmethod. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; leave formatting to black/ruff.
Inputs: file (required), name (required), end_line (required), start_line (required), +7 more. Returns: object
extract_variableA
Extract a selected expression into a named variable, replacing the expression with the name. Pass the file and the selection Range (start_line/start_character to end_line/end_character, 0-based, UTF-16 units) covering exactly one expression. replace_similar also substitutes other occurrences of the same expression; to_global_scope creates the variable at module level. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; leave formatting to black/ruff.
Inputs: file (required), name (required), end_line (required), start_line (required), +6 more. Returns: object
inlineA
Inline the method, variable, or parameter at a Position — the server detects which kind, so just point at the name (0-based LSP line/character, UTF-16 units). Methods and variables: every certain use is replaced by the body or value; remove_definition=false keeps the definition; only_current_occurrence=true inlines just the occurrence at the Position. Parameters: the default value is written into call sites that omit it. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely instead of inlining the wrong thing. Locate the definition with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), root, +5 more. Returns: object
introduce_factoryA
Introduce a factory for a class and route instantiations through it. Point at the class name (0-based LSP line/character, UTF-16 units). By default the factory is a static method named factory_name on the class; global_factory=true creates a module-level function instead. Existing constructor calls across the project are rewritten to the factory. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the class with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), factory_name (required), +4 more. Returns: object
introduce_parameterA
Turn a value used inside a function into a new parameter, with the original expression becoming the parameter's default. Select the expression — a name or attribute access such as a module constant or self. — with a Range (start_line/start_character to end_line/end_character, 0-based, character in UTF-16 units) inside the function body and give the parameter a name. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; this tool only changes code.
Inputs: file (required), end_line (required), start_line (required), end_character (required), +4 more. Returns: object
local_to_fieldA
Promote a local variable inside a method to an instance field: the local becomes self. everywhere in the class. Point at the local variable's name (0-based LSP line/character, UTF-16 units). Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the variable with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), root, +2 more. Returns: object
method_objectA
Convert a method into a method object: a new class whose call holds the method body, with the original method delegating to it — a stepping stone for decomposing a complex method. Point at the method name (0-based LSP line/character, UTF-16 units) and name the new class. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Read the method with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), class_name (required), +3 more. Returns: object
module_to_packageA
Convert a Python module file into a package: creates a directory of the module's name and moves the module to its init.py, rewriting relative imports to absolute. Pass the module's file path alone; no Position needed. Defaults to a Dry Run preview (created and moved entries appear in the Blast Radius); set apply=true to write. Use your LSP for navigation and reading; this tool only restructures.
Inputs: file (required), root, apply. Returns: object
moveA
Move a Python symbol or module and update imports project-wide. Three targets, one tool: a global function/class/variable at a Position moves to another module (pass destination: that module's file path); a method at a Position moves to the class held by an attribute of self (pass destination_attribute, and optionally new_name); a whole module or package moves into a package when you omit line/character entirely (pass destination: the package directory). Coordinates are 0-based LSP line/character (UTF-16 units), exactly as your LSP returns them — locate the symbol with the LSP first. Defaults to a Dry Run preview; set apply=true to write. Prefer a clean git tree before applying, since git is the reversal mechanism. Moved resources report old_path; new files report created.
Inputs: file (required), line, root, apply, +5 more. Returns: object
organize_importsA
Tidy a module's import block structurally (not formatting — black/ruff own that). Pass the file alone; no Position. One mode per call: 'organize' (default) sorts, deduplicates, and drops unused imports; 'expand_star_imports' replaces from m import * with explicit names (follow with 'organize' to prune unused ones); 'relatives_to_absolutes' rewrites relative imports as absolute; 'froms_to_imports' converts from-imports to plain imports; 'handle_long_imports' shortens deep module paths. Defaults to a Dry Run preview; set apply=true to write. An empty blast_radius means the module already conforms.
Inputs: file (required), mode, root, apply. Returns: object
renameA
Rename a Python symbol (function, class, method, variable, module-level name) and update every reference across the project — a binding-aware alternative to find-and-replace. Use your LSP to locate the symbol first; pass its file and 0-based line/character Position (character in UTF-16 units, exactly as the LSP returns). Defaults to a Dry Run that previews the full Blast Radius without writing; set apply=true to write. Supply expected_symbol (the identifier you believe is at the Position) when edits may have happened since your LSP answer — a mismatch fails safely instead of renaming the wrong code. Prefer a clean git working tree before applying, since git is the reversal mechanism; use git diff afterwards for exact text. Occurrences that cannot be proven to refer to this symbol are reported as uncertain_occurrences for you to adjudicate, never silently changed. Keep navigation and reading with your LSP, and formatting with black/ruff — this tool only changes code structure.
Inputs: file (required), line (required), new_name (required), character (required), +5 more. Returns: object
rewriteA
Rewrite every site matching a structural Pattern into a Goal, project-wide — for transformations no dedicated refactoring expresses, such as migrating a deprecated call form (${obj}.get_attribute(${key}) -> ${obj}[${key}]) or collapsing an idiom. The Pattern is Python source with ${wildcard} placeholders; the Goal is the replacement template reusing those Wildcards. Prefer a dedicated behaviour-preserving tool (rename, inline, change_signature, move, use_function) whenever one fits; use rewrite only when none does, because a Rewrite is not behaviour-preserving: you assert that Pattern and Goal are equivalent, and the tool guarantees only that it rewrites exactly the Match Sites it reports. Control over-matching with per-Wildcard Match Constraints, e.g. constraints={"obj": {"type": "myapp.models.User"}}: name / type / object / instance narrow by a symbol's dotted path (one per Wildcard), and exact: true narrows to the Wildcard's literal name. type matches instances of exactly that class; instance matches instances of its subclasses (not the base class's own) — to cover a class and its subclasses, run once with each. A constrained run reports only the sites the constraint engages (matched or unsure), not every textual match. Each Match Site reports its certainty: matched (constraints satisfied) or unsure (a constraint that cannot be established at that site, common in dynamically typed code). Unsure sites are surfaced but not rewritten, so nothing is silently skipped; add unsure: true to a Wildcard's constraints to rewrite them too — they stay flagged unsure in the result for you to audit. When the Goal introduces a name the target modules do not import, pass imports (a list of import statements, added to each changed module, deduplicated); the tool never infers imports — checking for missing names is your LSP's job, so an omitted import leaves broken code. A rewrite that would produce unparsable Python fails safely in either mode, naming the file and parse location, with nothing written. Defaults to a Dry Run that previews without writing; review every Match Site for over-matching before setting apply=true. A truncated Match Site list ('showing N of M', unsure sites first) means the audit is incomplete — tighten the Pattern or Match Constraints and preview again before a Live Run. Both modes report the file-level Blast Radius and every Match Site (file + Range in 0-based UTF-16 LSP coordinates, against the pre-apply text — live targets for your LSP on a Dry Run, audit records after a Live Run). Start from a clean git tree, since git is the reversal mechanism, and run git diff after a Live Run to verify the equivalence you asserted. Pass root (the project directory) explicitly. Keep navigation and reading with your LSP; this tool only changes code.
Inputs: goal (required), pattern (required), root, apply, +2 more. Returns: object
use_functionA
Replace code that duplicates a function's body with calls to that function, across the whole project. Point at the name of a module-level function (0-based LSP line/character, UTF-16 units); statements matching its body pattern are rewritten into calls. Defaults to a Dry Run preview; set apply=true to write. Sites that cannot be proven to match are reported as uncertain_occurrences for you to adjudicate, never silently rewritten. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the function with your LSP first; this tool only changes code.
Inputs: file (required), line (required), character (required), root, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct refactoring operation (rename, move, extract, inline, signature changes, etc.). Even potentially overlapping tools like rewrite and extract_method are clearly differentiated by their descriptions and explicit guidance on when to use the dedicated tool.
All names use snake_case and are generally descriptive, but there's a mix of grammatical patterns: single verbs (rename, move), verb-noun (extract_method, change_signature), and noun-based phrases (method_object, local_to_field). This is mostly consistent with a refactoring domain, though a more uniform verb-first pattern would be slightly clearer.
15 tools is within the desirable range for a specialized refactoring server. Each tool covers a well-known Python refactoring, and none feel redundant or unnecessary. The set is neither too thin nor bloated.
The server covers a broad spectrum of common refactorings, including structural changes (move, module_to_package), local transformations (extract_variable, local_to_field), and signature/class operations. Some advanced refactorings like 'pull up' or 'extract class' are absent, but the core workflows are well represented, and the rewrite tool provides a fallback for custom transformations.
Maintenance
Related MCP Connectors
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLMs to apply Martin Fowler's 71+ refactoring patterns to codebases through a pluggable, language-agnostic architecture. Supports previewing and applying refactorings, analyzing code smells, and inspecting code structure with safe-by-default operations.522 PyPI5MIT
- AlicenseAqualityDmaintenanceProvides Python refactoring capabilities via the Rope library, enabling AI agents to perform safe, project-wide code transformations such as renaming symbols, moving modules, and extracting methods.1039 PyPI2MIT
- AlicenseNot gradedqualityDmaintenanceMaps a local Python repository into an AST-backed symbol graph and performs verified multi-file refactors, enabling scope-aware renaming, moving, and deletion of symbols with safety checks.MIT
- FlicenseNot gradedqualityBmaintenanceEnables deterministic, AST-based rewriting of Python imports and callsites, so module paths can be re-aliased and migrated across a codebase without regex errors. It also supports dependency graph auditing and refactoring planning with token-efficient output for coding agents.7-