Weavatrix Refactor MCP server

Weavatrix 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 WEAVATRIXALLOWSOURCEEDITS unset for preview-only sessions. Preview is a read; only a confirmed apply or rollback requires the gate. Refactor does not expose Core's openrepo, 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.

.agents/plugins, then add weavatrix-refactor@weavatrix-refactor.

• Cursor: search for Weavatrix Refactor after marketplace approval.
• Codex: add the Weavatrix/weavatrix-refactor marketplace from

install weavatrix-refactor@weavatrix-refactor.

• Claude Code: add the same repository marketplace from .claude-plugin, then

Weavatrix/weavatrix-refactor, open /marketplace, and install it.

• Grok Build: run grok plugin marketplace add

The plugin opens WEAVATRIXALLOWSOURCE_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 renamesymbol and rollbacklast_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

Shortened. The full README is on GitHub.