MCP server

Refactron ships an MCP server that exposes one tool: verify_change. An agent proposes an edit, calls verify_change, and gets back a SAFE / UNSAFE / UNPROVEN verdict with a reproducible report, before it writes anything to your repo. This is how Refactron fits an agentic workflow: it isn’t a competing code generator, it’s the deterministic gate the generator calls to check its own work.

An AI agent calling Refactron's verify_change MCP tool and receiving a SAFE, UNSAFE, or UNPROVEN verdict before landing the change — An agent proposes a change, calls verify_change, and decides whether to land it based on the verdict.

Install (from source)

Prerequisites: Node.js ≥ 18, and for a coverage-backed SAFE verdict, Python 3.8+ with pytest and coverage.py (the same prerequisites as the quickstart).

The MCP server is unreleased; it is not in refactron@0.2.4 on npm. Build from source until the next release, which ships a refactron-mcp bin.

git clone https://github.com/Refactron-ai/Refactron_Lib_TS
cd Refactron_Lib_TS
npm install
npm run build

The server is then at dist/mcp/server.js. It speaks MCP over stdio and registers itself under the name refactron.

Register it with your client

For Claude Code:

claude mcp add refactron -- node /absolute/path/to/Refactron_Lib_TS/dist/mcp/server.js

Any MCP client works the same way: point it at node <repo>/dist/mcp/server.js as a stdio server. Use an absolute path; the server resolves your repo from the tool arguments, not its own working directory.

The `verify_change` tool

Verify a proposed change and get the verdict. The change is supplied as either full-file contents or a unified diff; one of the two is required.

Argument	Type	Required	Description
`repoRoot`	string (absolute path)	yes	The repository root to verify against.
`edits`	`[{ path, newContent }]`	one of these	Proposed full-file contents, keyed by repo-relative path.
`unifiedDiff`	string	one of these	A unified/git diff to apply and verify.
`testCmd`	string	no	Override the test command (e.g. `python3 -m pytest -q`).

The tool returns the verification report as JSON text content: the same structure verify-diff --json prints:

{
  "verdict": "SAFE",
  "gates": {
    "syntax": { "passed": true, "durationMs": 11 },
    "imports": { "passed": true, "durationMs": 8 },
    "tests": { "passed": true, "durationMs": 2980 }
  },
  "changedFiles": ["calc.py"],
  "coverage": { "tool": "coverage.py", "changedLinesCovered": true, "uncovered": [] },
  "reason": "Tests pass and the changed code is covered."
}

An agent reads verdict and decides: land on SAFE, stop on UNSAFE, and on UNPROVEN either add the test named in missingTests or ask a human.

Coverage is Python-only. A TypeScript or mixed-language change returns UNPROVEN (“coverage of the changed code could not be determined”), never SAFE. See Verdicts.

What it does and doesn’t do

Runs entirely local. The verification happens on your machine, in a shadow tree. Nothing about your code leaves it.
Never mutates your repo. verify_change reads your tree and applies the change in an isolated copy. Landing the change is the agent’s job, after a verdict it trusts.
Deterministic. The same repo state and the same diff produce the same verdict every time.

The verify-diff CLI is auth-gated (refactron login, or REFACTRON_TOKEN in CI; unauthenticated exits 7). The MCP verify_change handler runs the same local verification engine directly and makes no network calls.

Verdicts

What SAFE, UNSAFE, and UNPROVEN mean, and how coverage fuses in.

Verify a diff (CLI)

The same engine from the command line and CI.

Getting Started

Verification

Concepts

CLI

Configuration

Migration mode

Reference

Install (from source)

Register it with your client

The `verify_change` tool

What it does and doesn’t do

Next

Verdicts

Verify a diff (CLI)

​Install (from source)

​Register it with your client

​The verify_change tool

​What it does and doesn’t do

​Next

Verdicts

Verify a diff (CLI)

Install (from source)

Register it with your client

The `verify_change` tool

What it does and doesn’t do

Next