Enables coding agents to perform transactional, evidence-backed code refactoring across multiple files with previews and rollbacks.
Also known as Weavatrix/weavatrix-refactor
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.16
- Last commit
- Nov 13, 2026
- License
- MIT
What is Weavatrix Refactor MCP?
Weavatrix Refactor enables coding agents to perform transactional, evidence-backed code refactoring across multiple files with previews and rollbacks.
Summary generated from the project's README
About Weavatrix Refactor MCP server
Weavatrix Refactor is a native MCP server designed for coding agents to perform precise, multi-file code transformations. Unlike standard agents that might guess during a rename, this server provides evidence-backed edits by using a repository graph to find symbols and preview byte-exact changes. It is intended for developers using MCP clients like Cursor, Claude Code, Codex, or Grok Build to ensure refactoring tasks are safe and verifiable.
Users can run the server via npm or Cargo, pointing it to an absolute path of a repository. The server operates with different profiles, such as a narrow rename profile that only exposes two tools, or a full refactor profile containing 11 methods. To enable writing, the WEAVATRIX_ALLOW_SOURCE_EDITS environment variable must be set to 1. Every write operation requires a single-use, plan-bound confirmation token to prevent accidental or unverified changes.
Safety is a core feature, as the server refuses to resolve ambiguous names without specific candidate IDs and uses content hashes to detect if a working tree has drifted. If a transaction goes wrong, the rollback_last_apply tool allows for a drift-safe restoration of the previous state.
What you can do with it
- 1Reducing agent context window usageDevelopers can use a specialized profile to limit the tools available to the agent, which minimizes the number of tokens used for the tool catalog.
- 2Recovering from failed refactoring attemptsIf a code change causes issues, the agent can use the rollback tool to revert the last applied transaction.
- 3Identifying uncertain code referencesWhen a refactor is not fully proven by the graph, the server reports specific locations that require manual human review.
Written from the project's README. Every use case is checked against a quote from it.
How to install Weavatrix Refactor MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Weavatrix Refactor MCP in Claude Code
$ claude mcp add weavatrix-refactor -- npx -y weavatrix-refactorInstall Weavatrix Refactor MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"weavatrix-refactor": {
"command": "npx",
"args": [
"-y",
"weavatrix-refactor"
]
}
}
}Install Weavatrix Refactor MCP in VS Code
.vscode/mcp.json
{
"servers": {
"weavatrix-refactor": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"weavatrix-refactor"
]
}
}
}Install Weavatrix Refactor MCP in VS Code CLI
$ code --add-mcp '{"name":"weavatrix-refactor","type":"stdio","command":"npx","args":["-y","weavatrix-refactor"]}'Install Weavatrix Refactor MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"weavatrix-refactor": {
"command": "npx",
"args": [
"-y",
"weavatrix-refactor"
]
}
}
}Install Weavatrix Refactor MCP in Codex
$ codex mcp add weavatrix-refactor -- npx -y weavatrix-refactorInstall Weavatrix Refactor MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.weavatrix-refactor] command = "npx" args = ["-y", "weavatrix-refactor"]
Install Weavatrix Refactor MCP in Gemini CLI
$ gemini mcp add -s user weavatrix-refactor npx -- -y weavatrix-refactorInstall Weavatrix Refactor MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"weavatrix-refactor": {
"command": "npx",
"args": [
"-y",
"weavatrix-refactor"
]
}
}
}Configuration
WEAVATRIX_ALLOW_SOURCE_EDITSSet to 1 to authorize confirmed apply operations and rollback to write source files; unset, the refactor tools stay preview-only
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableweavatrix/weavatrix-refactor is public and reachablegithub.com/weavatrix/weavatrix-refactor ↗Pass
- Package names this repository as its sourceweavatrix-refactor names weavatrix/weavatrix-refactor as sourcenpmjs.com/package/weavatrix-refactor ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/weavatrix/weavatrix-refactor ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from weavatrix-refactorPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWeavatrix Refactor
The explicit source-write layer of the Weavatrix ecosystem; Core remains read-only.
Refactor across files without letting the agent guess.
Weavatrix Refactor is a native MCP server for coding agents. It finds a symbol through the repository graph, previews byte-exact edits, reports every same-named occurrence it could not prove, and writes only after an explicit, hash-bound confirmation.
The useful difference is not “AI can rename a word.” It is that the agent gets evidence before the write and a recoverable transaction after it.
Install
Run the native binary through npm:
npx -y weavatrix-refactor mcp /absolute/path/to/repository
Or install it with Cargo:
cargo install weavatrix-refactor --locked
weavatrix-refactor mcp /absolute/path/to/repository
An MCP client can start it directly. Prefer an absolute path, or Cursor's
${workspaceFolder} so the write server never follows the host process cwd:
{
"mcpServers": {
"weavatrix-refactor": {
"command": "npx",
"args": ["-y", "weavatrix-refactor@1.0.11", "mcp", "${workspaceFolder}", "--profile=refactor"],
"env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}
}
}
}
Leave WEAVATRIX_ALLOW_SOURCE_EDITS unset for preview-only sessions. Preview is a read; only a
confirmed apply or rollback requires the gate. Refactor does not expose Core's
open_repo, so it cannot silently retarget mid-session; the launch root is the
only repository it will edit.
Install as a plugin
The repository also ships one plugin bundle for Cursor, Codex, Claude Code, and Grok Build. The plugin starts the extension-only profile, so it contributes the 11 Refactor methods without repeating Weavatrix Core's 43 read-only method definitions. Install the separate Weavatrix plugin when both surfaces are needed.
The bundled skill is optional and activates only for explicitly requested refactoring work. Its entry point stays short; each method has an individual reference card that is loaded only when needed.
- Cursor: search for Weavatrix Refactor after marketplace approval.
- Codex: add the
Weavatrix/weavatrix-refactormarketplace from.agents/plugins, then addweavatrix-refactor@weavatrix-refactor. - Claude Code: add the same repository marketplace from
.claude-plugin, then installweavatrix-refactor@weavatrix-refactor. - Grok Build: run
grok plugin marketplace add Weavatrix/weavatrix-refactor, open/marketplace, and install it.
The plugin opens WEAVATRIX_ALLOW_SOURCE_EDITS=1, but every write still needs
the exact preview's short-lived, plan-bound single-use token.
For a rename task, expose only the two tools the agent needs:
weavatrix-refactor mcp /absolute/path/to/repository --profile=rename
The rename profile keeps rename_symbol and rollback_last_apply; every
unrelated graph and refactor tool is absent and cannot be called. Omit the
option (or use --profile=refactor) for all 11 Refactor methods. The narrower
catalog reduces repeated agent context; it does not weaken preview hashes, the
write gate, the confirmation token, or rollback checks.
When Weavatrix Core is already installed as a separate MCP, expose only the 11 methods that Refactor adds:
weavatrix-refactor mcp /absolute/path/to/repository --profile=refactor
The refactor profile is the default for MCP and list-tools, including the
marketplace plugin. The former full compatibility profile has been removed
and is rejected by both commands: Refactor no longer republishes Core methods.
Install Weavatrix Core as its own MCP when read-only repository intelligence is
also needed.
A safe cross-file rename in three calls
Suppose two files declare resolveTarget. A bare name is ambiguous, so the server refuses to
pick one and returns exact ids:
// rename_symbol
{"symbol":"resolveTarget","new_name":"locateTarget","output_format":"json"}
{
"status": "NOT_FOUND",
"reason": "the name matches more than one symbol; pass one of the candidate ids",
"candidates": [
"symbol:src/core.ts#function:resolveTarget@2:1",
"symbol:src/shadow.ts#function:resolveTarget@3:1"
]
}
Retry with the intended id. The result is still read-only: it contains the edit plan, content hashes, the proven edit count, and the references the backend refused to guess at.
// rename_symbol
{
"symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
"new_name": "locateTarget",
"output_format": "json"
}
{
"status": "PLANNED",
"completeness": "PARTIAL",
"renamedEdits": 7,
"uncertainReferences": ["... three named locations ..."],
"confirmToken": "single-use-token",
"plan": {"schemaVersion":"weavatrix.edit-plan.v1","files":["..."]}
}
After reviewing the plan, repeat the same operation with the same inputs and its token:
// rename_symbol
{
"symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
"new_name": "locateTarget",
"mode": "apply",
"confirm_token": "single-use-token",
"output_format": "json"
}
{"status":"APPLIED"}
This exact flow is exercised against the real stdio MCP server. The repository fixture requires seven edits across three files, preserves four traps (a longer identifier, string, comment, and unrelated shadow), and must still compile; it scores 12/12.
What is automatic today
The eleven tools do not all claim the same level of automation:
| Level | Tools | What the agent receives |
|---|---|---|
| Complete preview/apply workflow | rename_symbol, rename_related_symbols |
A generated plan and token, then a confirmed write by repeating the same operation |
| Plan-producing | change_signature, edit_symbol, bulk_replace, organize_imports, move_file |
Byte-exact edits or a review plan; use apply_edit_plan where an edit-plan envelope is returned |
| Advisory | move_symbol, delete_readiness |
Blast radius, cycle/architecture risks, or a deletion verdict; no automatic source write |
| Safety infrastructure | apply_edit_plan, rollback_last_apply |
Verification/application of an edit-plan envelope and drift-safe restoration |
Refactor uses the Rust Weavatrix graph internally for evidence but never
exports Core methods. Install the separate Weavatrix plugin for read-only
repository intelligence. The Refactor MCP owns exactly its 11 extension
methods; --profile=rename is an optional narrower two-method workflow.
Safety model and exact limits
- Ambiguous names fail with candidate ids instead of selecting the first match.
PARTIALmeans the graph proved the edits in the plan but did not prove that no other semantic references exist.uncertainReferencesnames the places requiring review.- Every file in a plan carries a content hash. A changed working tree makes the preview stale instead of applying the old coordinates.
- Apply requires
WEAVATRIX_ALLOW_SOURCE_EDITS=1plus a short-lived, single-use token bound to that repository and exact recomputed plan. rollback_last_applyrefuses to overwrite files that drifted after the transaction.- Multi-file writes are journaled and crash-recoverable. They are not observationally atomic to unrelated processes: another process may briefly observe an intermediate filesystem state.
Only edits with proven provenance are applied. A lexical or graph backend is deliberately more conservative than a language server and must not be read as a claim of full compiler semantics.
Measured benchmark, with unlike layers kept separate
The checked-in August 2026 benchmark uses equivalent adversarial TypeScript, Rust, and Python
fixtures. Each has seven required edits, four traps, and a build/test gate. Protocol runs count
exact o200k_base initialization, catalog, request, and response tokens. Agent runs use the
actual cumulative usage reported by Codex CLI with pinned gpt-5.6-sol / medium reasoning.
No byte proxy or estimated tokens-per-second conversion is used.
The new rename-only profile kept all nine protocol runs at 12/12 while reducing fixed MCP context from 9,331 to 485 tokens. Its guided TypeScript agent A/B is:
| Arm | Correctness | Median end-to-end | Median input tokens |
|---|---|---|---|
| Naked Codex | 12/12 x3 | 42,602 ms | 72,169 |
Weavatrix 1.0.6 --profile=rename |
12/12 x3 | 48,389 ms | 108,155 |
| Weavatrix 1.0.5 full surface | 12/12 x3 | 58,719 ms | 275,784 |
| Serena | 12/12 x3 | 68,728 ms | 388,271 |
The full agent matrix is 12/12 in all 27 TypeScript/Rust/Python runs; every run also completed
operationally and passed the sanitized edit-channel audit. The deterministic protocol
matrix also exposed a language-specific Serena defect: its suggested find_symbol →
rename_symbol flow scored 7/12 on TypeScript in all three runs, while Rust and Python passed.
It also found and drove fixes for Rust macro calls and Python f-string/module-level call evidence.
On this toy TypeScript repository naked Codex is still faster and cheaper than the narrowed profile. Weavatrix's demonstrated value is preview-before-write, named uncertainty, stale-plan refusal, explicit authorization, and rollback—not a universal small-repository token win.
See the full methodology, all language medians, raw-result links, and limitations.
Contract
The 11 Refactor tool names, schemas, and result states are frozen in
contract/refactor-tools.v1.json. All refactor operations are
native Rust; the host uses the read-only
weavatrix-rust engine
internally for graph evidence without exporting its methods on the default
surface.
Versions 0.1.x used the JavaScript engine. That line continues as
weavatrix-refactor-js and keeps a
separate state directory, token store, and rollback journal.
License
MIT.
Weavatrix Refactor MCP questions
How do I add Weavatrix Refactor MCP to Claude Code?
Run claude mcp add weavatrix-refactor -- npx -y weavatrix-refactor in your terminal. Add --scope user to make it available in every project.
How do I add Weavatrix Refactor MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the server handle ambiguous symbol names?
If a name matches more than one symbol, the server refuses to guess and instead returns a list of candidate IDs for the agent to choose from.
Can I undo a refactoring operation?
Yes, the server provides a rollback tool that allows for drift-safe restoration of the code.
What is required to allow the agent to actually write changes to my files?
You must set the WEAVATRIX_ALLOW_SOURCE_EDITS environment variable to 1 and provide a single-use confirmation token for the specific plan.